Using the 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 “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 and configure the providers you wish to use for authentication and social sharing. You will also need your 20-character Application ID from the Engage Dashboard.

Import the JREngage headers:

#import "JREngage.h"

Initialize

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

Social Sign-In

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];
}

Social Sharing

If you want to share an activity, first create an instance of the JRActivityObjectand 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];

Even Quicker Quick Start Guide

Just copy and paste!

Sign in to Engage, create an application, and configure the providers you wish to use for sign-in and/or social publishing.

Import the JREngage headers:

#import "JREngage.h"

To authenticate*:

JREngage *jrEngage = [JREngage jrEngageWithAppId:@"<your app id>"
                                     andTokenUrl:nil
                                        delegate:self];

[jrEngage showAuthenticationDialog];

To share*:

JREngage *jrEngage = [JREngage jrEngageWithAppId:@"<your app id>"
                                     andTokenUrl:nil
                                        delegate:self];

[jrEngage showSocialPublishingDialogWithActivity:
          [JRActivityObject activityObjectWithAction:@"<just did something fabulous>"
                                       andUrl:@"http://<your_url>"]];

Implement the JREngageDelegate protocol:

- (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> as necessary.

* 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 (like when 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.

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:

  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, and so on.
  5. Use the token to access other Janrain Engage features through 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, 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 = @"&lt;your app id&gt;";
static NSString *tokenUrl = @"&lt;your token url&gt;";
...

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.

Email and SMS Sharing

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:

Add the MessageUI framework to your project by right-clicking the Frameworks group under your project and selecting Add > Existing Frameworks.

Locate MessageUI.framework in the list, and add it to the project.

As this framework is not available on all versions of the iOS, you must designate the framework as weak-linked.

Once you have added the framework to your project, expand your Application Target and select the target’s build phase, called Link Binary With Libraries.

Once this is selected, go to the Detail view and you can change the MessageUI’s role from Required to Weak.

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 Share Email and SMS

Device Can Only Share SMS

Device Can Only Share Email

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.

Email

Create a JREmailObject and populate the fields of the object:

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];

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];

SMS

Create a JRSmsObject and populate the fields of the object:

JRSmsObject *sms =
    [JRSmsObject smsObjectWithMessage:
                    [NSString stringWithFormat:
                      @"Check out this article from the Janrain Blog!nn%@",
                      @"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 by 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.

URL Shortening

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 five shortened URLs each for email and SMS 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!nn%@",

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.

Help Us Improve!

Give us your feedback