Social and Viral API Use
Kaneva's social and viral API is contained within the file kanevaWebHelper.lua. This file is automatically placed in your 3D App when you create the app, and is located at
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.
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:
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.
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:
function yourFunction() data = getFriends(user, 1, 1, "friendsHandler") -- get your data outside of your handler function if (data ~= nil) then friendsHandler(user, data) end end function friendsHandler(user, data) kgp.playertell(user, data, "DEBUG", 1) end
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
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.
KanevaWebHelper.lua contains the following functions for use within your 3D App.
|sendBlast||Sends a Blast to the user's profile|
|sendBlastComment||Send a comment to a blast on the user's profile.|
|getProfile||Gets a user's profile|
|getBlasts||Gets a list of blasts from a user|
|getBlastReplies||Gets a list of replies to a given blast|
|getFriends||Gets a list of the user's friends, and details about them|
|getMedia||Gets a list of media assets|
|getApps||Gets a list of the user's 3D Apps|
|getPlaylists||Gets the list of playlists associated with this 3DApp.|
|addPlaylist||Creates a new playlist.|
|deletePlaylist||Deletes a new playlist.|
|addToPlaylist||Adds media to a playlist.|
|deleteFromPlaylist||Removes media from a playlist.|
|uploadYoutube||Adds a YouTube video to your media library.|
|earnLeaderBoard||Updates the leaderboard with the user's score|
|getLeaderBoard||Retrieve the leaderboard for this 3D App|
|earnLevel||Updates the player's level for your 3D App|
|getBadgesForApp||Gets the badges available in the App.|
|getBadgesForUser||Gets the badges that a user has earned.|
|getEarnedBadgesForUser||Gets the list of badges earned by a user.|
|earnBadge||Gives the user a new badge|