API Documentation

From Docs.kaneva.com
Jump to: navigation, search

Contents

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

       yourGame/GameFiles/ScriptServerScripts/SavedScripts/KanevaWebHelper.lua

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.

  1. Tie the KanevaWebHelper.lua script to your game script
  2. Set up the Web Helper
  3. 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:

       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

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.

Function Name Description
setupWebHelper Initializes KanevaWebHelper.
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

Advanced

Advanced OAUTH Information

Personal tools
World Of Kaneva
Builders