Getting the Library

Prerequisites

Download the Library

You can either

  • Download an archive of the library, or
  • clone the Janrain Engage for iOS library from GitHub: 
    git clone git://github.com/janrain/engage.iphone.git

We recommend you clone the GitHub repository, and check out 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.

Add the Library to Your Xcode Project

Xcode 4

  1. Open your project in Xcode.
  2. Make sure the “Project Navigator” pane is showing. (View > Navigators > Show Project Navigator ⌘1)
  3. In the “Project Navigator” pane of your Xcode project, right-click the root project node for your application — with the blue Xcode icon — and select the menu option New Group, to create a new group in your project tree. Rename this group “JREngage.”

4. Right-click the JREngage group, and select the menu option Add Files To [your project name].

5. Navigate to the location where you placed the engage.iphone. Open that folder, and then open the JREngage subdirectory. Select the directories Classes, Resources, Security, and JSONKit, and the file JREngage-Info.plist.

6. In the dialog, do not check the Copy items into destination group’s folder (if needed) box. Make sure the Create groups for any added folders is selected, and that the Add to targets check box is selected for your application’s targets. Click Add.

7. You must also add the Security framework and the MessageUI framework to your project. As the MessageUI framework is not available on all iOS devices and versions, you must designate the framework as “weak-linked.” Instructions for adding frameworks in Xcode 4 can be found in Apple’s iOS Developer Documentation.

Working with ARC

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 these instructions:

  1. Add the JREngage files to your project by following the above instructions for Xcode 4.
  2. Go to your project settings, select your application’s targets and click the Build Phases tab.
  3. Expand the section named Compile Sources.
  4. Select all the files from the JREngage library, including SFHFKeychainUtils.m and JSONKit.m.
  5. Press Enter to edit all the files at once, and, in the floating text-box, add the -fno-objc-arc compiler flag.

Xcode 3.5

  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.

5. Add the Security framework to your project by right-clicking the Frameworks group under your project and selecting Add > Existing Frameworks. Then locate Security.framework in the list and add it to the project.

6.(Optional) If you interested in adding social sharing though email and SMS, you must also add the MessageUI framework to your project. As this framework is not available on all versions of iOS, you must designate the framework as “weak-linked.” Instructions for doing this can be found in the Email and SMS section of the documentation.

Upgrading the Library from a Previous Version

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

  1. Open your project in Xcode.
  2. Locate the JREngage folder (group) under the Project Navigator pane — or the Groups & Files pane if you’re using Xcode 3 — of your Xcode project.
  3. Right-click the JREngage folder and click Delete.
  4. In the dialog, make sure you select the Remove References Only button.
  5. Re-add the JREngage files following the above instructions for Xcode 3.5 or Xcode 4. You shouldn’t have to add the Security or MessageUI frameworks if you have already done so.

Help Us Improve!

Give us your feedback