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 download size.
  • The SDK requires either ALWAYS or IN APP location authorizations.

Get an API key

Sign up for access to Engine here.

Get the SDK

The Engine SDK is distributed as a static library. Once you’ve verified your account, you can access your API key and download the SDK here.

Copy the SDK to Your Project

  • Decompress the downloaded archive. The contents should contain the files FactualEngine.h and libFactualEngine.a.
  • Within Xcode, add both files to your project (libFactualEngine.a may fail to link otherwise!). Make sure to enable the “Copy items if needed” checkbox for Destination (visible under ‘Options’).

  • Note that you can optionally drag and drop the library files into your project. Similiar to the above process, make sure to enable the “Copy items if needed” checkbox for Destination (visible under ‘Options’).

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 for:

  • NSLocationAlwaysUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysAndWhenInUseUsageDescription
  • NSMotionUsageDescription

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 for the property “Privacy - Location Always Usage Description”.
  • Repeat for the property “Privacy - Location Always and When In Use Usage Description”.
  • Repeat for the property “Privacy - Motion Usage Description”

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

Set Background Mode

In order to receive location updates in the background you must update the “Background Modes” as follows:

  • Go to the “Capabilities” tab of your Xcode project file in Xcode.
  • Switch “Background Modes” from OFF to ON.
  • Select the checkbox next to “Location Updates”

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.

Insert your API Key

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

[FactualEngine startWithApiKey:@"your Api Key Goes Here"