Using the functions inside KanevaWebHelper.lua requires first setting up your script so that it has access to KanevaWebHelper.lua, then simply calling the functions as you would call any other functions inside your script. These functions allow you to take advantage of all of Kaneva's 2D features, such as profiles, blasting, badges, leveling, and much more.

Setup

To setup your KanevaWebHelper there are three steps you need to take.

Tie the KanevaWebHelper.lua script to your game script

Set up the Web Helper

Set up your script to receive Web Events

The first step is simple, just execute this line of code:

kgp.scriptDoFile("KanevaWebHelper.lua")

The second step is a bit more complecated. After you connect the web helper script to your script, you need to set up the web helper. This can be done by executing the following code (The best place to do this is inside your kgp_start function):

setupWebHelper(webKey, webSecret, false, "ServerName")

The parameters of the above code are as follows:
webKey: The Web Key of your App, as found at My 3D Apps -> Manage App -> Game Information
webSecret: The Web Secret of your App, as found at My 3D Apps -> Manage App -> Game Information
debugLog: Whether or not a log should be kept for debugging. True or False
serverName: The name of the server, it can be anything you want except "Preview" or "Tech Preview."

The final step is to set up your script to receive web events. To do this you have to listen for web events in your menuevent function. The following code will do this for you.

function kgp_menuevent(user, params)
webMenuEvent(user, params)
end

You don't need to manually handle webMenuEvents. These events will automatically be sent to their respective callback functions and you can deal with them there.

Callback Functions

KanevaWebHelper functions work by sending a request for information to the website, and waiting for the website to respond. Because the website and the 3D App server do not tick at the same speed, it sometimes takes a while for the website to respond (This time is still less than a second, but code often executes in nano or picoseconds, so it does matter!). Because of this time discrepancy, KanevaWebHelper functions work on an event driven model. They send a request to the website when you call the method, and then an event created when the website responds. Between the call and the response, code will continue to execute so that your 3D App does not freeze while waiting for the website. What this means is that you cannot use the data from the function call without first checking to make sure that you actually have the data, even after you call the function. For example, you CANNOT do this:

data = getFriends(user, 1, 1, "friendsHandler")
kgp.playertell(user, data, "DEBUG", 1) -- You CANNOT do this because you DON'T know if you have data yet, data may still be nil!

This is the reason that most KanevaWebHelper methods have a parameter for what is called a "callback function." When the website responds to a request from the KanevaWebHelper, it calls the function with the same name as the callbackFunction parameter of the KanevaWebHelper function. Within this function, you can be certain that you actually have the data returned from the website, so it is best to put all of your code that requires data from the website inside your callback function, so that your code looks something like this:

function yourFunction()
data = getFriends(user, 1, 1, "friendsHandler") -- get your data outside of your handler function
end
function friendsHandler(user, data)
kgp.playertell(user, data, "DEBUG", 1) -- We KNOW we have the data here, so we can SAFELY use it.
end

In addition, you can also use some other tricks to make sure you have data. One such trick is using a conditional:

if (data ~= nil) then
--Do stuff with data
end

In fact, this should be done, as sometimes the website responds so fast that the callback function doesn't even get called! A simple way to solve this problem is to check if the data was returned immediately, and if it was, just manually call the callback function. Using these ideas, your code for getting data from the website should generally look something like this:

Parsing

All of the functions located in KanevaWebHelper.lua that return data need to have that data parsed before it will make any sense. Data is returned as an object or, more often, a table of objects. Each object within a table has several fields that all contain data related to that field. So to access any useful data, you have to pick the object in the table that you want to get data on, and then pick the field in that object that you want. For example, to get a user's first friend's username, you would first access the first friend by executing the following code:

firstFriend = friends[1]

Then you would access the username field of the friend object by executing the following code:

username = firstFriend["username"]

For a more detailed look at all of the fields and structures returned by each function, see the specific API entry for that function below.

Functions

KanevaWebHelper.lua contains the following functions for use within your 3D App.