Android

Skip to end of metadata
Go to start of metadata

Introduction

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.
  • Fingerprint authentication requires Android Marshmallow (v6.0) or above.
  • Android SDK has also been tested on Amazon Fire TV running FireOS v5.2.1.
  • Implementing social provider authentication in your app requires the latest native SDK of the social provider (Google/Facebook).
  • 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

Download the latest Android SDK files (zip):

  • Gigya Developer Downloads

     

If you are upgrading from a previous version, please make sure to read the SDK's Change Log.

Library Guide

Please follow these steps to integrate Gigya's Android library:

  1. Download the SDK zip file (above)
  2. Add to AndroidManifest.xml
  3. Gigya Setup - obtain your Gigya API key
  4. Initialization
  5. Logging in the User
  6. 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 ID of the activity where you initialized the SDK:

<activity
    android:name="com.gigya.socialize.android.ui.HostActivity"
	android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
    android:theme="@android:style/Theme.Translucent.NoTitleBar" />
<activity
    android:name="com.gigya.socialize.android.login.providers.WebLoginActivity"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:launchMode="singleTask"
    android:allowTaskReparenting="true" >
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="YOUR-PACKAGE-NAME" android:host="gsapi" />
    </intent-filter>
</activity>

 

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:

<uses-permission android:name="android.permission.INTERNET">
</uses-permission>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE">
</uses-permission>
	/* To enable fingerprint authentication you must request the following permission 
	   Fingerprint authentication *requires* Android v6.0 Marshmallow or above */
<uses-permission android:name="android.permission.USE_FINGERPRINT">
</uses-permission>

Gigya Setup - Obtain Your Gigya API Key

Go to the Site Dashboard page on Gigya's website. Follow the instructions in the Gigya's Setup guide to setup your application and obtain a Gigya API key.

Important: Please make sure to check the Enable mobile or desktop client applications API access checkbox in the Permissions page.

Initialization

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:

GSAPI.getInstance().initialize(this, "YOUR-API-KEY");

Note: If your site has been set up to use a data center other than us1 (default), you have to specify during initialization that API requests should be sent to a different data center domain. Your initWithAPIKey call should therefore look like this:

GSAPI.getInstance().initialize(this, "YOUR-API-KEY", "<Data_Center>");

Where <Data_Center> is:
  • us1.gigya.com - For the US data center.
  • eu1.gigya.com - For the European data center.
  • au1.gigya.com - For the Australian data center.
  • ru1.gigya.com - For the Russian data center.
  • cn1.gigya-api.cn - For the Chinese data center.

If you are not sure of your site's data center, see Finding Your Data Center.

See the initialize method reference for more information.

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.

If your site is using Gigya's RaaS, see Using Gigya Plugins in the Android SDK.

 

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):

// Present the Login user interface.
GSAPI.getInstance().showLoginUI(null, null, null);

Note: If you wish to implement the graphic design by yourself, use the login method instead.

The following providers currently support the login operation: Amazon, Blogger, Facebook, FourSquare, GooglePlus, Instagram, Kakao, LINE, LinkedIn, Livedoor, Messenger, mixi, Naver, Netlog, Odnoklassniki, Orange France, PayPalOAuth, Tencent QQ, Renren, Sina Weibo, Spiceworks, Twitter, VKontakte, WeChat, WordPress, Xing, Yahoo, Yahoo Japan.

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:

GSAPI.getInstance().setSocializeEventListener(new GSSocializeEventListener() {
    @Override
    public void onLogin(String provider, GSObject user, Object context) {
        // User was logged in
    }
    @Override
    public void onLogout(Object context) {
        // User was logged out
    }
    @Override
    public void onConnectionAdded(String provider, GSObject user, Object context) {
        // Social connection has been added to the user
    }
    @Override
    public void onConnectionRemoved(String provider, Object context) {
        // Social connection was removed from the user
    }
});

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 sendRequest method. The following code sends a request to set the current user's status to "I feel great":

