Integrate with iOS

This section outlines step-by-step instructions to integrate Zendrive SDK into your iOS application.

Before You Begin

Requirements

• Zendrive SDK works for iOS 13 and above. It will throw a compilation error for applications targeting iOS 12 or below.

• Zendrive SDK needs Swift 5.1 or above.

Preparation

• To use Zendrive SDK, you will need a Zendrive SDK Key. Sign up.

• Upgrade to the latest stable version of Xcode.

• This document contains code samples for both Swift and Objective-C. Please be sure to refer to the correct code tabs based on your needs.

Process Overview

1. Set up your project.

2. Enable Zendrive SDK.

3. Implement trip events.

4. Create a Zendrive Configuration.

5. Initialize Zendrive SDK.

6. Learn how and when to disable Zendrive SDK.

Once you have completed the above tasks, you are ready to go ahead to use Zendrive SDK with your application.

Additional Steps

Perform the following steps, in addition to the above:

1. Add any additional features.

2. Test your setup.

3. Look at Next Steps.

Set Up your Project

You can set up your project in Xcode using CocoaPods (recommended) or by directly linking the framework. We publish our SDK Swift Binary Framework as an xcframework bundle.

Use CocoaPods

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

1. Install CocoaPods.

2. Update CocoaPods. Our minimum supported version is 1.9.0. See Known Issues.

   $ sudo gem update cocoapods

3. Create a Podfile and use it in Xcode.

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

   pod 'ZendriveSDK', :git => 'https://bitbucket.org/zendrive-root/zendrive_cocoapod.git', :tag => '10.1.0'
   pod 'ZendriveSDKSwift', :git => 'https://bitbucket.org/zendrive-root/zendrive_cocoapod.git', :tag => '10.1.0'

Directly Link the Framework

If you don't use CocoaPods, you can directly add the required frameworks into your app.

1. Download all the frameworks required for your project.

2. Link the following system libraries:

   • CoreLocation.framework

   • CoreMotion.framework

   • CoreTelephony.framework

   • SystemConfiguration.framework

   • Accelerate.framework

   • libsqlite3.0.dylib

   • libz.1.1.3.dylib

3. Add the -ObjC and -lC++ linker flag to Other Linker Flags under Build Settings.

4. Add the dependencies you downloaded in Step 1 to the Embedded Binaries section:

   • SQLite.framework

   • AWSSQS.framework

   • AWSCore.framework

5. Go to project Target Settings -> General tab -> Frameworks, Libraries, and Embedded Content. Add ZendriveSDK.xcframework. Zendrive SDK and its dependencies need to be embedded with the application’s binary, as follows:

   1. Select the Do Not Embed option for the ZendriveSDK.xcframework.

   2. Select Embed & Sign for AWSCore.xcframework, AWSSQS.xcframework and SQLite.xcframework.

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.

2. Disable Bitcode for your app. The Zendrive SDK does not support Bitcode.

   1. On the Project Settings screen, select the relevant Target for your app.

   2. Click Build Settings.

   3. Search the options for Enable Bitcode.

   4. Ensure it is set to No.

3. Add the key NSLocationAlwaysUsageDescription to your Info.plist. Set its value to your custom text that tells the user why you want them to allow location services for the application. See sample text below.

   "We use location to better determine driving behavior
   and, in case of accident, let others know where you are."

   This is required for iOS 8 and above. See Apple's documentation.

4. Add the key NSMotionUsageDescription to your Info.plist. Set its value to your custom text that tells the user why you want them to allow motion services for the application. See sample text below.

   "We use activity to detect your driving trips faster and more accurately.
   This also reduces the amount of battery we use."

   This is used for better trip detection results. While we need you to add this key to your plist, this program requires an opt-in. If you want to take advantage of this program, please contact us to opt-in. If you choose not to, this permission will not be used.

Enable the SDK

Once the SDK is added to your project, import the header file in the file where you want to initialize the SDK.

