Engine for iOS Installation

This document walks you through the process for installing the Engine SDK.


This beta version of Engine is compatible with iOS 8.0+.


Once you have registered to join the Engine Open Beta, you can download Engine from the garage. Engine is provided as an archive containing a static library:

filename description
FactualEngine.h Objective-C header file
libFactualEngine.a Objective-C library file

Once you’ve unzipped the downloaded archive, startup Xcode.

  1. Copy FactualEngine.h and libFactualEngine.a into your project. (If you are following the Get Started tutorial, it’s probably easiest to put them in the same directory as your AppDelegate and ViewController code.)
  2. Add FactualEngine.h and libFactualEngine.a to your project (ctrl-click -> Add Files to “My Project Name“…):

Linked Libraries

You’ll also need to add a few linked libraries:

  1. Click on the Build Phases tab.
  2. Open the Link Library With Binaries options.
  3. Click + and add libc++.tbd.
  4. Also add libz.tbd.

Disable Bitcode

At the current time, Engine is not compatible with bitcode.

  1. Click on the Build Settings tab.
  2. Search for bitcode
  3. Under the option for Enable bitcode, choose the option “No”

Set Location Permission Messaging

You must make sure to configure the InfoPlist.strings values associated with requesting location permissions from your users as follows:

  1. From the Project Navigator in Xcode, open info.plist.
  2. If you hover over Information Property List, you’ll see a small plus symbol (+) in a circle. Click it.
  3. In the resulting pick list menu, scroll down and click on the item “Privacy - Location Usage Description”
  4. After it is added, double click on the corresponding Value entry and enter “My Application needs your location to provide helpful services.” You can enter your own text here if you desire. This is the text that will appear in the permission dialog when users are prompted for access to location by your app.
  5. Repeat, adding the parameter “Privacy - Location When In Use Usage Description”
  6. Repeat again, adding the parameter “Privacy - Location Always Usage Description”

Initializing Engine

In order to initialize Engine, you will need to do the following:

Import Engine:

#import "FactualEngine.h"

Start Engine when your app is ready (e.g., from within didFinishLaunchingWithOptions or similar):

FactualEngine *engine = [FactualEngine sharedEngine];

[engine startWithApiKey:@"your_api_key"
        acceptedTosDate:[NSDate date]];

Note: In order to be initialized, Engine requires a URL representing your app’s Terms of Service, and the date that the current user accepted the Terms of Service (or the current date, as shown here).


Over-the-air configuration enables you to push changes to devices that are running in the field in real-time, to change the behavior of your app. In the production version of Engine, this will allow you to do things like push completely new circumstance definitions.


Updates pushed using the over-the-air configuration system may take as long as 24 hours to propagate to all devices.

During the Engine Open Beta, there are only two parameters you can control from our online interface:

You can specify:

  • When Engine is allowed to access user location (in app, or always).
  • Whether or not Engine should pop-up the associated dialog requesting the associated location permissions.

If you choose to have Engine pop-up a dialog, the resulting dialog would resemble the following:


As a general rule, we suggest that you only ask for permissions that make sense for your associated use cases. If your app is not able to provide any obvious value to your end users by detecting their current situation while the app is not in the foreground, you should not request the always permission.