| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
Flash (ActionScript3)From $1Table of contents
Contents
This document provides the basic knowledge needed to start developing using Gigya Socialize. We will start with a basic example of a widget that uses Gigya Socialize - the Gigya Socialize "Hello World", and a guide for using Gigya Socialize API methods. We highly recommend reading this document before starting to code. This document is designed for people familiar with ActionScript3 programming.
Basic Working ExampleNote: the following example is built using the Flash CS3 IDE. If you are using an alternative development environments, you will still find this example useful, since the core code is identical.
Run the Example:The Example Source (FLA)You may download the source of the running example here. The zip file includes the fla file of the above example and the gigya.swc file which must be included in the project (this issue is further explained below). The Example Code:We have created an AS3 FLA file and placed three UI components:
The following is the code entered in the main document Actions-Frame: connectBtn.enabled = false;
label.text = 'Loading Socilaize...';
connectBtn.addEventListener(MouseEvent.CLICK, onConnectBtnClick);
// Step 2 - Define a configuration object. Insert your Gigya APIKey below:
var conf:Object = {
APIKey: 'INSERT-YOUR-APIKEY-HERE',
mcRoot: root,
enabledProviders: '*'
}
// Step 3 - Load socialize service
// 3.1 Create the load-parameters object
var loadParams:Object = {
services:'socialize',
callback:onGigyaInit
}
// 3.1 Load the services
gigya.load(conf,loadParams);
// 3.2 Wait for the load to complete and handle failures\success
function onGigyaInit(response): void
{
if (response.hadError) {
// handle failure
label.text = 'An error has occurred while attempting to load Socialize service';
} else {
// successful load
label.text = '';
connectBtn.enabled = true;
}
}
function onConnectBtnClick(event: MouseEvent): void {
// Step 4 - Define parameters object:
var connectParams:Object = {
callback: onConnect,
provider: 'facebook'
};
// Step 5 - Calling the Socialize API method - connect:
gigya.services.socialize.connect(conf, connectParams);
}
// Step 6 - Define callback function:
function onConnect(response: Object): void {
if (response.errorCode == 0)
{
// inject the user's nickname to the label
label.text = response.user.nickname;
// inject the user's photo to the image "source" attribute.
image.source=response.user.photoURL;
} else {
//handle errors
label.text = "An error has occurred!" + '\n' +
"Error details: " + response.errorMessage+ '\n' +
"In method: " + response.operation;
}
}
Note:
In order to make this code work in your environment, please:
The Example demonstrates the 6 basic steps of using the Gigya Socialize API: Step 1: Include the gigya.swc file in your projectDownload the gigya.swc file from the Gigya website. Unzip the file and include it in your project by placing the file in your working directory and performing the following steps in your Flash project: Click "File" > "Publish Settings..." > select the "Flash" tab > click the "Setting..." button > select the "Library path" tab > click the "Browse to SWC file" button (red icon) > browse and select gigya.swc file > click 'OK' on both windows.
The gigya.swc file provides boot strapping code for the Gigya API and should never be changed. We encourage you to get the latest version of this file whenever you make changes to your project so that it would include the latest improvements and fixes. Note: The gigya.swc will implicitly give the Gigya API code permissions to access your SWF's data members. If the Gigya API is used in a SWF which is loaded by another SWF, or within an hierarchy of other SWFs, then all the parent SWFs must give Gigya permissions to access them as well. Implement that by adding the following lines of code: Security.allowDomain("cdn.gigya.com");
Step 2: Create a global configuration objectEvery GS API method requires a configuration object as its first parameter. This object is used for storing global configuration parameters, which are common to all the API calls and are expected to remain static for the lifetime of the application. The conf object can be created once and passed to all the method calls in the lifetime of the application. Best practice is, to define one global conf object and use it throughout the application: // Step 2 - Define a configuration object. Insert your Gigya APIKey below:
var conf:Object = {
APIKey: 'Put Your APIKey here',
mcRoot: root,
enabledProviders: 'facebook,myspace'
}
Note: Modify "Put Your APIKey here" in the code, to your Gigya API-Key. A Gigya API-Key can be obtained on the Site Setup page on Gigya website.
The conf object consists of various members (please refer to the API Reference for the full specification). In the Example above, we have used three of the conf object members:
Step 3: Load Socialize serviceThe Socialize service must be loaded prior to using the Socialize API methods. Loading the Socialize service is done by executing the gigya.load(conf, params) method and waiting for your callback method to be called with an indication if the load operation being successful or not. Note: You should not call any API method before your load callback method is called and an indication of successful load is received.
Step 3.1: Create a load's params objectEvery GS 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 our example conforms to this definition, and thus can be passed as the second parameter of the gigya.load method, as shown below. // 3.1 Create the load-parameters object
var loadParams:Object = {
services:'socialize',
callback:onGigyaInit
}
Step 3.2: Execute the gigya.load MethodCall 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 OperationThe 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
label.text = 'An error has occurred while attemting to load Socilaize service';
} else {
// successful load
label.text = '';
connectBtn.enabled = true;
}
}
The callback function is a developer-defined function. The only constraint is on its signature - Gigya Socialize 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:
The callback function should initially check the value of hadError field as indication for load failure\success.
Step 4: Create a method specific params objectAs mentioned above, every GS API method requires a "params" object as the second parameter. The params object enfolds all the specific parameters sent to the API method. // Step 4 - Define parameters object:
var connectParams:Object = {
callback: onConnect,
provider: 'facebook'
};
Each method in the Gigya Socialize API accepts different set of parameters, as appropriate for that method. Additionally, all the methods in the Gigya Socialize API accept the following common parameters:
The API Reference, specifies the list of parameters ("params" object members) which each API method accepts - some are required and some are optional. In our Example we used the method socialize.connect (in Step 5), which defines the following parameters:
This means: that the method requires a parameter called 'provider', in addition to some optional parameters. The 'var connectParams' object in the above example conforms to this definition, and thus can be passed as the second parameter of the connect method, as shown below.
Note: Some of the parameters may appear both in the Conf object and in the method's specific "Params" object. An example for that is the cid parameter. In such case the value from the Params object overrides the value from the Conf object.
var conf = { ..., cid: "abc" }
var params = { ..., cid: "xyz" }
gigya.services.socialize.connect(conf,params); // The cid "xyz" will be used.
This can be useful, for defining global default in the Conf object, and overriding the default in some methods, by setting a different value in the method's Params object.
Best practiceIt is important to define an independent params object per method call, as opposed to editing and reusing the same object for several method calls. This is due to the fact that the methods are running asynchronously. Best practice is to concatenate the method name to the params object name. For example: var paramsConnect:Object = {
callback: onConnect,
provider: 'facebook'
};
gigya.services.socialize.connect(conf, paramsConnect);
var paramsGetFriendsInfo:Object = {
detailLevel: 'extended',
callback: getFriendsResponse
};
gigya.services.socialize.getFriendsInfo(conf, paramsGetFriendsInfo);
Another option is to define the params object inline. For example:gigya.services.socialize.connect(conf, {
callback: onConnect,
provider: 'facebook'
});
gigya.services.socialize.getFriendsInfo(conf, {
detailLevel: 'extended',
callback: getFriendsResponse
});
Step 5: Execute the API MethodCall the API method socialize.connect. Transfer the 'conf', and 'connectParams' objects as parameters. // Step 5 - Calling the Socialize API method - connect: gigya.services.socialize.connect(conf, connectParams);
Step 6: Define a Callback function (optional)The API uses an asynchronous programming model, meaning - that socialize.connect 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:onConnect. Thus in our example the onConnect function is called when the processing of the method socialize.connect completes: // Step 6 - Define callback function:
function onConnect(response: Object): void {
if (response.errorCode == 0)
{
// inject the user's nickname to the label
label.text = response.user.nickname;
// inject the user's photo to the image "source" attribute.
image.source=response.user.photoURL;
} else {
//handle errors
label.text = "An error has occurred!" + '\n' +
"Error details: " + response.errorMessage + '\n' +
"In method: " + response.operation;
}
}
The callback function is a developer-defined function. The only constraint is on its signature - Gigya Socialize 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. In particular, the callback function should verify that the errorCode field of the response object equals zero 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. In our Example - the socialize.connect method defines the following additional member:
Note - The 'user' parameter is of the type 'User object'. Please refer to the specification of User object in the API reference section.
Notice how we used the response object in the implementation of onConnect(response) function: We used some of the common data members: response.errorCode, response.errorMessage, response.operation We also used the response.user data member, which is specific to the connect method. response.user is of the type User object, and thus includes the members - nickname and photoURL, which are used in the example: response.user.nickname, response.user.photoURL
What's Next?You should now be ready to start using the basic features of Gigya Socialize API.
< Back to 'Developer's Guide' root | Next to 'Using Socialize Widgets' >
Tags:
Files (0) |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