Swift

import ZendriveSDKSwift

Objective-C

@import ZendriveSDK;

Implement Trip Events

This delegate receives various callbacks about interesting events from the Zendrive SDK. Define the implementation of the various callbacks.

Swift

import ZendriveSDKSwift

class ZendriveDelegateManager: NSObject, ZendriveDelegate {
    func processStart(ofDrive startInfo: DriveStartInfo) {
        print("Drive started")
    }
    
    func processResume(ofDrive resumeInfo: DriveResumeInfo) {
        print("Drive is resumed")
    }
    
    func processEnd(ofDrive estimatedDriveInfo: EstimatedDriveInfo) {
        print("Drive ended")
    }
    
    func processAnalysis(ofDrive analyzedDriveInfo: AnalyzedDriveInfo) {
        print("Drive analyzed")
    }
    
    /// This callback gives information about errors in device or
    /// application settings that may be affecting Zendrive SDK.
    func settingsChanged(_ settings: Settings) {
        if settings.errors.count == 0 {
            print("All settings are fine, no action needed")
        } else {
            print("Resolve errors in settings")
        }
    }
}

Objective-C

//MyApp.h
@interface ZendriveDelegateManager : NSObject <ZendriveDelegateProtocol>

@end

//MyApp.m
@import ZendriveSDK;

@implementation ZendriveDelegateManager


- (void)processStartOfDrive:(ZendriveDriveStartInfo *)startInfo {
    NSLog(@"Start of Drive invoked");
}

- (void)processResumeOfDrive:(ZendriveDriveResumeInfo *)drive {
    NSLog(@"Resume of Drive invoked");
}

- (void)processEndOfDrive:(ZendriveDriveInfo *)drive {
    NSLog(@"End of Drive invoked");
}

- (void)processAnalysisOfDrive:(ZendriveAnalyzedDriveInfo *)drive {
    NSLog(@"Analysis of drive invoked");
}

// This callback gives information about errors in device or
// application settings that may be affecting Zendrive SDK.
- (void)settingsChanged:(ZendriveSettings *_Nonnull)settings {
    if(settings.errors.count == 0) {
        NSLog(@"All settings are fine, no action needed");
    } else {
        NSLog(@"Resolve errors in settings");
    }
}

- (void)processAccidentDetected:(ZendriveAccidentInfo *)accidentInfo {
    NSLog(@"Accident detected by Zendrive SDK.");
}

@end

Create a Zendrive Configuration

Define your SDK Key and Driver ID.

Swift

// Create a Zendrive Configuration.
    let configuration: Configuration = Configuration()
    configuration.applicationKey = @"ZENDRIVE_SDK_KEY"; // REQUIRED. This is your Zendrive SDK key.
    configuration.driverId = @"<your-driver-id>"; // REQUIRED
// If you're using Automatic Drive Detection, set the following attribute.    
    configuration.driveDetectionMode = .autoON;

Objective-C

// Create a Zendrive Configuration.
    ZendriveConfiguration *configuration = [[ZendriveConfiguration alloc] init];
    configuration.applicationKey = @"ZENDRIVE_SDK_KEY"; // REQUIRED. This is your Zendrive SDK key.
    configuration.driverId = @"<your-driver-id>"; // REQUIRED
// If you're using Automatic Drive Detection, set the following attribute.    
    configuration.driveDetectionMode = ZendriveDriveDetectionModeAutoON;

(Optional) Before your setup call, provide ZendriveDriverAttributes for your particular driver.

Swift

// You can provide meta-information about the driver before setting up the SDK.
// This step is optional.
    let driverAttributes: DriverAttributes = DriverAttributes()
// A human recognizable alias for the driver that will be visible in the dashboard
    driverAttributes.setAlias("Homer13v2")
    driverAttributes.setCustomAttribute("custom-attribute", forKey: "custom-key")
    driverAttributes.setVehicleType(.car) //.car or .motorcycle. Contact us to use.
    configuration.driverAttributes = driverAttributes;
    