// Step 1 - Defining request parameters
GSObject params = new GSObject();
params.put("status", "I feel great");  // set the "status" parameter to "I feel great"

// Step 2 - Defining response listener. The response listener will handle the request's response.
GSResponseListener resListener = new GSResponseListener() {
        @Override
        public void onGSResponse(String method, GSResponse response, Object context) {
            try {
                if (response.getErrorCode()==0) { // SUCCESS! response status = OK
                    System.out.println("Success in setStatus operation.");                
                } else {  // Error
                    System.out.println("Got error on setStatus: " + response.getLog());
                }
            } catch (Exception ex) {  ex.printStackTrace();  }
        }
    };

// Step 3 - Sending the request
String methodName = "socialize.setStatus";
GSAPI.getInstance().sendRequest(methodName, params, resListener, null);			

 

Step 1: Define the Request Parameters

Create a GSObject instance and fill it with parameters. There are two ways to define the parameters:

  1. Construct a GSObject from a JSON string. For example:

    GSObject params = new GSObject("{param1:'value1', param2:'value2', param3:'value3',...}");
    
  2. Construct an empty GSObject and add parameters using the put method:

    GSObject params = new GSObject();
    params.put("param1", "value1"); 
    params.put("param2", "value2"); 
    params.put("param3", "value3"); 
    ...
    

When a parameter is a complex object, you can use compound GSObject s or a JSON string as the value. See the example below.

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

To define a response listener, define a class that implements the GSResponseListener interface. The onGSResponse method implementation should handle the response.

class MyResponseHandler implements GSResponseListener {
        @Override
        public void onGSResponse(String method, GSResponse response, Object context) {
                 // Handle response here...
        }
}

 

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.

class UserInfoResponseHandler implements GSResponseListener {
        @Override
        public void onGSResponse(String method, GSResponse response, Object context) {
                // Handle response here...
		try {
			if (response.getErrorCode() == 0) {  // SUCCESS! response status = OK
                                String nickname = response.getString("nickname",""); // Second parameter gets default value
                                String age= response.getInt("age");
                                alert("User name: " + nickname + "; The user's age: " + age);	
			} else {
				alert("Got error on getUserInfo: "+response.getLog());
			}
		} catch (Exception ex) {  ex.printStackTrace();  }
        }
}

  

Step 3: Sending the Request

Execute the sendRequest method:

GSAPI.getInstance().sendRequest("socialize.setStatus", params, resListener, null);	

 

The parameters of the method are:

  1. method - the Gigya API method name. Please refer to the REST API reference for the list of available methods.
  2. params - the parameters object that you have created in Step 1.
  3. listener - the response listener object that you have created in Step 2.
  4. 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

// 1. Defining request parameters
GSObject userAction = new GSObject();

userAction.put("title", "This is my title");
userAction.put("userMessage", "This is my user message");
userAction.put("description", "This is my description");
userAction.put("linkBack", "http://google.com");

GSArray mediaItems = new GSArray();
mediaItems.add(new GSObject("{\"src\":\"http://www.f2h.co.il/logo.jpg\", \"href\":\"http://www.f2h.co.il\",\"type\":\"image\"}"));
userAction.put("mediaItems", mediaItems);

GSObject params = new GSObject();
params.put("userAction", userAction); // set the "userAction" parameter 

// 2. Sending 'socialize.publishUserAction' request
GSAPI.getInstance().sendRequest("socialize.publishUserAction", params, null, null);

Option B - Using a JSON String

// Defining the userAction parameter 
GSObject userAction = new GSObject("{\"title\":\"This is my title\", \"userMessage\":\"This is a user message\", 
     \"description\":\"This is a description\", \"linkBack\":\"http://google.com\", 
     \"mediaItems\":[ {\"src\":\"http://www.f2h.co.il/logo.jpg\", \"href\":\"http://www.f2h.co.il\",\"type\":\"image\"}]}"); 

GSObject params = new GSObject();
params.put("userAction", userAction);  // set the "userAction" parameter 

