Developer's Guide

Definitions:

Callback function - Callback functions are used to return results of Gigya ActionScript API function calls when the method is expected to take a long time to execute. This programming model is known as asynchronous because the result of a function call is not returned when the function call returns but instead it is returned after a while by calling the associated callback function.

Context object - Context objects are commonly used in asynchronous programming to allow the application to store and pass information between callbacks. All the Gigya ActionScript API method calls can accept a context object and then pass it back to the application as a parameter of the callback function. Gigya ActionScript API never attempts to read the context object and it is left to the application to create and interpret its meaning.

Step 3.1: Create a load's params object

Every Gigya API method requires a "params" object as its second parameter. The params object enfolds all the specific parameters sent to the API method. 

The method gigya.load expects the following members in the params object:

In other words: the gigya.load method requires a parameter called 'services', in addition to the optional parameters 'callback' and 'context'. 

The 'var loadParams' object in the following example conforms to this definition, and thus can be passed as the second parameter of the gigya.load method:

// 3.1 Create the load-parameters object
var loadParams:Object = {
    services: 'social,reports',
    callback: onGigyaInit
}

Step 3.2: Execute the gigya.load Method

Call the API method gigya.load. Transfer the 'conf', and 'params' objects as parameters:

// 3.2 Load the services
gigya.load(conf,loadParams);

Step 3.3: Define a Callback Function for the Load Operation

The API uses an asynchronous programming model, meaning - that gigya.load will run in the background and call a developer provided callback function when it completes.

Recall that we specified the callback function in the "callback" attribute of the params object -  callback:onGigyaInit. Thus in our example the onGigyaInit function is called when the processing of the method gigya.load completes:

// 3.3 Wait for the load to complete and handle failure\success
function onGigyaInit(response:Object): void
{
    if (res.hadError) {
        // handle failure
        trace('An error has occurred while attemting to load Socilaize service');
    } else {  
        // successful load
        //continue knowing that the required services are now available.
        //please note that some services may require initialization after they are loaded.
    }
}

The callback function is a developer-defined function. The only constraint is on its signature - Gigya expects the callback function to receive one parameter, which is the response object.

The response object contains the values returned from the API method. The callback function should analyze the response object and handle it appropriately. For example - display an error message to the end-user if an error has occurred.

The response object for the gigya.load operation include the following members:

• hadError - a boolean indicating if an error has occurred.
• errorCode - an error code or 0 if no error has occurred.
• errorMessage - a string containing the description of the error.
• errorData - this object provides additional data about the error. It includes the following members:
  
  • failedServices - a comma separated list of services that failed to load.
  • detailedErrors - a string with additional details about the errors causing each failure respectively.
• requestParams - a reference to the "params" object that was passed to the original call. This object includes the following members:
  • services
  • callback - a reference to the callback function.
• context - a reference to the "context" object that was passed to the original call.

The callback function should initially check the value of hadError field as indication for load failure\success.

Step 4.1: Create a method specific params object

As mentioned above, every Gigya API method requires a "params" object as the second parameter. The params object enfolds all the specific parameters sent to the API method. Each method in the Gigya API accepts different set of parameters, as appropriate for that method. Additionally, all the methods in the Gigya API accept the following common parameters:

• callback - A reference to a callback function. Gigya will call the specified function along with the results of the API method when the API method completes.
• context - A developer-created object that will be passed back unchanged to the application as one of the fields in the result object.

The API Reference, specifies the list of parameters ("params" object members) which each API method accepts - some are required and some are optional.

var paramsGetGeo:Object = {
     callback: getGeoResponse,
     cid: '123'
};      
gigya.services.env.getGeo(conf,paramsGetGeo);

var paramsGetFriends:Object = {
     callback: getFriendsResponse
};      
gigya.services.social.getFriends(conf, paramsGetFriends);

gigya.services.env.getGeo(conf, {         
     callback: getGeoResponse,
     cid: '123'
 });

gigya.services.social.getFriends(conf, {
     callback: getFriendsResponse
    });

Step 4.2: Execute the API Method

All the methods in the Gigya API (except the gigya.load method) have a common signature:

gigya.services.service_name.method_name(conf,params);

Both "conf" and "params" are actually objects that contain multiple members used for configuring the method. We choose to use these two objects instead of passing paremeters in the classical way to give us flexibility in adding new parameters without breaking older code.

The API uses an asynchronous programming model where operations are started by calling and API method, run in the background and call a user supplied callback function when they are complete. The callback function is called regardless if the operation succeeded of failed, so the application can handle both cases gracefully. A single callback function may be used to handle multiple events, in this case the application can set a context object when it calls the API and the callback function can later use this object to determine the context in which it was called and react accordingly.

Step 4.3: Define a Callback function (optional)

When an API call is made it returns immediately and starts processing the request in the background. When the processing is complete the user provided callback function is called with the purpose of passing the API method's return values. The callback function is a developer-defined function. The only constraint is on its signature - Gigya expects the callback function to receive one parameter, which is the response object.

The response object contains the values returned from the specific API method. The callback function should analyze the response object and handle it appropriately. For example - display an error message to the end-user if an error has occurred. In particular, the callback function should verify that the status field of the response object is "OK", as any other value indicates an error.

Every response object contains common members (values which are returned by all API methods).

The common members of the response object are specified in the following table: 

Each API method defines its additional members in the response object. Method specific members are detailed in the reference section for each API call.

For example, in the following code we define a callback method for the social.getFriends API method:

// Step 4.3 - Define callback function: 
function getFriendsResponse(response: Object): void {
    if (response.hadError)
    {   
        // handle errors        
        trace(response.errorMessage);
    } else {
        //Use the friends data
        var friends:Array = response.friends.asArray();
    }
}

Notice how we used the response object in the implementation of getFriendsResponse(response) function:

We used some of the common data members: response.hadError, response.errorMessage.

We also used the response.friends data member, which is specific to the getFriends method.