Engage for iPhone 2 beta Documentation

Before You Begin
¥	You need to have created a Janrain Engage application, which you can do on http://rpxnow.com
¥	If you would like to do server-side authentication, you'll need to create a token_url

Overview
¥	User Experience
¥	Components
¥	Basic Flow: Authentication
¥	Basic Flow: Social Publishing
¥	Detailed Flow

Getting the Library
¥	Prerequisites
¥	Get the Library
¥	Add the Library to Xcode

Using the Library
¥	Quick Start Guide
¥	Server-side Authentication
	
More Documentation
¥	iPhone Documentation
¥	JREngage API
¥	Janrain Engage Documentation
¥	Janrain Engage API


Overview

User Experience
Authentication: 
For an example application demonstrating authentication with the JREngage library, Janrain Quick Sign-In* is available (for free) on the iTunes store: itms://itunes.apple.com/us/app/quick-sign-in/id375197510?mt=8

Social publishing:
For an example application demonstrating how you can publish an activity with the JREngage library, Janrain Quick Publish* is available on the iTunes store: itms://itunes.apple.com/us/app/quick-publish/id389229631?mt=8

*The Quick Sign-In and Quick Publish applications are free and the source code for both applications ship with the library. 

Components
¥	iPhone Application*
¥	JREngage Library
¥	Engage/Providers' Servers
¥	Web Application* with Token URL (optional)
*Samples come with library

Basic Flow
Authentication:
1.	User launches the library's dialog and chooses a provider.
2.	The library takes the user to the provider in an embedded webview and they authenticate.
3.	Janrain Engage completes authentication and sends the authentication token and the user's basic authentication information back to the library*.
4.	The library closes the dialog and passes the profile data to the calling application.
5.	The application parses the profile data and the user is signed in.
6.	Optionally, the library can post the token to the token URL, to complete any server-authentication**.
7.	The token URL calls auth_info with the token and application key and can make any additional calls on the Engage API.
8.	If the token URL sends any data back to the library, the library passes the response straight through to the application, and server-side authentication is complete.
*	This step has changed from the previous versions of the JREngage library. You can now receive the basic profile data without implementing a token URL on your server.
**	This step has been made optional in this version of the JREngage library.

Social Publishing:
1.	The application creates an activity object and populates the object's fields.
2.	The user or the application initiates social publishing, passing the activity object to the library.
3.	The user chooses the providers on which they wish to share and adds their own comments.
4.	If the user is already authenticated, they can post the activity to the provider.
5.	If the user is not authenticated, the library takes them through the authentication process, described above, and then the activity is shared.
6.	The library takes the user to the provider in an embedded webview and they authenticate.
7.	The user can share to multiple providers, and the dialog is closed when the user clicks the "Close" button.

Detailed Flow (Authentication)
Step 1: User signs in from your iPhone application
The library pops up a modal dialog, and the user chooses their identity provider from the library's list of providers. The library passes this on to the Engage server for processing.
Step 2: Engage handles authentication transaction
Janrain Engage starts the authentication on behalf of your application and sends the user to the identity provider's webpage in an embedded web view. The provider authenticates the user and asks for approval to sign-in to your application.
Step 3: Engage sends the user's profile to the library
Upon successful authentication, Engage sends the library the user's basic profile data and the dialog closes.
Step 4: Optionally, the library POSTS the token to the token URL
If you wish to do any server-side authentication, you can pass the library your server's token URL. The library will continue processing authentication behind-the-scenes by issuing a POST, with the token as a parameter, to the token_url you specified.
Step 5: Use the token to access the authentication data
Your token_url code calls the Engage API with the token from Step 4 and gets back an Engage response with the OpenID authentication information and profile data, including any extended data.
Step 6: Authenticate the user on your website
Log the user into your website and create/update user profile with the data received in Step 5. The details of how this is done depends on your website implementation.
Step 7: Send a response back to the library
After you receive the data in Step 6 and process it on your server, you can send any relevant information back to the library in your response. The library will pass the response to your application. The details of the response depend on your application's implementation.


Getting the library

Prerequisites
¥	The iPhone SDK
¥	A Janrain Engage application
¥	(Optional) A web application (See Google App Engine to quickly build one)
¥	The Janrain iPhone library

Get the Library
Download the library:
	http://github.com/janrain/engage.iphone/downloads

Or clone from GitHub:
	git clone git://github.com/janrain/engage.iphone.git

