Getting Started

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


After completing the Getting Started guide please refer to the rest of our developer docs for examples of how to:

1. Ensure the SDK requirements are met

  • The Factual Location Engine SDK is compatible with iOS 8.0+ and above
  • 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.

2. Get an API key

Sign up for access to Engine.

3: Install CocoaPods

Installing the SDK via CocoaPods automates the majority of the installation process for you.

sudo gem install cocoapods


For manual installation please see the instructions here , then skip to step 6.

4: Construct a Podfile

Once you’ve installed the CocoaPods Ruby Gem, create a file in your Xcode project directory named Podfile, for example:

source ''
source ''

target 'YourAppTarget' do
  pod 'FactualEngineSDK'

5: Install the SDK

To install the SDK Cocoapod, navigate to the directory of your Xcode app project in your terminal and run the following command:

pod install

You should now be able to start development using the new Xcode project workspace created by CocoaPods.


6. Disable Bitcode

The Factual Location Engine SDK is not compatible with bitcode. To disable set the Enable Bitcode option in Build Options to No


7. Set Location Authorization Messaging

You must ensure the InfoPlist.strings values associated with location authorizations are properly defined. These values define the messages that will be displayed to your users when prompting for the appropriate authorizations. The SDK requires values defined for:


info.plist properties


Privacy - Location Always Usage Description


Privacy - Location When In Use Usage Description


Privacy - Location Always and When In Use Usage Description

  • 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 enter your desired prompt text for each of the properties listed in the table above

8. Set Background Mode

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

  • Go to the "Signing & Capabilities" tab of your Xcode project file in Xcode.
  • Click "+ Capability" and search for "Background Modes". Double-click on "Background Modes."
  • Select the checkbox next to "Location Updates"

9. Follow the sample implementation

The example code below will:

  • Initialize and start Engine, in conjunction with the required permission checks

Import the Engine header and add the FactualEngineDelegate interface

#import <UIKit/UIKit.h>
#import "FactualEngine.h"

@interface AppDelegate : UIResponder <UIApplicationDelegate,
                                      FactualEngineDelegate> // Engine system debug info

@property (strong, nonatomic) UIWindow *window;


Implement the Factual delegates


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.

#import "AppDelegate.h"

@interface AppDelegate ()
@property CLLocationManager *manager; // Engine assumes you are managing location permissions


@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // for demonstration, we're requesting location permissions here:
  if (_manager == nil) {
    _manager = [[CLLocationManager alloc] init];
  [_manager requestAlwaysAuthorization];
  // start the SDK.
  // Note, you don't need to worry about whether or not the necessary
  // authorizations have returned from the user before calling start.
  // Engine will automatically detect for any changes to location
  // authorizations and behave accordingly.
  [FactualEngine startWithApiKey:@"Your API Key Here"
                        delegate:self]; // FactualEngineDelegate
  return YES;

// ---- methods to support the FactualEngineDelegate interface ----
- (void)engineDidStartWithInstance:(FactualEngine *)engine {
  NSLog(@"Engine started.");

- (void)engineDidStop{
  NSLog(@"Engine stopped.");

- (void)engineDidFailWithError:(FactualError *)error{
  NSLog(@"Engine error: %@", [error message]);

- (void)engineDidReportInfo:(NSString *)infoMessage{
  NSLog(@"Engine debug info: %@", infoMessage);

- (void)engineDidSyncWithGarage{
  NSLog(@"Engine updated configuration.");

- (void)engineDidLoadConfig:(FactualConfigMetadata *)data{
  NSLog(@"Engine config loaded: %@", [data version]);

- (void)engineDidReportDiagnosticMessage:(nonnull NSString *)diagnosticMessage {
  // Delivers structured diagnostic data that is helpful for Factual when evaluating performance
  // and diagnosing issues.

- (void)circumstancesMet:(NSArray<CircumstanceResponse *> *)circumstanceResponses{
  for (CircumstanceResponse *circumstanceResponse in circumstanceResponses) {
    NSString *circumstanceId = circumstanceResponse.circumstance.circumstanceId;
    NSArray<NSString *> *tags = circumstanceResponse.circumstance.tags;
    NSLog(@"Circumstance %@ with tags: %@ met.", circumstanceId, tags);



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

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

Further Code Examples


Look through the rest of our developer docs for examples on how to: