Engine SDK for iOS

The steps below will guide you through installing the Engine SDK into your app via Xcode and Objective-C.


  • The Engine SDK is compatible with iOS 8.0+
  • After compilation, the SDK should add no more than 1.7 MB to your app’s size.
  • The Engine will store no more than 256 KB of data on-device.
  • The SDK requires either ALWAYS or IN APP location authorizations.

Get an API key

Sign up for access to Engine here.

Get the SDK

Once you’ve verified your account, you can access your API key and download the AAR here.

Copy the SDK to Your Project

  • Decompress the downloaded archive. The contents should contain the files FactualEngine.h and libFactualEngine.a.
  • Copy these files into your project. (libFactualEngine.a may fail to link otherwise!)
    • Note that you can optionally drag and drop the library files into your project. If you do so, make sure to enable the “Copy items if needed” checkbox for Destination.
  • Within Xcode, add both files to your project:

Add Linked Libraries

Click on the Build Phases tab. Link the following binary libraries:

  • libFactualEngine.a (This should already be linked from step 3.)
  • libc++.tbd
  • libz.tbd

Disable Bitcode

The Engine SDK is not compatible with bitcode.

Set Location Authorization Messaging

You must ensure the InfoPlist.strings values associated with location authorizations are defined.

If you haven’t done so already, the process is as follows:

  • From the Project Navigator in Xcode, open info.plist.
  • Hover over Information Property List. Click on the small plus symbol (+) in a circle.
  • In the resulting pick list menu, scroll down and select the item “Privacy - Location When In Use Usage Description”
  • Double click on the corresponding Value field and enter your desired prompt text.
  • Repeat again, for the property “Privacy - Location Always Usage Description”.

These values define the messages that will be displayed to your users when prompting for the appropriate location authorizations.

Example Implementation Code

  • Import the Engine header
  • Add the FactualEngineDelegate interface


The example code below will:

  • Initialize and start Engine, in conjunction with the required permission checks
  • Make and handle a request for current location candidates
  • Programmatically define a Circumstance
  • Define and register a simple handler for when the Circumstance is met

A few things to note:

  • The SDK detects which location authorizations your app has requested. It will not request any location authorizations on its own. This example contains boilerplate code for seeking the authorizations.
  • The FactualEngineDelegate interface provides debugging info to your app.
  • Starting the SDK requires a URL representing your app’s terms of service and the applicable date.

Insert your API Key

In the code example above, you’ll need to provide:

  • Your API key
  • A URL to your app’s terms of service
  • The date the current user has accepted the terms of service
[FactualEngine startWithApiKey:@"your Api Key Goes Here"
               acceptedTosDate:[NSDate date]