// 2. Sending 'socialize.publishUserAction' request 
GSAPI.getInstance().sendRequest("socialize.publishUserAction", params, null, null);

 

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.

If you do not yet have an active Facebook app please see our Facebook documentation.

For mobile specific app creation, please go to:

 

2. Setting Up Your Android Studio Project

  1. Add the Gigya SDK to your project as described above (you can use the gigya-sdk-demo project).
  2. Download and extract the Facebook SDK for Android. The latest version fully supported by Gigya is v4.13, available at https://developers.facebook.com.
  3. Import the "facebook" folder from the downloaded SDK into your workspace.
  4. Under the project properties, navigate to the "Android" tab.
  5. In the lower part of the dialog box, click "Add" and choose the "FacebookSDK" project from the workspace.
  6. 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).
  7. Add the following to your res/values/strings.xml file:
<string name="app_id">YOUR-FB-APP-ID</string>
  1. Add the following to your AndroidManifest.xml file, under the manifest tag:
<uses-permission android:name="android.permission.INTERNET"/>
  1. Add the following to your AndroidManifest.xml file, under the application tag:
<activity android:name="com.facebook.FacebookActivity"
          android:configChanges=
                 "keyboard|keyboardHidden|screenLayout|screenSize|orientation"
          android:theme="@android:style/Theme.Translucent.NoTitleBar"
          android:label="@string/app_name" />
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/app_id"/>

Adding Google Sign-In

Android enables users to set their Google account on their device. Google no longer supports app login via WebView. Using Google Sign-In is mandatory if you want users to login via Google.

Instructions for adding Google Sign-in to your Android device can be found at Google Sign-In for Android.

Using Google Sign-In requires signing your APK with a SHA-1 fingerprint. For instructions on obtaining this fingerprint, see https://developers.google.com/android/guides/client-auth.

 

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.
Example
@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
    if (GSAPI.getInstance().handleAndroidPermissionsResult(requestCode, permissions, grantResults))
        return;

    // handle other permissions result here
}
  • 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:

GSObject params = new GSObject();
params.put("provider", "googleplus");
GSAPI.getInstance().login(currentActivity, params, new GSResponseListener() {
    @Override
    public void onGSResponse(String method, GSResponse response, Object context) {
         // Handle silent login
    }
}, true, null);    

Adding LINE Native Login

The Gigya Android SDK allows you to enable LINE native login for users that have the LINE app installed.

Instructions for adding LINE Native Login to your Android device can be found at Integrating LINE Login with an Android app.

Required Steps

You must generate a package signature to place in your LINE Channels > Technical configuration > Android Package Signature field. The signature you need is the SHA1 signature, with the colons (":") removed. Both Android Package Name and Android Package Signature are required. See screenshot below.

// Code to generate Package Signature
keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
 
//Returns -> SHA1: DD:D3:1B:4.....xxxxx.....
//Convert To -> DDD31B4xxxxxxx.............xxxxxx


 

In the AndroidManifest.xml > application node, add the following:

<meta-data
	android:name="lineChannelID"
    android:value="@string/line_Channel_ID" />

In the resources > strings node, add the following:

<resources>
    ...
	<string name="line_Channel_ID">144...20</string> // LINE Channel ID
    ...
</resources>

Install the LINE Android SDK from the Channel of your LINE account, following the instructions from LINE.

To add LINE to your Android SDK project, follow the instructions at https://developers.line.me/android/development-with-sdk-v2.

Gigya's Android SDK using LINE native login was tested with LINE Android SDK v4.0.5. 

 

Adding WeChat Native Login

The Gigya Android SDK allows you to enable WeChat native login for users that have the WeChat app installed.

Required Steps

In the AndroidManifest.xml > application node, add the following:

<activity
    android:name=".wxapi.WXEntryActivity"
    android:exported="true"
    android:theme="@android:style/Theme.NoDisplay" />

Also add 