Objective-C

// You can provide meta-information about the driver before setting up the SDK.
// This step is optional.
    ZendriveDriverAttributes *driverAttributes = [[ZendriveDriverAttributes alloc] init];
// A human recognizable alias for the driver that will be visible in the dashboard
    [driverAttributes setAlias:@"Homer13v2"]; 
    [driverAttributes setCustomAttribute:@"custom-attribute" forKey:@"custom-key"];
    configuration.driverAttributes = driverAttributes;

Initialize the SDK

Initialize the SDK with your SDK Key and a driver ID which will identify this driver in the system. When Zendrive SDK is setup for the first time, it requests location access from iOS.

Initialize (Swift)

func initializeZendriveSDK() {
    // You can optionally provide a delegate to receive callbacks from the SDK.
    // This is passed to the SDK in the setup method.
    
    let zdDelegate: ZendriveDelegate = ZendriveDelegateManager()
    self.zendriveDelegate = zdDelegate // keep a strong reference to the delegate object
    
    
    ...
    
    // Setup Zendrive SDK. Drive tracing will begin automatically on successful setup.
    Zendrive.setup(with: configuration, delegate: self, completionHandler: {
        success, error in
        if success {
            print("SDK setup is successful.")
        }
        else {
            print("Setup failed.")
        }
    }
}

Complete sample (Swift)

func initializeZendriveSDK() {
    // You can optionally provide a delegate to receive callbacks from the SDK.
    // This is passed to the SDK in the setup method.
    
    let zdDelegate: ZendriveDelegate = ZendriveDelegateManager()
    self.zendriveDelegate = zdDelegate // keep a strong reference to the delegate object
    
    // Create a Zendrive Configuration.
    let configuration: Configuration = Configuration()
    configuration.applicationKey = @"ZENDRIVE_SDK_KEY"; // REQUIRED. This is your Zendrive SDK key.
    configuration.driverId = @"<your-driver-id>"; // REQUIRED
    configuration.driveDetectionMode = .autoON;
    
    // You can provide meta-information about the driver before setting up the SDK.
    // This step is optional.
    let driverAttributes: DriverAttributes = DriverAttributes()
    driverAttributes.setAlias("Homer13v2")
    driverAttributes.setCustomAttribute("custom-attribute", forKey: "custom-key")
    configuration.driverAttributes = driverAttributes;
    
    // Setup Zendrive SDK. Drive tracing will begin automatically on successful setup.
    Zendrive.setup(with: configuration, delegate: self, completionHandler: {
        success, error in
        if success {
            print("SDK setup is successful.")
        }
        else {
            print("Setup failed.")
        }
    }
}

Initialize (Obj-C)

- (void)initializeZendriveSDK {

    // You can optionally provide a delegate to receive callbacks from the SDK.
    // This is passed to the SDK in the setup method.
    id<ZendriveDelegateProtocol> zdDelegate = [[ZendriveDelegateManager alloc] init];
    self.zendriveDelegate = zdDelegate; // keep a strong reference to the delegate object

    ...

    // Setup Zendrive SDK. Drive tracing will begin automatically on successful setup.
    [Zendrive setupWithConfiguration:configuration
     delegate:zdDelegate // Can be nil
     completionHandler:^(BOOL success, NSError *error) {
        if(success) {
            NSLog(@"SDK setup is successful.");
        } else {
            NSLog(@"Setup failed.");
        }
    }];
}

Complete sample (Obj-C)

- (void)initializeZendriveSDK {

    // You can optionally provide a delegate to receive callbacks from the SDK.
    // This is passed to the SDK in the setup method.
    id<ZendriveDelegateProtocol> zdDelegate = [[ZendriveDelegateManager alloc] init];
    self.zendriveDelegate = zdDelegate; // keep a strong reference to the delegate object

    // Setup Zendrive.
    ZendriveConfiguration *configuration = [[ZendriveConfiguration alloc] init];
    configuration.applicationKey = @"ZENDRIVE_SDK_KEY"; // REQUIRED. This is your Zendrive SDK key.
    configuration.driverId = @"<your-driver-id>"; // REQUIRED
    configuration.driveDetectionMode = ZendriveDriveDetectionModeAutoON; // OPTIONAL

    // You can provide meta-information about the driver before setting up the SDK.
    // This step is optional.
    ZendriveDriverAttributes *driverAttributes = [[ZendriveDriverAttributes alloc] init];
    [driverAttributes setAlias:@"Homer13v2"]; // A human recognizable alias for the driver that will be visible in the dashboard
    [driverAttributes setCustomAttribute:@"custom-attribute" forKey:@"custom-key"];
    configuration.driverAttributes = driverAttributes;

    // Setup Zendrive SDK. Drive tracing will begin automatically on successful setup.
    [Zendrive setupWithConfiguration:configuration
     delegate:zdDelegate // Can be nil
     completionHandler:^(BOOL success, NSError *error) {
        if(success) {
            NSLog(@"SDK setup is successful.");
        } else {
            NSLog(@"Setup failed.");
        }
    }];
}

Your SDK Setup code structure should look similar to the Complete Sample tab above. The driver ID is an identifier for the driver currently using the application. Each driver using the application needs a unique ID.

More Resources:

• The driver ID will be returned in the Server APIs responses.

• Method Reference: setupWithConfiguration.

Call Zendrive.setup on Every Launch

Zendrive.setup must be called on every app launch. There are 2 options:

• Call the setup method from didFinishLaunchingWithOptions or,

• Call the setup method from the initial view controller of your application.

Resume Zendrive SDK

We have provided a convenient method to set up Zendrive SDK, called resumeWithDelegate:completionHandler:. This method can be used in addition to the Zendrive Setup method +setupWithConfiguration:delegate:completionHandler:.

• This method can be used to set up Zendrive SDK quickly, from the second time SDK is set up.

• This method sets up Zendrive SDK using the ZendriveConfiguration that was provided to the +setupWithConfiguration:delegate:completionHandler: method.

• Call this method from the -[UIApplicationDelegate applicationDidBecomeActive:] method.

• Make sure you provide the same ZendriveDelegateProtocol reference to both the resume and setup methods.

Disable the SDK

To disable the SDK at any point in the application, you can invoke the teardownWithCompletionHandler method. Zendrive SDK goes completely silent after this call and does not track any driving behaviour.

Swift

Zendrive.teardown(completionHandler: {
    //teardown completed
})

Objective-C

[Zendrive teardownWithCompletionHandler:^{
    // teardown completed
}];

The application needs to reinitialize the SDK to start tracking driving behaviour.

Add Additional Features

Zendrive SDK provides a number of features that you can use to control how and when trips are detected and where you can implement your business logic.

Click a link below to know more about the feature you want:

• Collision Detection: Set up and test Automatic Collision Detection (ACN). ACN is enabled by default.

• Manual Trip Tagging: Set up the SDK to manually start and stop trip detection. This is useful for apps with known start and end points, for example, taxi-metering apps.

• Vehicle Tagging: Connect the Zendrive SDK to a car bluetooth stereo.

• Driving Sessions: Compile multiple point-to-point trips into a single session.

• Controlling Automatic Drive Detection: Toggle drive detection mode to prevent automatic trip detection when a driver is not on duty.

Test Your Setup

Before you use Zendrive SDK, we strongly recommend using our testing framework to simulate drives and perform 'at-desk' integration testing.

iOS Testing Framework

Next Steps

Once you finish the steps above, your app now has the Zendrive SDK integrated.

Also see:

iOS Checklist and FAQChanges in iOS VersionsiOS PermissionsServer Integrations