Mobile Apps Overview

Use this documentation to help integrate Janrain social login and registration with your native Android or iOS mobile applications. This is an SDK with libraries and tools designed to help you build such applications. If you want to create a mobile version of your web applications, you need to refer to the Embed UI in a Webview section for the respective platform.

Overview

The Janrain User Management Platform (JUMP) includes the Engage and Capture widgets. Engage enables Social Sign-in, and Capture provides User Registration so you can gather information about your users. Federate is another component of JUMP that allows you to make a group of related websites work together. Our documentation often refers to Engage and Capture as separate widgets or applications, but they work together.

This page provides an overview of the Janrain Mobile Libraries, and how to use them.

Engage

Janrain Engage — part of the Janrain User Management Platform (JUMP) — is a user authentication service for the web. Engage unifies the interface to different social sign-in providers (such as Facebook and Google) and presents a unified, simplified interface which allows developers to add social sign-in to their websites easily.

Janrain provides two mobile libraries — JUMP for iOS and JUMP for Android — that bring the advantages of the Engage service to native-mobile applications. With these libraries, developers can authenticate their users on multiple providers and share their activities through Janrain’s unified API.

Along with the Engage mobile library, developers should implement their own server authentication endpoint or use Capture as their back end to manage user sessions within their mobile application.

Components

The following components are involved in social sign-in and sharing for Engage:

* Look at the sample applications for more ideas.

Sign-In

During sign-in, the JUMP mobile libraries open a dialog presenting the end user with a list of providers for which the application is configured. The user chooses a provider, and then the libraries take him or her to an embedded web browser displaying the social provider’s sign-in page. Once the user signs in, the JUMP mobile libraries process the results and pass them back to your application and close the dialog. The libraries then post an Engage auth_info token to your application’s server (or to Capture) to complete the authentication.

Important: Engage authenticates users, but does not manage user sessions.

Sharing

The JUMP mobile libraries provide screens, using native user interface elements, for sharing on the user’s social networks. Your users can share messages, and links (as well as Facebook activities) to Facebook, Yahoo!, Twitter, Myspace, and LinkedIn, as well as sharing through SMS or email.

Note: The JUMP mobile libraries’ native sharing User Experience (UX) supports only broadcast sharing at this time. Sharing with specific contacts only is not supported yet.

Capture

Janrain Capture — part of the Janrain User Management Platform (JUMP) — is a user management service for the web. It provides a customizable user data-store with a rich set of features including:

Janrain has provided Capture support in the JUMP for iOS library, which brings the advantages of Capture to the iOS device. With this library, developers can authenticate their users on multiple providers and manage the user’s record through Janrain’s unified API.

Components

The following components are the main actors involved in Capture mobile integration:

* A sample comes with the library.

Engage Wrapper

The JUMP for iOS library “wraps” the Engage mobile library module when integrating Capture into your mobile application. Instead of independently configuring and connecting the Engage and Capture modules, the Engage wrapper in the Capture module configures both Engage and Capture and connects them automatically.

User Model

The JUMP for iOS library creates a user model, in Objective-C, from your Capture schema. The user model stores the full Capture record on the device and includes methods to easily push local changes to your Capture server.

User Experience

This section describes the user flow and its features.

Engage Sign-In

The JUMP mobile libraries give your application the ability to authenticate users through their existing social identity provider accounts — Google, Facebook, Twitter, and so on. When you are ready to authenticate a user, the libraries present a modal dialog displaying a list of the providers that are configured in your Engage application. The user can select their desired provider and sign in through the provider’s web interface.

The screenshots below show the sign-in process on the iPhone:

Sign-in on iPhone.

Figure 1: Sign-in on iPhone.

The screenshots below show the sign-in process on Android:

Sign-in on Android

Engage Sharing

Additionally, the JUMP mobile libraries include native social sharing screens, giving your users the ability to share their activities on their social networks. You can compose an activity, and when you are ready, the library presents a modal dialog that allows your users to add their comments and share the activity. In addition to sharing through the user’s social network, they can share by email and SMS.

Figure 3 below shows social sharing on the iPhone:

Social Sharing on the iPhone

Figure 3: Social Sharing on the iPhone.

For an example application demonstrating how you can share an activity with the JUMP for iOS library, see the Janrain Quick Publish* app, available for free in the iTunes AppStore.

Here are links to our documentation to get you started.

The screenshots below show social sharing on Android:

Social Sharing on Android

iPad and Android Tablets

JUMP can run on iPad and Android tablets as well.