<meta-data
    android:name="wechatAppID"
    android:value="wxXXXXXXXXXXXXXX00" /> // replace this with your App ID


In the resources > strings node, add the following:

<resources>
    ...
	<string name="wechatAppID">wxXXXXXXXXXXXXXXXXXXXXXXXXXXXX00</string> // WeChat App ID
    ...
</resources>

 

Create a subfolder in the root of your project called wxapi. In that folder, create an activity named WXEntryActivity containing the following:

package // Your package name

import android.app.Activity;
import android.os.Bundle;
import com.gigya.socialize.android.login.providers.WeChatProvider;
import com.tencent.mm.opensdk.modelbase.BaseReq;
import com.tencent.mm.opensdk.modelbase.BaseResp;
import com.tencent.mm.opensdk.openapi.IWXAPIEventHandler;


public class WXEntryActivity extends Activity implements IWXAPIEventHandler {

    public void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
        WeChatProvider.api.handleIntent(getIntent(), this);
        finish();
    }

    @Override
    public void onReq(BaseReq req) {}

    @Override
    public void onResp(BaseResp resp) {
        WeChatProvider.onResponse(resp);

    }
}

It should look like this:

 

In your main project build.gradle, make sure to add 

jcenter{ url "https://jcenter.bintray.com/" } to buildscript -> repositories. It should look like this:

 

In your app build.gradle, add 

compile 'com.tencent.mm.opensdk:wechat-sdk-android-without-mta:+'   to your list of dependencies. 

Once you've tested your app, run the signature generation tool available from WeChat at https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1419319167&token=&lang=en_US.

Use the tool to generate the app signature and update your setting in the WeChat console.

Notes:

  • The signature generation tool must be installed on the mobile device.
  • You will not be able to test WeChat functionality using an emulator. WeChat requires a physical mobile device.
  • Once you update your app signature in the WeChat console, it could take a number of hours to update. If you experience problems and notice errCode -6 from WeChat while debugging, it means the signature isn't correct.

 

Integrating Your Site with the Android SDK

GSWebBridge connects between the Gigya JavaScript SDK and the Gigya Android SDK. Any WebView can be attached to the web bridge. Doing this provides the following benefits:

  • 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.
    • Captcha is only supported when using the GSPluginFragment class to load your Screen-Sets.

       

Note: For the sample code to work correctly you need to enable Javascript in the Android WebView by calling webView.getSettings().setJavaScriptEnabled(true);. For more details click here .

 

To register a web view, follow these steps:

  1. Call the attach method before the web view has started loading:

      GSWebBridge.attach(webView, new GSWebBridgeListener() { ... });              
  2. Add the following code to the beginning of your WebViewClient implementation's shouldOverrideUrlLoading method:

     public boolean shouldOverrideUrlLoading(WebView webView, String url) {
          if (GSWebBridge.handleUrl(webView, url)) {
              return true;
          }
      }              
    
  3. Detach the web view when finished:

    GSWebBridge.detach(webView); 
    

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.commentsUINote: 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.ShareBarUIPlease 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.

Important Note

