Skip to main content

Integrate the Fairmatic iOS SDK

Before You Begin​

We have created a sample app to demonstrate the basic use of the Fairmatic SDK. We have referred to this app in multiple places throughout the documentation. Here is the link for the app.

Requirements​

  • The SDK supports iOS 13 or above. Your app should target iOS 13 or above to use the SDK.
  • You should have the latest stable version of Xcode installed.
  • Sign in to the Fairmatic dashboard to access your Fairmatic SDK Key.

1. Setup your Project​

You can set up your project in Xcode using CocoaPods (recommended) or using the Swift Package Manager

Installation using Cocoapods​

The easiest way to integrate the Fairmatic iOS SDK and its dependencies into your application is by using the Fairmatic SDK CocoaPod.

  1. Install CocoaPods. See the CocoaPods Guide.

  2. Update CocoaPods.

    $ sudo gem update cocoapods

  3. Create a Podfile and use it in Xcode. See Instructions.

  4. Add the following to your Podfile and run the command: pod update

pod 'FairmaticSDK', :git => 'https://github.com/fairmatic/fairmatic-cocoapods', :tag => '3.0.1'
warning

If, after including the SDK, you get an error saying "duplicate symbols for architecture i386", then you might have already linked some frameworks directly. Importing the included frameworks with CocoaPods causes the duplication of the symbols.

In such a case, it is suggested that you remove the conflicting frameworks from your project and add them using CocoaPods.

Installation using Swift Package Manager​

  1. Open your project in the latest Xcode.
  2. Go to File > Swift Packages > Add Package Dependency...
  3. In the field, enter package repository URL, enter https://github.com/fairmatic/fairmatic-sdk-spm
  4. Pick the latest version and click Next.
  5. Click Finish
  6. Add the -ObjC flag to the Other Linker Flags section of your target's build settings.

2. Adjust Project Settings​

  1. Allow background location updates for your app.
    1. On the project screen, click Capabilities.
    2. Turn Background Modes on.
    3. Select Location updates.
    4. Select Background Fetch

Location Permission Screen and Keys​

The App Store publishes the following guidelines for apps using “Always Allow” location permission:

  • Your app must have an explicit notification to users that location and driving behavior data are being tracked, and the purpose of this tracking.
  • Your app must get explicit consent from users before collecting such information and disclose its use clearly. Directing users to and requiring acknowledgment of a privacy policy is not considered sufficient.
  • Include the following keys in your app's Info.plist:
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need background location permission to provide you with
driving analytics</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need background location permission to provide you with
driving analytics</string>
<key>NSMotionUsageDescription</key>
<string>We use activity to detect your trips faster and more accurately.
This also reduces the amount of battery we use.</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Bluetooth</string>
info

Even though we won't actually use Bluetooth features, Apple requires this message whenever Bluetooth code is present in an app. This is just a technical requirement.

Background Task ID​

For the Fairmatic SDK to be more accurate in uploading all trip data, it needs to have background fetch capability and a background task ID declared in your Info.plist file. You must add the following line in Info.plist file:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
	<string>com.fairmatic.sdk.bgrefreshtask</string>
</array>

In the case you already have a background refresh task, as iOS allows only one scheduled background fetch task, you will need to reuse your existing BGAppRefreshTask task to call the following function:

Fairmatic.logSDKHealth(.backgroundProcessing) { _ in
    // task.setTaskCompleted(success: success)
}

In this case, don’t add the new BGTaskSchedulerPermittedIdentifiers to your Info.plist.

3. Set up the Fairmatic SDK in code​

The following code snippet shows how to initialize the SDK. You will need the SDK key and the driver details.

// 1. Import the Fairmatic SDK module
import FairmaticSDK

// 2. Driver attributes creation
let driverAttributes = DriverAttributes(firstName: "John",
                                        lastName: "Doe",
                                        email: "john_doe@company.com",
                                        phoneNumber: "1234567890")

// 3. Creation of the config object using the SDK key, 
// driverId, and the above driver attributes.
let config = Configuration(sdkKey: "your_sdk_key_here",
                           driverId: "alphanumeric_driver_id",
                           driverAttributes: driverAttributes)

// 4. Set up the SDK with the config object, and check for success.
Fairmatic.setupWith(
    configuration: config
) { [weak self] success, error in
    if success {
        print("Fairmatic SDK setup successfully!")
    } else {
        print("Failed to init the Fairmatic SDK, error: \(error)")
    }
}
tip

Please put this code in your AppDelegate's didFinishLaunchingWithOptions() method if the driver details are already available in your app. This code should also be present in the flow when your driver logs in successfully to the app. The SDK's Fairmatic.setup() API should be called at every app launch with proper configuration. Failing to do so will result in errors in the trip APIs.

We recommend that in the completion handler of the setup API, you check the error parameter to be nil and the success parameter to be true if the SDK is set up or not. This is important to ensure that your application flow is not broken and the SDK APIs can be called properly.

Handling setup() API Errors​

The implementation included in this document for the setup() API function handles the errors returned in the completion handler. You can use that completion handler to display or hide error notifications for the setup() API. See our FairmaticError Appledoc for more details.