iPad

The Engage for iOS SDK also works, as is, on the iPad and with universal apps. No changes to your code are required. The library dynamically detects the device and presents its dialogs in modal views optimized for the iPad.

Figure 5 below show sign-in and social sharing on the iPad.

Sign-in and Sharing on iPad.

Here is a link to our documentation about prerequisites.

Android Tablet

Since release 2.0, the Engage for Android library has included support for Android tablets. Tablet screens are supported automatically with the use of modal dialogs, and the sharing interface is embeddable as an Android fragment.

Capture Sign-In

The JUMP for iOS library provides Capture user management to your iOS application, giving you the ability to authenticate your users on social providers and interact with the user’s record and session locally and remotely.

Flow

Janrain sign-in, sharing, and other applications all have flow, that is, user screens, presented to the end-user in a particular order.

Engage Sign-In

  1. Your mobile application requests that the Engage library present the sign-in dialog.
  2. The user chooses a provider.
  3. The library takes the user to the provider in an embedded web browser where she signs in.
  4. Janrain Engage completes authentication and sends the auth_info token, the user’s authentication information, and the user’s unique identifier back to the library.
  5. The library closes the dialog and passes the profile data to the calling application.
  6. Optionally, the library can post the auth_info token to a token URL to complete server-side authentication:
    1. The library opens an HTTP connection to the token URL, in which:
      1. The library POSTs the auth_info token to the token URL.
      2. The token URL server POSTs to the Engage auth_info URL with the supplied auth_info token and your Engage API key.
      3. Engage responds with the user’s authentication information and the user’s unique identifier.
      4. Your token URL server creates a session incorporating the user’s identifier, and responds to the library with a session token.
    2. The response from your server’s token URL, containing the session token you created, is passed to your JREngageDelegate through the jrAuthenticationDidReachTokenUrl (iOS, Android) method.
    3. Your mobile application stores the session token supplied in the token URL’s response, and uses it to communicate securely with your server.
  7. The application parses the profile data and the user is signed in.

Here are links to our documentation to get you started.

Engage Sharing

  1. The application creates an activity object and populates the object’s fields.
  2. The application initiates social sharing, passing the activity object to the library.
  3. The user can add comments and choose which provider he wishes to share the activity with.
  4. If the user is already signed in, he can post the activity to the provider.
  5. If the user is not signed in, the library takes the user to the provider’s web interface where he authenticates, and then the activity is shared.
  6. The user can share to multiple providers, and the dialog is closed when the user presses dismisses the dialog.

Documentation links.

Capture Sign-In

  1. Your mobile application requests that the JUMP for iOS library present the sign-in dialog.
  2. The user chooses a provider. (Username and password authentication is also available.)
  3. The library takes the user to the provider in an embedded web browser where she signs in.
  4. Janrain Engage completes authentication with the chosen provider and sends a portion of the user’s authentication information back to the library.
  5. The library closes the dialog and passes the information to the calling application, where the calling application can update its UI to reflect that sign-in is almost complete.
  6. The library automatically posts the authentication token to the Capture server, where Capture will attempt to sign the user in, using the social profile data available from the social identity provider. One of three results will occur:
    1. Returning User — The user’s record already exists on the Capture server. The record is retrieved from the Capture server and is passed back to your application.
    2. New User, Record Created — The user’s record did not yet exist on the Capture server, but it is automatically created and passed back to your application. Your application may wish to collect additional information about the user and push that information back to the Capture server.
    3. New User, Record Not Created* — The user’s record was not automatically created because required information was not available in the social profile data returned by the social identity provider. (For example, your Capture instance may require an email address, but Twitter does not provide an email address, so the record cannot be automatically created on Capture when the user signs in with Twitter.) An incomplete user record is passed back to your application, where it is your application’s responsibility to collect the missing required data and invoke the user record creation on Capture:
      1. Your application should present UI to collect the required information and any additional information you wish to collect.
      2. Your application should store this information in the user record object returned by Capture.
      3. Once the information is collected, your application invokes record creation on Capture.
  7. The library will send the captureAuthenticationDidSucceedForUser:status: message to your JRCaptureSigninDelegate, containing the JRCaptureUser record and a JRCaptureRecordStatus status indicating whether the record is is for a returning user, a new user, or if the record has not yet been created.
  8. The user’s session token is stored by the library, and she is signed in. You can continue to collect data about your user and her activities, and effortlessly push the data to the Capture servers.

* If your Capture instance does not require information such as an email address, this scenario does not occur.

Documentation links.