When calling specific APIs using a mobile SDK, the plugin name is not always inputted the same as it is for Web 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

      #For example, with accounts.showScreenSet in the Cordova SDK you would use the following:
      gigyaClient.showPlugin('accounts.screenSet', { 'screenSet': 'Default-RegistrationLogin' },

*A notable exception to this is socialize.showLoginUI which is still showLoginUI in both Android and iOS SDKs and not currently supported in the Cordova SDK.

An example for using showPluginDialog to display GSPluginFragment modally:

 

GSObject params = new GSObject();
params.put("categoryID", "comments1");
params.put("streamID", "1");
params.put("captionText", "My Comments");
GSAPI.getInstance().showPluginDialog("comments.commentsUI", params, null, null);

 

An example for creating an instance yourself:

 

GSObject params = new GSObject();
params.put("categoryID", "comments1");
params.put("streamID", "1");
GSPluginFragment pluginFragment = GSPluginFragment.newInstance("comments.commentsUI", params);
getSupportFragmentManager().beginTransaction().add(R.id.my_layout, pluginFragment, "comments").commit();

 

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.

Sessions

The SDK handles all session information internally and enables Gigya to maintain the Login State according to your site Policy settings or Global Conf object.

Once a user is logged in via the SDK, they will be considered logged in to all available plugins that are then loaded.

Advanced Topics

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 5: the notifyLogin response data includes the following fields: sessionToken and sessionSecret.
    The following code is the implementation of steps 4,5 using Gigya's Java SDK:

    // Define the API-Key and Secret key (the keys can be obtained from your site setup page on Gigya's website).
    final String apiKey = "PUT-YOUR-APIKEY-HERE";
    final String secretKey = "PUT-YOUR-SECRET-KEY-HERE";
    
    // Defining socialize.notifyLogin request 
    String methodName = "socialize.notifyLogin";
    GSRequest request = new GSRequest(apiKey, secretKey, method);
    request.put("siteUID", "12345");  // The ID you have designated to this user
    request.put("targetEnv", "mobile");
    request.put("newUser", true);  // whether or not this user is new (registration vs login)
    
    GSResponse response = request.send();
    if (response.getErrorCode() == 0)
    { 
        String sessionToken = response.getString("sessionToken");
        String sessionSecret = response.getString("sessionSecret");
        /* send the sessionToken & sessionSecret to the client app
        ...
        */
    }
    else {
        System.out.println("Got error on notifyLogin: " + response.getLog());
    }
    
  • 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:

    // Create and store a session
    String sessionToken; // value received from server
    String sessionSecret; // value received from server
    long expirationSeconds = 6 * 60 * 60; // The session will expire 6 hours from now (setting expiration time is optional)
    GSSession session = new GSSession(sessionToken, sessionSecret, expirationSeconds);
    gsAPI.setSession(session);  // Store the session in the app's storage                                
  • 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:

 

//Stores the session data in a GSSession object
GSSession session = GSAPI.getInstance().getSession();
//Make sure session != null before validating
if (session != null && session.isValid()) {
   // User is logged in!
}                      

 

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

The Android SDK can be integrated with Gigya's Referred Traffic (link) report. Add the following code when your app is opened via deep link:

 

GSAPI.getInstance().reportDeepLink(intent);                            

 

For more information see reportDeepLink in the reference guide.

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:

  1. Upon user login, grab the "accessToken" and "secret" from the getSession method of GSSession in your mobile SDK.
  2. Over HTTPS, pass this accessToken and secret to your application server.
  3. Call getUserInfo (without specifying a UID) passing the accessToken and secret as the API Key and Secret Key (respectively) to the Gigya API.
  4. Assuming the accessToken and secret that you received is valid, you will receive a valid response from the getUserInfo call.


For API keys beginning with 3_xxx the process is as follows:

  1. Upon user login, grab the UID, Signature, and Timestamp from the response and pass it to your application server.
  2. Use your SDK's SigUtils.validateUserSignature() method, passing in the data you received from step 1 and your Gigya secret key.

 

Fingerprint Authentication Support

Overview

After the user has logged in to your app using Gigya’s Android SDK, it is now possible for them to opt-in to fingerprint authentication - a way to restore the user’s session after authenticating with a fingerprint.

 

Fingerprint Authentication Application Requirements 

Fingerprint Authentication is only available via our latest Gigya Android SDK Release v3.3.21 or above and requires Android Marshmallow (v6.0) or higher. 

To implement Fingerprint Authentication in your app, you need to add the following to your AndroidManifest.xml file.

<uses-permission android:name="android.permission.USE_FINGERPRINT">
</uses-permission>

 

Flow Explained

The end-user performs the following:

  • Opens the client's app.
  • Invokes a RaaS login (social or site).
    • After successfully logging in, a Gigya session is created via the Gigya Android SDK.
  • User chooses to opt-in to fingerprint authentication.
    • The client's app prompts for fingerprint.
      • Requires a custom UI provided by the client's app.
  • User chooses to then lock the session.
    • After locking, the user must restore the session using unlock
      • Requires a custom UI provided by the client's app.
  • User chooses to opt-out of fingerprint authentication.
    • The client's app prompts for fingerprint.
      • Requires a custom UI provided by the client's app.

Fingerprint Authentication Methods

IFingerprintOperation optIn(IFingerprintCallbacks callbacks);
	/*
	Opts-in the existing session to use fingerprint authentication.
	*/
IFingerprintOperation optOut(IFingerprintCallbacks callbacks);
	/*
	Opts-out the existing session from using fingerprint authentication.
	*/
void lock(IFingerprintCallbacks callbacks);
	/*
	Locks the existing session until unlocking it.
	No authenticated actions can be done while the session is locked.
	Invokes the onError callback if the session is not opt-in.
	*/
IFingerprintOperation unlock(IFingerprintCallbacks callbacks);
	/*
	Unlocks the session so the user can continue to make authenticated actions.
	Invokes the onError callback if the session is not opt-in.
	*/
bool isOptIn();
	/*
	Returns the indication if the session was opted-in.
	*/
bool isLocked();
	/*
	Returns the indication if the session is locked.
	*/
bool isSupported();
	/*
	Returns the indication if the fingerprint related actions are supported on the device.
	*/



IFingerprintCallbacks

onNotSupported

For a user to activate Fingerprint Authentication, their device must meet the following criteria:

  • Sensor available for reading the fingerprint.
  • Lock Screen setup.
  • A minimum of 1 (one) fingerprint already stored in the devices key store.

In Addition, before calling the relevant API, the app must hold a valid Gigya session.

If any of the conditions above aren’t met, an onNotSupported callback will be invoked with the relevant reason (of enum GigyaFingerprintManager.FingerprintError).

 

onError

The onError callback will be invoked when an unexpected exception occurred, together with the exception itself as an argument.

 

onSuccess

The onSuccess callback will be invoked after a successful fingerprint authentication.

 

Cancelling The Fingerprint Authentication Operation

Gigya’s Android SDK Fingerprint APIs return IFingerprintOperation, which can be cancelled using the cancel() method, for example:

IFingerprintOperation fpOperation = GSApi.getInstance().fingerprint.optIn(fpCallbacks);
fpOperation.cancel();

 

Code Example For Implementing Opt-In Login

public void OnOptInButtonClicked() {
	IFingerprintCallbacks fpCallbacks = new IFingerprintCallbacks() {
		@Override
		public void onNotSupported(GigyaFingerprintManager.FingerprintError reason) {
			GigyaSampleLog.i(TAG, "show - onNotSupported");
        }

		@Override
        public void onError(Exception e) {
            GigyaSampleLog.i(TAG, "show - onError");
		}

		@Override
        public void onSuccess() {
            hideFingerprintDialog();
            GigyaSampleLog.i(TAG, "show - onDone");
            showNextScreen();
        }             
	};

	IFingerprintOperation fpOperation = GSApi.getInstance().fingerprint.optIn(fpCallbacks);

	showMyFingerprintDialog(new IMyCallback {
     	@override
		public void onCancel() {
			fpOperation.cancel();
		}
	});
}

 

Frequently Asked Questions About Fingerprint Authentication

Is the fingerprint saved for the app?

  • No, Gigya's Android SDK uses the fingerprints that are stored at Androids Operating System level (using the respective native APIs).

Can I use fingerprint authentication before the user logs in?

  • No, the fingerprint authentication is an additional layer of security that can be added on top of an existing Gigya session.

Where can I get the fingerprint dialog UI?

 

 

Android Studio Demo Project

We have created for your assistance a simple Android Studio project that integrates Gigya's Android SDK, with basic usage.

Download the Gigya Demo Project.

The demo project is a simple application that implements Gigya's login and logout and supports Fingerprint Authentication (uploaded July 31, 2018).

 

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.