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

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

  • NSLocationAlwaysUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysAndWhenInUseUsageDescription

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

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.

Insert your API Key

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

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