| ||||||||||||||||||||||||||||||||||||||||||||||||||||||
 |
Web Pages (JavaScript)From $1Table of contents
This document provides the basic knowledge needed to start developing using Gigya Socialize. We will start with a basic example of a web page 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 HTML and JavaScript programming.
Basic Working ExampleRun the Example:The Example Code:<html>
<head>
<title>Gigya Socialize Example</title>
<!-- Step 1 - Including the socialize.js script: -->
<script type="text/javascript" src="http://cdn.gigya.com/JS/socialize.js?apikey=INSERT-YOUR-APIKEY-HERE" ></script>
<script type="text/javascript" >
// Step 2 - Define a configuration object. Insert your Gigya APIKey below:
var conf = {
APIKey: "INSERT-YOUR-APIKEY-HERE",
enabledProviders: "facebook,myspace"
};
function Connect()
{
// Step 3 - Define parameters object:
var params = {
callback: onConnect,
provider: "facebook"
};
// Step 4 - Calling the Socialize API method - connect:
gigya.services.socialize.connect(conf, params);
}
// Step 5 - Define callback function:
function onConnect(response)
{
if (response.errorCode == 0)
{
// Update the page with the data received in the response:
// inject the user's nickname to the "divUserName" div
document.getElementById('divUserName').innerHTML = response.user.nickname;
// inject the user's photo to the image "src" attribute.
document.getElementById('imgUserPhoto').src=response.user.photoURL;
}
else
{
//handle errors
alert("An error has occurred!" + '\n' +
"Error details: " + response.errorMessage + '\n' +
"In method: " + response.operation);
}
}
</script>
</head>
<body >
<center>
<input type="button" onclick="Connect()" value="Connect to facebook" />
<div id="UserInfo">
<div id="divUserName"></div>
<div id="divUserPhoto"><img id="imgUserPhoto" src="http://www.gigya.com/wildfire/i/transparent.GIF" onerror="this.src='http://www.gigya.com/wildfire/i/transparent.GIF'" /></div>
</div>
</center>
</body>
</html>
Note:
In order to make this code work in your environment, please:
The Example demonstrates the 5 basic steps of using the Gigya Socialize API: Step 1: Include the Socialize JS file in your pagesIncluding the Socialize JS file in your pages is a prerequisite for using Gigya Socialize API method calls. Every page that uses the Gigya Socialize API should include the Socialize Java-script library (only once) in the <HEAD> section: <script type="text/javascript" src="http://cdn.gigya.com/JS/socialize.js?apikey=INSERT-YOUR-APIKEY-HERE" ></script> Notes:
Step 2: Create a global configuration objectEvery GS API method requires a configuration object as the 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. var conf = {
APIKey: "INSERT-YOUR-APIKEY-HERE",
enabledProviders: "facebook,myspace"
};
Note: Please, replace "INSERT-YOUR-APIKEY-HERE" in the code, to your Gigya API-Key, which 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 full specifications). In the Example above, we have used two of the conf object members:
Step 3: Create a method specific params objectEvery GS API method requires a "params" object as the second parameter. The params object enfolds all the specific parameters sent to the API method. var params = {
callback: onConnect,
provider: 'facebook'
}
Each method in the Gigya Socialize API accepts different parameters, as appropriate for that method. Additionally, all the methods in the Gigya 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 4), which defines the following parameters:
This means: that the method requires a parameter called 'provider', in addition to some optional parameters. The 'var params' object in the above example conforms to this definition, and thus can be passed as the second parameter of the connect method.
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 = {
callback: onConnect,
provider: "facebook"
};
gigya.services.socialize.connect(conf, paramsConnect);
var paramsGetFriendsInfo = {
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 4: Execute the API MethodCall the API method socialize.connect. Transfer the 'conf', and 'params' objects as parameters. gigya.services.socialize.connect(conf, params);
Step 5: 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 parameter - "callback": onConnect. Thus in our example the onConnect function is called when the processing of the method socialize.connect completes: function onConnect(response)
{
if (response.errorCode == 0)
{
// Update the page with the data received in the response:
// inject the user's nickname to the "divUserName" div
document.getElementById('divUserName').innerHTML = response.user.nickname;
// inject the user's photo to the image "src" attribute.
document.getElementById('imgUserPhoto').src=response.user.photoURL;
}
else
{
//handle errors
alert("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) |
|||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