Add the Library to Your Xcode Project
1.	Open your project in Xcode.
2.	Open the JREngage library in Xcode.
3.	Under the "Groups & Files" pane of the JREngage Xcode project, click the JREngage folder and drag it into the "Groups & Files" pane under your application's Xcode project. 
4.	In the dialog, do not check the "Copy items" box, make sure the "Recursively create groups..." option is selected, and then click "Add". 
 

Using the JREngage Library

You can use the JREngage library in three easy steps:
1.	Instantiate the library with your Engage application's Application ID, your server's token URL (optional), and the delegate class that implements the JREngageDelegate protocol
2.	Begin authentication or sharing by calling one of the two "show...Dialog" methods 
3.	Implement the JREngageDelegate protocol to receive notifications and profile information for your authenticating users 

Quick Start Guide
To begin, sign in to Engage to configure the providers you wish to use for authentication and/or social publishing. You will also need your 20-character Application ID from the Application Info box. 

Initialize
To initialize an instance of the library, pass your Application ID to the JREngage class method jrEngageWithAppId:andTokenUrl:delegate: which returns a pointer to the shared instance of the JREngage object:
  NSString *appId = @"<your app id>";
    ...  
  JREngage *jrEngage = [JREngage jrEngageWithAppId:appId andTokenUrl:nil delegate:self];

If you wish to implement server-side authentication you can optionally pass your token URL to this method. Make sure that your delegate class implements the JREngageDelegate protocol. 

Authenticate
In the section of code where you wish to launch the library's authentication process, send the showAuthenticationDialog message to your JREngage object: 
  [jrEngage showAuthenticationDialog];

To receive the user's basic profile data, implement the jrAuthenticationDidSucceedForUser:forProvider: method from the JREngageDelegate protocol: 
  - (void)jrAuthenticationDidSucceedForUser:(NSDictionary *)profile forProvider:(NSString *)provider 
  {     
    NSString *preferredUserName = [[profile objectForKey:@"profile"] objectForKey:@"preferredUsername"];       
    UIAlertView *alert = [[[UIAlertView alloc] initWithTitle:[NSString stringWithFormat:
                                                              @"Hello, %@!", preferredUserName] 
                                                     message:[NSString stringWithFormat:
                                                              @"You have successfully signed in to %@!", provider]
                                                    delegate:self
                                           cancelButtonTitle:@"OK"
                                           otherButtonTitles:nil] autorelease];     
    [alert show]; 
  }

Share
If you want to share an activity, first create an instance of the JRActivityObject and populate the activity object's fields: 
  JRActivityObject *activity = [[[JRActivityObject alloc]
                                  initWithAction:@"added JREngage to her iPhone application!" 
                                          andUrl:@"http://janrain.com"] autorelease];

Then pass the activity to the showSocialPublishingDialogWithActivity: message: 
  [jrEngage showSocialPublishingDialogWithActivity:activity];

Server-side Authentication
If you would like to access any of the extra features available in Janrain Engage's API or if you would like to complete server-side authentication, you can do so by implementing a token URL that does the following: 
1.	Implement a method to which the JREngage library can POST the token 
2.	Extract the token 
3.	Make a call to auth_info with the token and your application's 40-character Application Key 
4.	Parse the profile data returned from the call to auth_info, and do anything to log your user in to your web application, create session cookies, etc. 
5.	Use the token to access other Janrain Engage features via the API, such as get_contacts* and map* 
6.	Send a response back to the JREngage library with any additional information that your application may need 
*Some features may be limited to Pro and Plus customers only.

To use your token URL, you can pass it into the jrEngageWithAppId:andTokenUrl:delegate: method when initializing the shared instance of the library:
  static NSString *appId = @"<your app id>"; static NSString *tokenUrl = @"<your token url>"; 
    ...
  jrEngage = [JREngage jrEngageWithAppId:appId andTokenUrl:tokenUrl delegate:self];

Alternatively, you can change the token URL at any time using the updateTokenUrl: method: 
  - (void)updateTokenUrl:(NSString*)newTokenUrl;

The JREngage library will only post the token if this value is not null. 

Whether or not the library posts the token to the token URL, your iPhone application should not contain the Application Key. 


More Documentation

iPhone Documentation
For more detailed documentation on using the second version of our JREngage iPhone library, you can use these online docs:
https://rpxnow.com/docs/iphone_v2

JREngage API
For the complete API of the JREngage library, please see our API Documentation: 
https://rpxnow.com/docs/iphone_api/index.html

Janrain Engage Documentation
For a more thorough explanation of Janrain Engage, please see our Engage Documentation:
https://rpxnow.com/docs

Janrain Engage API
For documentation on Janrain Engage's APIs, please see our API Documentation:
https://rpxnow.com/docs#api