The iOS client library provides an Objective-C interface for the Gigya API, making it simple to integrate Gigya's service in your iPhone, iPad and iPod Touch applications. This document is a practical step-by-step guide for programmers, explaining how to integrate the Gigya service into their iOS application. Follow the steps below to get started, and use the Library Reference while implementing.
For your assistance, we provide a simple Demo Xcode Project that includes a basic Gigya SDK integration.
- Gigya's iOS SDK requires iOS 7.0 and above.
- Gigya's iOS SDK supports iOS 9. See our tips for preparing your app to work with iOS 9.
- Gigya's iOS SDK supports iOS 10.
- 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 an earlier version, please use the Upgrade Guide to migrate your code.
Download the library archive:
If you are upgrading from a former version, please make sure to read the SDK's Change Log.
Follow these steps to integrate this library in your iOS application:
- Download the Gigya SDK (above)
- Gigya Setup - obtain your Gigya API key
- Getting Started:
- Logging in the User
- Use Gigya's API - Send Requests
You may then refer to:
- Example - Publishing User Action
- Configuring Native Login - for Facebook, Google and Twitter
- Integrating Your Site with the iOS SDK
- Using Gigya Plugins in the iOS SDK
- Advanced Topics for advanced integration issues.
Gigya Setup - Obtain Your Gigya API Key
To get started, you'll need to follow these steps:
a. Add GigyaSDK Framework to Your Application's Xcode Project
- Unzip GigyaSDK.zip and drag the GigyaSDK.framework file into the "Frameworks" folder of your application's Xcode project.Note: You need Xcode 4.5 or above to be able to compile with the Gigya SDK framework.
Import the Gigya SDK header:
Add the following to your app's AppDelegate:
b. Configure Your Xcode Project
- Go to your target's settings, then to Build Settings and set the Other Linker Flags parameter to:
- In your app's Info tab, add a URL type and enter your bundle ID as the identifier and scheme:
c. Additional Provider Configuration
Gigya's SDK allows you to use the native login feature from Google and Facebook's SDKs, and Twitter's iOS integrated SSO.
In order to use these providers native logins, additional configurations are needed. Please refer to the relevant sections:
The Gigya class is the central class of the Gigya iOS SDK. The class methods of the Gigya class provide access to the Gigya login, connections, and global settings.
As a first step for using Gigya service, insert the following code in your app's AppDelegate
You should only call initWithAPIKey once.
Logging in the User
The first interaction with Gigya must always be logging in. If the user is not logged in, you cannot access his social profile nor perform social activities, such as setting his status. The quickest way to implement login is using one of the showLoginProvidersDialog methods of the Gigya class. The methods open a login user interface, which presents a selection of providers' icons, enabling the user to login via their social network / webmail account.
Here is a screenshot of the login dialog:
In order to implement Login with Facebook you need to add Facebook native login to your app. For more information go to Facebook native login section.
The following code displays the providers selection login dialog (with specified login providers ):
You may also display a specific provider login directly without showing the providers selection dialog, by calling loginToProvider with the specified provider:
If you wish to implement site login (using your own login form, and site credentials) alongside with Gigya login, read below how to synchronize site login with Gigya Service.
Registering for Gigya Global Events
For example, using GSSocializeDelegate:
Sending a Request
After you have logged in the user, you may use the GSRequest class to access the user profile and perform various activities. The following code sends a request to set the current user's status to "I feel great":
The response handler receives GSResponse and NSError parameters. If the operation was successful, error will be nil. Otherwise, you can check the error object (see GSErrorCode enum for error codes) or response to learn why it failed.
For example - handling a 'getUserInfo' response:
The response of 'getUserInfo' includes user information in its data field.
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 which 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 you can either use NSDictionary objects or provide a JSON string, as shown in the two examples below:
Option A - Using NSDictionary objects
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
Adding Facebook native login to your iOS app is mandatory if you want to log in via Facebook.
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:
- Add the Facebook iOS SDK to your project (please consult the release notes to see the latest supported version).
- Add the following two parameters to your app's
FacebookAppID- your Facebook's application ID.
FacebookDisplayName- your Facebook's application Display Name as you configured in the App Dashboard.
- Create an array key called
URL typeswith 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".
When calling showLoginProvidersDialog, make sure to pass "facebook" in the providers parameter:
You may also display the Facebook login directly without showing the providers selection dialog, by calling loginToProvider with "facebook" as the provider:
- If you have multiple Facebook apps using the same Facebook app ID, as described in Facebook's documentation, you should concat the URL scheme suffix to the app ID in the .plist file, and add another parameter:
- FacebookUrlSchemeSuffix - your application's URL scheme suffix.
- 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 Gigya logout method.
- If you want to ask the user for additional permissions, you need to use the Gigya class requestNewFacebookPublishPermissions or requestNewFacebookReadPermissions methods.
Adding Twitter Single Sign-on
If Twitter Single Sign-on (SSO) is enabled and a Twitter account is defined on an iOS device, the user does not need to provide username and password when logging in with Twitter.
Simply add Social.framework and Accounts.framework to your project:
Using Touch ID
Gigya's iOS SDK supports Touch ID from version 3.5.2 and above. Touch ID is supported on iOS 8 and later, the iPhone 5s or later, iPad Pro, iPad Air 2, or iPad mini 3 or later.
Touch ID enables a much higher level of security for your app by verifying that the user is, in fact, the device owner. When this feature is enabled in the SDK, sessions are encrypted using the following methods:
- If Touch ID is supported by the device and a fingerprint has been registered - Touch ID is used.
- If Touch ID is supported by the device but fingerprints haven't been registered - the device passcode is used.
- If the device doesn't have a passcode or the device uses iOS 7, standard keychain encryption is used.
To enable Touch ID, add the following parameters to your .plist:
- GigyaTouchIDEnabled = YES (default = NO)
- GigyaTouchIDMessage = "<custom Touch ID message>" (default = "Please authenticate to proceed”).
When Touch ID is enabled, native login will continue to work as expected (if your app uses native login), but provider sessions will not be automatically refreshed.
When Touch ID is enabled, the user will be prompted to authenticate during the last step when logging in to your app. Once authenticated, the session is encrypted and the user may use your app.
After that time, Touch ID authentication takes place:
- When the app is re-opened, before the first call to a Gigya API. In this context, re-opened means that the app was closed. Switching apps does not cause an app to close.
- When a session has expired, before the first call to a Gigya API.
Generally, users will not be asked to authenticate more than once per running of your app.
Integrating Your Site with the iOS SDK
- Session state will be synchronized. If the user is logged in and the session is active in the iOS SDK, he will be automatically logged in via the JS SDK.
- Any API requests by the JS SDK will be routed through the iOS SDK, using the iOS SDK session.
- Any login process invoked by the JS SDK will be handled by the iOS SDK, creating a seamless login experience, using Safari or the provider’s native login.
To register a web view, follow these steps:
Call registerWebView:delegate: before the web view has started loading:
Add the following code to your UIWebViewDelegate implementation:
In the beginning of
Unregister the web view when finished:
The Gigya iOS SDK fully supports using WKWebView in place of UIWebView, however, it's usage differs slightly. If you attempt to exchange usage of WKWebView directly with UIWebView, the SDK will return an exception, since the two use different selectors.
The exception is thrown due to the
[GSWebBridge webViewDidStartLoad:webview] selector only accepts UIWebView.
To overcome this and implement the WKWebView with the GSWebBridge, please consult the following example code, which uses Objective-C with the Gigya iOS SDK.
Using Gigya Plugins in the iOS SDK
GSPluginView is a custom UIView that renders Gigya JS Plugins and integrates them seamlessly with the Gigya iOS SDK.
GSPluginView currently supports the following plugins:
- Comments - comments.commentsUI. Note: commenting is supported, but sharing the comment to social networks is not supported.
- Reviews - comments.commentsUI.
- 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 Gigya's showPluginDialogOver:plugin:parameters: to display the GSPluginView modally, or alternatively, for more control and customization, you can create an instance yourself and add it to your view.
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 showPluginDialogOver to display GDPluginView modally:
An example for creating an instance yourself:
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 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 Gigya setSession 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 for 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 by calling isSessionValid for the current user session:
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 "token" and "secret" from the active GSSession.
- 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 server-side SDK's SigUtils.validateUserSignature() method, passing in the data you received from step 1 and your Gigya secret key.
Handling Callbacks Manually
App developers who implement the ' application:openURL:sourceApplication:annotation: ' selector (wish to handle incoming events manually), should first check if the event is a Gigya event which should be handled by the Gigya SDK to avoid unexpected errors.
The following code should be placed in AppDelegate.m to enable the Gigya SDK to handle incoming Gigya events:
Handling Screen-Set Events
The following is an example of code to handle screen-set events, i.e., onAfterScreenLoad of the Registration screen-set.
Demo Xcode Project
We have created for your assistance a simple Xcode project that integrates Gigya's iOS SDK, with basic usage.
The demo project is preconfigured with site API key and native login for Facebook, Google and Twitter.
About the Demo
The demo project is a simple application, which implements Gigya's login and retrieves the user's friends list. The user can also add connections and log out.
The project is configured in the same manner as described in the Getting Started section above.
Before deploying any new project to production, it is recommended best practice to always test on a live device first.