Cordova

Skip to end of metadata
Go to start of metadata

Introduction

The Gigya Cordova SDK enables you to create multi-platform native mobile apps maintaining only a single code base. This document provides reference for using both JavaScript and/or TypeScript with Cordova and Gigya APIs.

Required Dependencies

The Gigya Cordova SDK requires Cordova. You can use either of the supported platforms listed below for development with our SDK.

Supported Platforms

The Gigya Cordova plugin is built for:

Getting Started

To get started with your first app, follow these steps.

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.

Download The Gigya Cordova Plugin

It is not necessary to download the plugin, it will be installed directly from github when adding it to your app via the Cordova command line. However, if you want to download a standalone version, the link is here.

Install Cordova

Install Cordova (http://cordova.apache.org/) or one of the other supported platforms.

If you are using one of the other supported platforms, be sure to adjust the following code examples to reflect the correct platform name. These instructions assume you are using Cordova.

$> npm install -g cordova

 

Create your new app

$> cordova create MyNewApp

 

Change to the new directory for your app.

$> cd myNewApp

 

Edit your unique widget id in the config.xml file that was created.

<widget id="<Your-App-Id>" version="0.0.1" xmlns="http://www.w3.org/ns/widgets">

If you edit this widget ID at any time after installing the Gigya plugin (in the following step), you will need to re-install the Gigya Cordova plugin.

 

Add any required platforms.

$> cordova platform add android
$> cordova platform add ios

 

Edit your unique widget id in the config.xml file that was created.

Add any required plugins.

#### STEP 1 
#Use only *ONE* of the following commands.
 
#If you *DO NOT* want Google native login support. **You can only use this line or the line below!**
$> cordova plugin add https://github.com/gigya/cordova-plugin-gigya --save
 
#If you *DO* want Google native login support. **You can only use this line or the line above!**
$> cordova plugin add https://github.com/gigya/cordova-plugin-gigya --save --variable GOOGLE_IOS_CLIENT_ID=<Your-Google-App-ID>

 
#### STEP 2
# **You can also add either, both, or none of the following two plugins.**
 
#Required for Facebook Native Login support.
$> cordova plugin add https://github.com/gigya/cordova-plugin-facebook4 --save --variable APP_ID="<Your-Facebook-App-ID>" --variable APP_NAME="<Your-Application-Name>"
 
#Required for Google Native Login support
$> cordova plugin add https://github.com/gigya/cordova-plugin-googleplus --save --variable REVERSED_CLIENT_ID=<Your-Reverse-Client-Id(See-Below)>

 
#### STEP 3 
#Finally, when finished installing the plugins, run
$> cordova prepare

For supporting both Facebook and Google Native Login all the above plugins are required.

The Reverse Client ID required for Google, is your Google App ID re-ordered in reverse, i.e., if your app id is 12345678901234567890.apps.googleusercontent.com your reverse client id would be com.googleusercontent.apps.12345678901234567890

Set the minimum versions inside your config.xml file to avoid exceptions.

  • For Android add to the platform definition: <preference name="android-minSdkVersion" value="15" />

    <platform name="android">
        <allow-intent href="market:*" />
        <preference name="android-minSdkVersion" value="15" />
    </platform>
  • For iOS add to the platform definition: <preference name="deployment-target" value="7.0" />

    <platform name="ios">
        <allow-intent href="itms:*" />
        <allow-intent href="itms-apps:*" />
        <preference name="deployment-target" value="7.0" />
    </platform>

Ensure that gigyaClient.init() is the very first call your app makes after the device is ready.

gigyaClient.init() must be the first interaction between the Gigya SDK and your app.

For example:

function onDeviceReady() {
	gigyaClient.init('<YOUR-API-KEY>', '<Data-Center>.gigya.com');    
	console.log(gigyaClient.getVersion());
    gigyaClient.addEventListener(gigyaClient.Event.LOGIN, onLogin);
    gigyaClient.addEventListener(gigyaClient.Event.LOGOUT, onLogout);
}

The gigyaClient library is automatically installed when building your app by including the cordova-plugin-gigya plugin.

init

init - Initializes the site configuration. This must be called before any further interaction with the SDK.

Parameters

  • apiKey - string
  • apiDomain - string - Your site's Gigya Data Center URL (without protocol)

Usage

gigyaClient.init('<YOUR-API-KEY-HERE>','<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.

Gigya's Cordova SDK does not currently support the Chinese data center.

 

Logging in the User

After gigyaClient.init() the next thing that must be done is login the user.

The first interaction with Gigya after initialization must always be logging in the user. 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 logging-in is using the showScreenSet API of the Accounts namespace.

Note that this is called within the SDK as screenSet(), not showScreenSet().

Example:

gigyaClient.showPlugin('accounts.screenSet', { screenSet: 'Default-RegistrationLogin' });

You can log the user in one of two ways, either using the showPlugin method or the loginToProvider method.

showPlugin

showPlugin - Calls a particular Gigya Add-on or method.

A small number of Loyalty APIs that generate in-page popups, i.e., gm.notifications will not function.

 

Parameters

  • pluginName - string (required)
  • params - object (optional)

    Though an optional parameter within the SDK, please review the documentation of any add-ons you are using. Any parameters required by the actual API will need to be included here.

  • pluginEvents - object - This object contains a list of Add-on events.
    • Allowed keys:
      • onDismiss.
      • All other plugin events.

Native Events

  • onDismiss - a JS event that can also be triggered from the native scope when the user has canceled the dialog.
    • event - object.

Usage

gigyaClient.showPlugin('accounts.screenSet', { screenSet: 'Default-RegistrationLogin' }, {
    onLoad: function (event) { ... },           # JS event
    onError: function (event) { ... },          # JS event
    onAfterSubmit: function (event) { ... },    # JS event
    onDismiss: function (event) { ... }         # JS / native event
});

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.

loginToProvider

loginToProvider - Login to Gigya using the specified provider.

Parameters

  • provider - string (required)
  • params - object (optional)

Response

  • Returns: Thenable<IResponse>

Usage

gigyaClient.loginToProvider('facebook')
     .then(function(response) {
          alert(JSON.stringify(response.data));
     })
     .catch(function(error) {
          alert(JSON.stringify(error.data));
     });

Using loginToProvider with Facebook or Google requires the providers Native Login to be supported within your app.

Please see the following sections for the Facebook Native Login and/or Google Native Login plugins.

See also Facebook's LoginBehavior constants.

Additional Provider Configurations

Facebook Native Login

To enable Facebook native login, you must install the plugin located at https://github.com/gigya/cordova-plugin-facebook4.

Follow the plugins instructions for adding it to your app.

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

For mobile specific app creation, please go to:

Google Native Login

To enable Google native login, you must install the plugin located at https://github.com/gigya/cordova-plugin-googleplus.

Follow the plugins instructions for adding it to your app.

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

For mobile specific app creation, please go to:

Sessions

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

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

Additional Information

Continue to the Cordova SDK Reference for your preferred language:

 

 

  • No labels