iOS
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:
- Use Circumstances to target users in real-time at interesting places
- Enable User-Journey to gather analytics on where your users go by
- Place-Attach on-demand to determine the place a user is at right now
- Enable remote analytics.
- Set a user's ad-id for use in remote analytics.
- Enable activity monitoring.
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 '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 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:
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 "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;
@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.
}
- (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);
}
}
@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:
- Use Circumstances to target users in real-time at interesting places
- Enable User-Journey to gather analytics on where your users go by
- Place-Attach on-demand to determine the place a user is at right now
- Enable remote analytics.
- Set a user's ad-id for use in remote analytics.
- Enable activity monitoring.
Updated 4 months ago