The current version of the library is 2.3.X, which includes support for Xcode 4 and iOS 5; an updated social sharing UI; the ability to dynamically exclude providers from list of sign-in providers or directly authenticate with one provider; better handling when your application quits or goes into the background; and several bug fixes.
The Janrain Engage for iPhone library gives your application the ability to authenticate users through their existing social identity provider accounts — e.g., Google, Facebook, Twitter, etc. When you are ready to authenticate a user, the library presents a modal dialog displaying a list of the providers that you configured in your Engage application. The user can select his desired provider and sign in through the provider's web interface. The library remembers his preference for a better return experience.
Below are some screen shots demonstrating the sign-in process on the iPhone.
For an example application demonstrating authentication with the Engage for iOS library, the Janrain Quick Sign-In* app is available for free from the AppStore.
Additionally, the Engage for iOS library includes a social sharing API, giving your users the ability to share their activities on several 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. They can post it to a number of social providers, as well as share it through email and sms.
Below are some screen shots demonstrating social sharing on the iPhone.
For an example application demonstrating how you can share an activity with the Engage for iOS library, the Janrain Quick Publish* app is available for free from the AppStore.
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.
Below are some screen shots demonstrating sign-in and social sharing on the iPad.
* | The Quick Sign-In and Quick Publish applications are free and the source code for both applications ship with the library. |
auth_info
token URL* | Samples come with library |
auth_info
token,
the user's
authentication information, and the user's unique identifier back to the library.
auth_info
token to a
token URL to complete server-side authentication:
auth_info
token to the token URL.
auth_info
url
with the supplied auth_info
token and your Engage API key.
You may also make additional calls against the Engage API.
identifier
, and responds to the library with a session token.
JREngageDelegate
via the
jrAuthenticationDidReachTokenUrl:withResponse:andPayload:forProvider:
method.
git clone git://github.com/janrain/engage.iphone.git
We recommend you clone the GitHub repository, and checkout a specific release tag.
This way it's easy to keep up with the latest version of the Engage for iOS
library — just git pull
the master branch to get the latest
stable release.
The current version of the library is 2.3.X, which includes support for Xcode 4 and iOS 5; an updated social sharing UI; the ability to dynamically exclude providers from list of sign-in providers or directly authenticate with one provider; better handling when your application quits or goes into the background; and several bug fixes.
The Janrain Engage for iOS library does not, itself, use automatic reference counting (ARC), but you can easily add the library to a project that does.
To use the Engage for iOS library with an ARC project, please follow the instructions below:
-fno-objc-arc
compiler flag.
We recommend that you upgrade the library from versions 2.2.1 and below to the current version (v2.3.0), as this version has been updated for iOS 5. As there has been some changes to the files in the Engage for iOS Library, the easiest way to update the references in Xcode is to remove the JREngage group and re-add it.
JREngageDelegate
protocolshow...Dialog
" methods
JREngageDelegate
protocol to receive notifications and profile information for your authenticating users
To begin, sign in to Engage and configure the providers you wish to use for authentication and/or social sharing. You will also need your 20-character Application ID from the Engage Dashboard.
Import the JREngage headers:
#import "JREngage.h"
To initialize an instance of the library, pass the Application ID of your Janrain
Engage application (found on the
Engage Dashboard),
an optional token URL, and an optional delegate object 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.
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*)auth_info 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]; }
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];
Just copy and paste!
#import "JREngage.h"
JREngage *jrEngage = [JREngage jrEngageWithAppId:@"<your app id>" andTokenUrl:nil delegate:self]; [jrEngage showAuthenticationDialog];
JREngage *jrEngage = [JREngage jrEngageWithAppId:@"<your app id>" andTokenUrl:nil delegate:self]; [jrEngage showSocialPublishingDialogWithActivity: [JRActivityObject activityObjectWithAction:@"<just did something fabulous>" andUrl:@"http://<your_url>"]];
- (void)jrEngageDialogDidFailToShowWithError:(NSError*)error { } - (void)jrAuthenticationDidNotComplete { } - (void)jrAuthenticationDidSucceedForUser:(NSDictionary*)auth_info forProvider:(NSString*)provider { } - (void)jrAuthenticationDidFailWithError:(NSError*)error forProvider:(NSString*)provider { } - (void)jrAuthenticationDidReachTokenUrl:(NSString*)tokenUrl withResponse:(NSURLResponse*)response andPayload:(NSData*)tokenUrlPayload forProvider:(NSString*)provider { } - (void)jrAuthenticationCallToTokenUrl:(NSString*)tokenUrl didFailWithError:(NSError*)error forProvider:(NSString*)provider { } - (void)jrSocialDidNotCompletePublishing { } - (void)jrSocialDidCompletePublishing { } - (void)jrSocialDidPublishActivity:(JRActivityObject*)activity forProvider:(NSString*)provider { } - (void)jrSocialPublishingActivity:(JRActivityObject*)activity didFailWithError:(NSError*)error forProvider:(NSString*)provider { }
Add code to the delegate messages you care about receiving, replace anything <between angle brackets>, and you're good to go!
* |
The first time your application uses JREngage on any device, the library contacts the Engage servers
to retrieve your application's list of providers and other configuration information JREngage needs to
work. Once this has been downloaded, the library caches this information for subsequent launches,
updating the cache only when the information has changed (e.g., you add or remove a provider).
While you can initialize the JREngage library immediately before you call one of the show...
methods, please understand that your users may encounter our loading screen during the delay in which
the library contacts the Engage servers.
|
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:
auth_info
with the token and your application's 40-character Application Key
get_contacts
* and
map
*
* | Some features may be limited to Pro, Plus and Enterprise 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. |
IMPORTANT: Whether or not the library posts the token to the token URL, your iPhone application should not contain the Application Key.
You can also share your activity through email and sms.* This additional feature uses the iPhone SDK's native MessageUI framework, which you will need to add to your Xcode project:
As this framework is not available on all versions of the iOS, you must designate the framework as weak-linked:
As not all devices have the ability to share via email or sms, designating the MessageUI.framework as weak-linked will allow the library to dynamically detect the functionality of the device and allow the user the option to share only if email and/or sms are available. If the device is not capable of sending and email or sms, this is detected the option(s) will not be available to the user.
![]() |
![]() |
![]() |
Device can only share email |
Device can only share sms |
Device can share email and sms |
To share with email or sms, create an
email or
sms object, populate the object's fields, and add the object to the
email
or
sms
property in your
JRActivityObject
. The given content is supplied to the MFMailComposeViewController
or MFMessageComposeViewController class when the user wants to share your activity via email.
* | Although the actual sending of an email or sms does not go through the Engage servers (it solely uses the iOS MessageUI framework), Engage will track when an activity is successfully shared via email/sms. |
Create a
JREmailObject
and populate the
fields of the object:
JREmailObject *email = [JREmailObject emailObjectWithSubject:@"Check out this article from the Janrain Blog!" andMessageBody:@"<html><bod><br /> \ I found this article on Janrain's Blog, \ and I thought you might be interested! \ <br /> \ <a href=\"http://www.janrain.com/blogs/social-login-iphone-janrain-engage\"> \ Click here to read it.</a> \ <br /> \ Learn more at <a href=\"http://janrain.com\"> \ http://janrain.com</a><br /> \ <br /></body></html>" isHtml:YES andUrlsToBeShortened:nil];
Add the object to the your
JRActivityObject
and pass it to the library.*
JRActivityObject *activity = [[[JRActivityObject alloc] initWithAction:@"shared an article from the Janrain Blog." andUrl:@"http://www.janrain.com/blogs/social-login-iphone-janrain-engage"] autorelease]; activity.email = email; [jrEngage showSocialPublishingDialogWithActivity:activity];
Create a JRSmsObject
and populate the
fields of the object:
JRSmsObject *sms = [JRSmsObject smsObjectWithMessage: [NSString stringWithFormat: @"Check out this article from the Janrain Blog!\n\n%@", @"http://www.janrain.com/blogs/social-login-iphone-janrain-engage"] andUrlsToBeShortened:nil];
Add the object to the your
JRActivityObject
and pass it to the library.*
JRActivityObject *activity = [[[JRActivityObject alloc] initWithAction:@"shared an article from the Janrain Blog." andUrl:@"http://www.janrain.com/blogs/social-login-iphone-janrain-engage"] autorelease]; activity.sms = sms; [jrEngage showSocialPublishingDialogWithActivity:activity];
* | If you do not supply a JREmailObject or JRSmsObject to the JREActivityObject, the option of sharing via email or sms (respectively) will not be available to the user. Likewise, if you do supply an email or sms object to the activity, but the device does not have this capability, the option will not be available to the user as well. |
If your email message body contains URLs that you would like shortened to an http://rpx.me/
URL (with which you can track click-throughs), you can do this by using the
urls
property of the
JREmailObject
or the
urls
property of the
JRSmsObject
. The library will contact the Engage servers to obtain
up to 5 shortened URLs for email and sms each and replace the URLs in
your email and sms message bodies.
Create an email or sms object, and populate the message body/message fields with your content, including the URLs that you would like shortened:
JREmailObject *email = [JREmailObject emailObjectWithSubject:@"Check out this article from the Janrain Blog!" andMessageBody:@"<html><body><br /> \ I found this article on Janrain's Blog, \ and I thought you might be interested! \ <br /> \ <a href=\"http://www.janrain.com/blogs/social-login-iphone-janrain-engage\"> \ Click here to read it.</a> \ <br /> \ Learn more at <a href=\"http://janrain.com\"> \ http://janrain.com</a><br /> \ <br /></body></html>" isHtml:YES andUrlsToBeShortened:nil]; JRSmsObject *sms = [JRSmsObject smsObjectWithMessage: [NSString stringWithFormat: @"Check out this article \ from the Janrain Blog!\n\n%@", http://www.janrain.com/blogs/social-login-iphone-janrain-engage] andUrlsToBeShortened:nil];
Create an array, add the exact URLs to the array, and add the array as the urls property of the email/sms object:
NSArray *emailUrls = [NSArray arrayWithObjects: @"http://www.janrain.com/blogs/social-login-iphone-janrain-engage", @"http://janrain.com", nil]; email.urls = emailUrls; NSArray *smsUrls = [NSArray arrayWithObjects: @"http://www.janrain.com/blogs/social-login-iphone-janrain-engage", nil]; sms.urls = smsUrls;
Once you pass the activity object to the library, it will contact the Engage servers to
obtain shortened URLs for all the URLs that you provided in the url
arrays.
Once this connection returns, the library will replace any instance of your URLs in your
email/sms message body with the http://rpx.me URL. When a user clicks on any shortened URL,
it will redirect them to the original URL and Engage will track the referral.
When obtaining the shortened URLs, the connection to the Engage server is made as soon as your application opens the library's sharing dialog. To maintain the best user experience, this call is non-blocking, but, if there are network latency issues, the connection may not return before the user is ready to share your activity via email/sms. If the user does attempt to share the activity via email before the connection to shorten the URLs is returned, the email will contain the original URLs and the click-throughs will not be tracked. As soon as the connection returns, the activity is modified to contain the shortened URLs.