factual

Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

iOS

Getting Started

The steps below will guide you through installing the 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 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.

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


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 'https://github.com/Factual/cocoapods.git'
source 'https://github.com/CocoaPods/Specs.git'

target 'YourAppTarget' do
  pod 'FactualEngineSDK'
end

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

permissions
info.plist properties

NSLocationAlwaysUsageDescription

Privacy - Location Always Usage Description

NSLocationWhenInUseUsageDescription

Privacy - Location When In Use Usage Description

NSLocationAlwaysAndWhenInUseUsageDescription

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 "Capabilities" tab of your Xcode project file in Xcode.
  • Switch "Background Modes" from OFF to ON.
  • 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;

@end

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

@end

@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.
}

@end

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

[FactualEngine startWithApiKey:@"Your Api Key Goes Here"
                      delegate:self];

Further Code Examples

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

iOS


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.