iOS

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:

Getting Started

To get started, you'll need to follow these steps:

#import <GigyaSDK/GSAPI.h>

Initialization - Create an Instance of GSAPI Class

Class GSAPI is the central class of the Gigya iOS SDK. The instance of the GSAPI class provides access to the Gigya service.
As a first step for using Gigya service, create an instance of GSAPI in your app's AppDelegate didFinishLaunchingWithOptions method:

gsAPI = [[GSAPI alloc] initWithAPIKey:@"PUT-YOUR-APIKEY-HERE"];

Note: You should only call initWithAPIKey once.

Class GSAPI's initialization method receives one parameter:

• APIKey - your Gigya API key, which you have obtained in the previous step.

You should create only one GSAPI object, and retain it for the lifetime of your application.
 

Logging in the User

The first interaction with Gigya must always be logging in. If the user is not logged in, you cannot access her social profile nor perform social activities, such as setting her status. The quickest way to implement logging-in 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 his social network / webmail account. Here is a screenshot of the login UI:

The following code displays the login UI (with specified login providers ):

// Present the Login user interface.
GSObject* pParams = [[GSObject alloc] init];
[pParams putStringValue:@"facebook,twitter,google" forKey:@"enabledProviders"];
[gsAPI showLoginUI:pParams ViewController:self delegate:nil context:nil];
[pParams release];

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

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 the 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 *pParams = [[GSObject alloc] init];
[pParams putStringValue:@"I feel great" forKey:@"status"];     // set the "status" parameter to "I feel great"

// Step 2 - Sending the request
[gsAPI sendRequest:@"socialize.setStatus" params:pParams delegate:nil context:nil]
[pParams release];

GSObject *pParams = [GSObject objectWithJSONString:@"{param1:'value1', param2:'value2', param3:'value3',...}"];

GSObject *pParams =[[GSObject alloc] init];
[pParams putStringValue:@"value1" forKey:@"param1"];
[pParams putStringValue:@"value2" forKey:@"param2"];
[pParams putIntValue:1000 forKey:@"param3"];
...
[pParams release];

[gsAPI sendRequest:@"socialize.setStatus" params:pParams delegate:nil context:nil]

