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”


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.

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.

A few notes on the pop-up dialog:

  • Prior to running Engine, you must make sure to configure the InfoPlist.strings values for ‘‘NSLocationWhenInUseUsageDescription’’ and ‘‘NSLocationAlwaysUsageDescription’’. Step-by-step instructions for doing so are available here
  • The resulting dialog would resemble the following:


  • If you choose this behavior, and the dialog has never been displayed before, the dialog will be displayed when Engine is initiated.
  • As per the way iOS behaves, this dialog can only be popped up once in the lifespan of your app being installed on a specific device.
  • Moreover, the general request for location permissions can only be made once in the lifespan of your app being installed. If your app previously requested location permissions for reasons unrelated to Engine, this dialog will be skipped.

After you’ve finished this, copy your API key from the Garage. You’ll need it for the next step.

Initializing Engine

If you are following the Get Started tutorial, you can skip this section. Instead, click here to return to the tutorial.

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

First, import Engine:

#import "FactualEngine.h"

Second, start Engine when your app is ready:

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