The Android client library provides a Java interface for the Gigya API. The library makes it simple to integrate Gigya's service in your Android application. This document is a practical step-by-step guide for programmers who wish to integrate the Gigya service into their Android application. Follow the steps below to get started, and use the Library Reference while implementing.
For your assistance, we provide a simple demo project for Android Studio, which includes a basic Gigya SDK integration.
- Android SDK requires Android 2.3 and above.
- Android SDK has also been tested on Amazon Fire TV running FireOS v5.2.1.
- If you wish to integrate the Gigya service in your server application, please refer to our Server Side SDKs and choose the SDK that suits your development platform.
- If you want to upgrade an app that was developed with a version earlier than 3.1.1, use the Upgrade Guide to migrate your code.
Download the SDK zip file:
If you are upgrading from a former version, please make sure to read the SDK's Change Log.
Please follow these steps to integrate Gigya's Android library:
- Download the SDK zip file (above)
- Add to AndroidManifest.xml
- Gigya Setup - obtain your Gigya API key
- Logging in the User
- Use Gigya's API - Send Requests
Add to AndroidManifest.xml
Paste the following lines in your app's AndroidManifest.xml, and make sure you replace "YOUR-PACKAGE-NAME" with the package of your MainActivity:
Modify the application manifest to allow the application to make network calls. Do this by adding the following to the AndroidManifest.xml file in the app project:
Gigya Setup - Obtain Your Gigya API Key
Important: Please make sure to check the Enable mobile or desktop client applications API access checkbox in the Permissions page.
The GSAPI class is the central class of the Gigya Android SDK. GSAPI is a singleton class that provides access to the Gigya SDK services.
As a first step for using Gigya service, insert the following code in your MainActivity's onCreate method:
Logging in the User
The first interaction with Gigya must always be logging in. If the user is not logged in, you cannot access their social profile nor perform social activities, such as setting their status. The quickest way to implement login is using the
showLoginUI method of class GSAPI. The method opens a login user interface, which presents a selection of providers' icons, enabling the user to login via their social network account. Here is a screenshot of the Login UI:
Note: In order to use Facebook login you must add Facebook native login to your app. For more information go to the Facebook native login section.
The following code displays the Login UI (with default preferences):
The following providers currently support the login operation:
Facebook requires their app to have an Android definitions section. For more information see Facebook Setup - adding the Android platform.
Registering for Gigya Global Events
The Gigya SDK provides two global event listeners that handle session changes, based on whether you are using Gigya's Social Login package (GSSocializeEventListener) or Registration-as-a-Service package (GSAccountsEventListener).
For example, using GSSocializeEventListener:
Sending a Request
After you have logged in the user, you may use the GSAPI to access the user profile and perform various activities. This is implemented using GSAPI's
method. The following code sends a request to set the current user's status to "I feel great":
Step 1: Define the Request Parameters
Create a GSObject instance and fill it with parameters. There are two ways to define the parameters:
Construct a GSObject from a JSON string. For example:
Construct an empty GSObject and add parameters using the put method:
You can find the list of available Gigya API methods and the list of parameters per each method in the REST API reference.
Step 2: Define the Response Listener
The GSResponse object includes data fields. For each request method the response data fields are different. Please refer to the Gigya REST API reference for the list of response data fields per method.
For example - handling a 'getUserInfo' response: The response of 'getUserInfo' includes a 'user' object.
Step 3: Sending the Request
The parameters of the method are:
- method - the Gigya API method name. Please refer to the REST API reference for the list of available methods.
- params - the parameters object that you have created in Step 1.
- listener - the response listener object that you have created in Step 2.
- context - an optional object that is passed back with the response.
Example - Publishing User Action
The following code sample sends a request to publish a user action to the newsfeed stream on all the connected providers that support this feature.
The socialize.publishUserAction method has a complex parameter called userAction, which defines the user action data to be published. To define the userAction parameter create a GSObject object and fill it with data. There are two ways to fill the GSObject with data; you can either use the put method or construct the GSObject with a JSON string, as shown in the two examples below:
Option A - Using GSObject's put Method
Option B - Using a JSON String
To learn more about publishing user actions, please read the Advanced Sharing guide.
Configuring Native Login
Adding Facebook Native Login
1. Setting Up Facebook Native Login
Adding Facebook native login to your Android app is mandatory if you want to login via Facebook. To do so, set up your Facebook app and your Android Studio project using the following instructions.
2. Setting Up Your Android Studio Project
- Add the Gigya SDK to your project as described above (you can use the gigya-sdk-demo project).
- Download and extract the Facebook SDK for Android. The latest version fully supported by Gigya is v4.13, available at https://developers.facebook.com.
- Import the "facebook" folder from the downloaded SDK into your workspace.
- Under the project properties, navigate to the "Android" tab.
- In the lower part of the dialog box, click "Add" and choose the "FacebookSDK" project from the workspace.
- If your project already has a copy of android-support-v4.jar, remove one of the copies (either from the Facebook project or from your app's project).
- Add the following to your res/values/strings.xml file:
- Add the following to your AndroidManifest.xml file, under the manifest tag:
- Add the following to your AndroidManifest.xml file, under the application tag:
Adding Google Sign-In
Android enables users to set their Google account on their device. Android applications can access the native account to authenticate the user without requiring the user to enter their credentials. We recommend utilizing this functionality on your Android app.
Adding Google Sign-in to your Android device is optional, and if you choose to add it, please follow the steps found at Google Sign-In for Android.
If you are currently using the older Google+ native login in Gigya's Android SDK v3.3.1 and earlier, you must upgrade to v3.3.2 or later before January 1, 2017, when Google will sunset their Google+ native login which has been replaced by Google Sign-In.
Using Google Sign-in on Android 6.0 (Marshmallow) requires that you ask the user for the 'GET_ACCOUNTS' permission at run-time.
To do so:
- Implement the onRequestPermissionsResult handler on the current Activity, from which the login request was sent.
- Login & addConnection methods now requires a reference to the current Activity.
- When login using plugin as dialog (e.g., ScreenSet), there's no need to handle onRequestPermissionsResult, since the current Activity is part of the GigyaSDK and the handler exists internally.
Google Cross Platform SSO
Gigya's Android SDK supports Google Sign-in cross-platform SSO. To see Google Sign-in documentation, click here.
If a user opens your Google Sign-in application under Android, while the same user is logged in to that application on another platform, Gigya will identify that the user is already logged in and grant them access.
To implement this, call GSAPI's login method with the silent parameter set to true. The SDK will attempt to log the user in without displaying any user interface, and invoke the response listener upon success:
Integrating Your Site with the Android SDK
- Session state will be synchronized. If the user is logged in and the session is active in the Android SDK - he will be automatically logged in in the JS SDK.
- Any API requests by the JS SDK will be routed through the Android SDK, using the Android SDK session.
- Any login process invoked by the JS SDK will be handled by the Android SDK, creating a seamless login experience - using the web browser or the provider's native login.
To register a web view, follow these steps:
Call the attach method before the web view has started loading:
Add the following code to the beginning of your WebViewClient implementation's shouldOverrideUrlLoading method:
Detach the web view when finished:
Using Gigya Plugins in the Android SDK
GSPluginFragment is a custom fragment that renders Gigya JS Plugins and integrates them seamlessly with the Gigya Android SDK.
GSPluginFragment currently supports the following plugins, listed with their plugin name:
- Comments - comments.commentsUI. Note: commenting is supported, but sharing the comment to social networks is not supported.
- Ratings & Reviews - comments.commentsUI (Reviews mode is handled in the console) , comments.RatingUI for ratings plugin.
- RaaS Screen-Sets - accounts.screenSet.
- Share Bar - socialize.ShareBarUI. Please note: the share buttons that implement providers' own (native) buttons are not supported. These include Facebook's native Facebook Like button, Twitter's Tweet button, and more. For the full list please refer to the shareButtons parameter in socialize.showShareBarUI .
You can either use showPluginDialog to display GSPluginFragment modally, or alternatively, for more control and customization, you can create an instance yourself and add it to your layout.
When calling specific APIs using an SDK, the plugin name is not always inputted the same as it is for JS or REST.
Whenever you are using an API that begins with 'show', i.e., showScreenSet, showCommentsUI, etc.
- Do not include the 'show' segment of the API name and convert the new first letter of the API to lower-case:
- showScreenSet will be screenSet
showCommentsUI will be commentsUI
*A notable exception to this is socialize.showLoginUI which is still showLoginUI in both Android and iOS SDKs. Though this method is not currently supported in the Cordova SDK.
An example for using showPluginDialog to display GSPluginFragment modally:
An example for creating an instance yourself:
You can also handle plugin events (for example, commentSubmitted) by implementing the GSPluginListener interface and passing it as a parameter.
For more information see reportDeepLink in the reference guide.
Once a user is logged in via the SDK, they will be considered logged in to all available plugins that are then loaded.
Site Login - Synchronizing with Gigya Service
When a user authenticates using your existing login form or when a new user registers using site registration, it is important to notify Gigya of the user's new state, so as to provide consistent user experience and have access to Gigya's API. The following chart diagram illustrates the implementation:
- Steps 1-3: your standard site login/registration flow.
- Step 4: call the socialize.notifyLogin API method. Pass the following parameters:
- siteUID - set this parameter with the user ID that you have designated for this user in your database. The notifyLogin call registers a new user in Gigya in case the siteUID provided is new, or reconnects a returning user in case the siteUID already exists in our records.
- newUser - If it is a new user set the newUser parameter to 'true'. This will enable Gigya to distinguish between a new site user and a returning site user, allowing Gigya to analyze users' login/registration behavior with or without Social Login and compare the ratio.
- Step 6: pass the sessionToken and sessionSecret to your client app.
Step 7: create a session on your client app using the sessionToken and sessionSecret fields, so as to maintain the client application synchronized with the user state. Use the
GSAPI.setSession (GSSession session)method:
- Step 8: As long as the session is valid (not expired and has valid token), the client app will have access to Gigya's API.
Checking the Session Status
As user sessions can expire from various reasons (like a timeout), and Gigya's API is only available through a valid session, it is recommended to perform validity checks before calling API methods on an uncertain session status.
The following code validates the current session:
A call to GSAPI's getSession() method returns a GSSession Object that holds data for the current session. Calling getSession() on an invalid session may return a null value, so you should check that the session object is not null before calling the isValid() function. If the session is valid and the user is logged in isValid() will return true. Otherwise the return value is false.
Tracking Deep Link Referrals
Verifying Signatures from Mobile Logins
The process for verifying UID signatures generated from logins via our mobile SDKs depends on whether your API key begins with 2_xxx (older) or 3_xxx (newer).
For API keys beginning with 2_xxx the process is as follows:
- Upon user login, grab the "accessToken" and "secret" from the getSession method of GSSession in your mobile SDK.
- Over HTTPS, pass this accessToken and secret to your application server.
- Call getUserInfo (without specifying a UID) passing the accessToken and secret as the API Key and Secret Key (respectively) to the Gigya API.
- Assuming the accessToken and secret that you received in iOS is valid, you will receive a valid response from the getUserInfo call.
For API keys beginning with 3_xxx the process is as follows:
- Upon user login, grab the UID, Signature, and Timestamp from the response and pass it to your application server.
- Use your SDK's SigUtils.validateUserSignature() method, passing in the data you received from step 1 and your Gigya secret key.
Android Studio Demo Project
We have created for your assistance a simple Android Studio project that integrates Gigya's Android SDK, with basic usage.
The demo project is a simple application that implements Gigya's login and logout and retrieves the user's friends list.