@interface YourClass UIViewController<GSResponseDelegate> {
...

- (void) gsDidReceiveResponse:(NSString*)method response:(GSResponse*)response context:(id)context
{
         
	 NSString *resMsg = [NSString stringWithFormat:@"\n errorCode=%d\n errorMessage=%@\n response.data=%@\n", 
					   response.errorCode, response.errorMessage, [response.data stringValue]];
	 NSLog(@"gsDidReceiveResponse:\nMethod=%@\nResponse=%@\n context=%@",method,resMsg,context);
}

// in this example 'self' conforms to the GSResponseDelegate protocol 
[gsAPI sendRequest:@"socialize.setStatus" params:pParams delegate:self context:nil]

- (void) gsDidReceiveResponse:(NSString*)method response:(GSResponse*)response context:(id)context
{
        // Handle response here...
        if (response.errorCode==0) {  // SUCCESS! response status = OK			
                NSString * nickname = [response.data getString:@"nickname"];
                NSString * age = [response.data getString:@"age"];
	        NSLog(@"User name: %@\nThe user's age: %@\n", nickname, age);
	} else {
		NSLog(@"Got error on getUserInfo: %@", response.errorMessage);
	}
        
}

Option A - Using GSObject's put Method

// 1. Defining request parameters
GSObject *userAction =[[GSObject alloc] init];

[userAction putStringValue:@"This is my title" forKey:@"title"]; 
[userAction putStringValue:@"This is my user message" forKey:@"userMessage"]; 
[userAction putStringValue:@"This is my description" forKey:@"description"]; 
[userAction putStringValue:@"http://gigya.com" forKey:@"linkBack"]; 

GSObject *image = [[GSObject new] autorelease];   // create a media item of type image to add to the user action
[image putStringValue:@"http://www.infozoom.ru/wp-content/uploads/2009/08/d06_19748631.jpg" forKey:@"src"]; 
[image putStringValue:@"http://www.gigya.com" forKey:@"href"]; 
[image putStringValue:@"image" forKey:@"type"]; 

NSArray *mediaItems = [NSArray arrayWithObject:image];  // create media items array and add the image object to it

[userAction putNSArrayValue:mediaItems forKey:@"mediaItems"]; 

GSObject *pParams = [[GSObject alloc] init];

[pParams putGSObjectValueGSObjectGSObject:userGSObjectiuserAuserActioneforKeyerAuserActionserAuserActiuserAuserActionametering 'socialize.publishUserAction' request
[gsAPIgsAPIRsendRequestcialize.publishUserAction" paramparamsapParamsgate:npParamsext:nil];

[userAuserActiuserAuserActionaseamsapParapParamsasepParams

Option B - Using a JSON String

// 1. Defining request parameters 
NSString *actionStr = @"{\"title\":\"This is my title\", \"userMessage\":\"This is a user message\", \"description\":\"This is a description\",\"linkBack\":\"http://www.gigya.com/\", \"mediaItems\":[ {\"src\":\"http://www.f2h.co.il/logo.jpg\", \"href\":\"http://www.gigya.com/\",\"type\":\"image\"}]}";
	
GSObject *userAction = [GSObject objectWithJSONString:actionStr];
	
GSObject *pParams = =[[GSObject alloc] init];
[pParams putGSObjectValueGSObjectGSObject: useGSObjecttiuserAuserActioneforKeyerAuserActionuserActionserAuserAcuserAction 


// 2. SeuserAuserActionameteruserActionishUserAction' request
[gsAPIgsAPIRsendRequestcialize.publishUserAction" paramparamsapParamsgate:nil context:nil]; 

[pParappParamsse];pParapParamsasepParams

To learn more about publishing user actions, please read the Advanced Sharing guide.

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.
  • targetEnv - set this parameter to "mobile". This determines the server response data fields.
  • 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 method:
  

  NSString* sessionToken; // initialize with the sessionToken received in response of notifyLogin
  NSString* sessionSecret; // initialize with the sessionSecret received in response of notifyLogin
  NSDate* expirationTime = [NSDate dateWithTimeIntervalSinceNow:36000];
  GSSession* session = [[[GSSession alloc] initWithSessionToken:sessionToken sessionSecret:sessionSecret expirationTime:expirationTime] autorelease];
  [gsAPI setSession:session];

• 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.

Adding Facebook Native Login

Gigya's SDK allows you to use the native login feature from Facebook's SDK. Utilizing this functionality on your app, your users will have one-click login access to your application. 

Your Facebook application must be configured for native mobile login. To do this configure your Facebook app according to the steps described in Facebook's documentation.

Follow these steps to utilize Facebook's native login for iOS:

1. Add the following two parameters to your app's .plist file:

• FacebookAppID - your Facebook's application ID 

• FacebookDisplayName - your Facebook's application Display Name as you configured in the App Dashboard

2. Create an array key called URL types with a single array sub-item called URL Schemes. Give this a single item with your app ID prefixed with fb. This is used to ensure the application will receive the callback URL of the web-based OAuth flow. For example, if your application's id is 1234, the value should be "fb1234".

3. Add the following to your app's AppDelegate:
   

   - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
   {
       if(viewController.m_pGSAPI != nil)
           return [viewController.m_pGSAPI handleOpenURL:url sourceApplication:sourceApplication annotation:annotation];
       return NO;
   }

    

4. When calling showLoginUI, make sure to pass "facebook" in the enabledProviders parameter:

   GSObject *pParams = [[GSObject alloc] init];
   [pParams putStringValue:@"facebook" forKey:@"enabledProviders"];
   [gsAPI showLoginUI:pParams delegate:self context:nil];
   [pParams release];

   
   If you have multiple facebook apps using the same facebook app ID, please pass the facebook local app ID (facebookLocalAppId parameter) to these methods as well. In such case, you should also concat the local app ID to the app ID in the .plist file, as required by Facebook. 
   
   Note: If you want certain permissions, you must specify them in the facebookReadPermissions parameter, using Facebook's permission strings as defined in Facebook's documentation.
    
5. On success of Facebook login, Gigya will initialize the Facebook SDK's active session, which is accessible at FBSession.activeSession. You can now use Facebook's SDK functionality with this created session. 
   The Facebook login token will be cached, and the session will be automatically opened the next time the app is opened. In order to clear the session, use the GSAPI logout method.

Adding Google+ Native Login

Gigya's SDK allows you to use the native login feature from the Google+ SDK. Utilizing this functionality on your app, your users will be able to authenticate through the Google+ iOS app. 

To do this configure a Google+ APIs Console project, according to the steps described in the documentation for Google+.

Follow these steps to utilize the Google+ native login for iOS:

1. Add the following parameter to your app's .plist file:

• GooglePlusClientID - your client ID 

2. In your app's Info tab, add a URL type and enter your bundle ID as the identifier and scheme:
   
    
   

    

3. Add the following to your app's AppDelegate:
   

   - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
   {
       if(viewController.m_pGSAPI != nil)
           return [viewController.m_pGSAPI handleOpenURL:url sourceApplication:sourceApplication annotation:annotation];
       return NO;
   }

    

4. When calling showLoginUI, make sure to pass "googleplus" in the enabledProviders parameter:

   GSObject *pParams = [[GSObject alloc] init];
   [pParams putStringValue:@"googleplus" forKey:@"enabledProviders"];
   [gsAPI showLoginUI:pParams delegate:self context:nil];
   [pParams release];

   
   
   Note: If you want certain scopes, you must specify them in the googlePlusExtraPermissions parameter, passing a comma-delimited list of Google scopes URLs.

5. The Google+ login token will be cached, and the session will be automatically opened the next time the app is opened. In order to clear the session, use the GSAPI logout method.

Adding Twitter Single Sign-on

If Twitter Single Sign-on (SSO) is enabled and a Twitter account is defined on an iOS5 device, the user does not need to provide username & password when loging-in with Twitter. 

Notes:

• If there is more than one Twitter account available on the device, Gigya will choose the first one.
• If there is no logged in twitter user, Gigya will use the regular webview login rather than the twitter SSO.

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

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.
    

About the Demo

The demo UI includes a "Show Gigya Login UI" button. Clicking the button Gigya's Social Login UI appears (See screenshot under Logging in the User). You can click your prefered social network button to login.

The project is configured in the same manner as described in the Getting Started section above.

The project includes the following Gigya related code:

• In AppDelegate.h

  GSAPI* gsAPI; // Define the instance of the GSAPI class, which provides access to the Gigya service.

• In AppDelegate.m

  // Initialize the instance of the GSAPI class, which provides access to the Gigya service.
  // (Change "INSERT-YOUR-API-KEY-HERE" to your Gigya Api Key, which can be obtained on https://platform.gigya.com/Site/partners/Dashboard.aspx)
  self.gsAPI = [[GSAPI alloc] initWithAPIKey:@"INSERT-YOUR-GIGYA-API-KEY-HERE"];

• In ViewController.m

  // Show Gigya's Social Login UI
  GSObject* pParams = [[GSObject alloc] init];
  [pParams putStringValue:@"facebook,twitter,google" forKey:@"enabledProviders"];
  [app.gsAPI showLoginUI:pParams ViewController:self delegate:nil context:nil];
  [pParams release];