Initialize the SDK

To use DriveMotion service and its features, the DriveMotionService needs to be initialized.

The initialize method will only need to be called once.

DriveMotionService initialization

Add below key to your Info.plist file. For example:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
</array>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Do you allow this app to know your current location?</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Do you allow this app to always know your location?</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Do you allow this app to know your current location?</string>
<key>NSMotionUsageDescription</key>
<string>Do you allow this app to track you motion data?</string>
...
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>location</string>
    <string>processing</string>
</array>

Import the library into your app:

Swift

1	`import TelenavDriveMotion`

Objective-C

    @import TelenavDriveMotion;

Create SDK options with account credentials:

Swift

    let options = TNSDKOptionsBuilder()
        .apiKey("API_KEY_PROVIDED_BY_TELENAV")
        .apiSecret("API_SECRET_PROVIDED_BY_TELENAV")
        .cloudEndPoint("CLOUD_ENDPOINT_PROVIDED_BY_TELENAV")
        .appInfo(name: "APPLICATION_NAME", version: "APPLICATION_VERSION")
        .userId("USER_ID")
        .deviceGuid("DEVICE_ID")
        .allowDataCollection(true)
        .build()

Objective-C

    TNSDKOptionsBuilder *builder = [TNSDKOptionsBuilder new];
    [builder apiKey:@"API_KEY_PROVIDED_BY_TELENAV"];
    [builder apiSecret:@"API_SECRET_PROVIDED_BY_TELENAV"];
    [builder cloudEndPoint:@"CLOUD_ENDPOINT_PROVIDED_BY_TELENAV"];
    [builder appInfoWithName:@"APPLICATION_NAME" version:@"APPLICATION_VERSION"];
    [builder userId:@"USER_ID"];
    [builder deviceGuid:@"DEVICE_ID"];
    [builder allowDataCollection:YES];
    TNSDKOptions *options = [builder build];

Create DriveMotion settings:

Swift

    let settings = TNDriveMotionSettingsBuilder()
        .driveDetectionMode(.auto)
        .delegate(self)
        .alertDelegate(self) // Optional
        .scoringInterval(.MONTH) // Optional
        .optInRequired(false)
        .userAlias('USER_ALIAS') //Optional, default is ""
        .userState('USER_STATE') //Optional, default is ""
        .isDeviceGuidOverrodeByForce(false) // Optional, default is false
        .isExternalUserIdUsedByForce(false) // Optional, default is false
        .analyticsQueryMode(#QUERY_MODE#) // Optional, default is userBase, added in 2.0
        .edgeEventDetectMode(#DETECT_MODE#) // Optional, default is all, added in 2.12.0
        .loggerSettings(#TNLoggerSettings#) // Optional
        .isEdgeMatcherEnabled(false) // Optional, default is false, added in 2.16.5
        .configDelegate(#TelenavDriveMotionAPI.TNDriveMotionConfigDelegate Implementation#) // Optional, default is nil, added in 2.22.0
        .build()

Objective-C

    TNDriveMotionSettingsBuilder *builder = [TNDriveMotionSettings builder];
    [builder driveDetectionMode:TNDriveDetectionModeAuto];
    [builder delegate:self];
    [builder alertDelegate:self]; // Optional
    [builder scoringInterval:TNScoringIntervalMONTH]; // Optional
    [builder optInRequired:NO];
    [builder userAlias:"USER_ALIAS"];
    [builder userState:"USER_ALIAS"];
    [builder isDeviceGuidOverrodeByForce:NO]; // Optional, default is false
    [builder isExternalUserIdUsedByForce:NO]; // Optional, default is false
    [builder analyticsQueryMode:#query mode#]; // Optional, default is userBase, added in 2.0
    [builder edgeEventDetectMode:#detect mode#]; // Optional, default is all, added in 2.12.0
    [builder loggerSettings:#TNLoggerSettings#] // Optional
    [builder isEdgeMatcherEnabled:NO] // Optional, default is false, added in 2.16.5
    [builder configDelegate: #TelenavDriveMotionAPI.TNDriveMotionConfigDelegate Implementation#] // Optional, default is nil, added in 2.22.0
    TNDriveMotionSettings *settings = [builder build];

Implement TNDriveMotionDelegate

See DriveMotionDelegate
Implement TNDriveMotionAlertDelegate

See DriveMotionAlertDelegate

Request location services authorization:

Swift

    import CoreLocation
    ...
    let manager = CLLocationManager()
    manager.requestAlwaysAuthorization()

Objective-C

    @import CoreLocation;
    ...
    CLLocationManager *manager = [CLLocationManager new];
    [manager requestAlwaysAuthorization];

Synchronous initialize DriveMotionService with options and settings: [Deprecated]

Note

Initialization in synchronous is deprecated in release 1.2.1 and will be removed in few releases, please use asynchronous initialization instead.

Swift

    try TNDriveMotionService.initialize(sdkOptions: options,
                                        driveMotionSettings: settings)

Objective-C

    NSError *error;
    [TNDriveMotionService initializeWithSdkOptions:options
                               driveMotionSettings:settings
                                             error:&error];

Asynchronous initialize DriveMotionService with options and settings:

Swift

    TNDriveMotionService.initialize(sdkOptions: options, driveMotionSettings: settings) { result, error in
        if result {
            // Initialize success
        } else {
            // The SDK initialization failed. Please check the message of DriveMotionException and perform subsequent operations according to the message.
        }
    }

Objective-C

    [TNDriveMotionService initializeWithSdkOptions:options
                            driveMotionSettings:settings
                                        handler:^(BOOL result, TNDriveMotionException * _Nullable error) {
        if (result) {
            // Initialize success
        } else {
            // The SDK initialization failed. Please check the message of DriveMotionException and perform subsequent operations according to the message.
        }
    }];

Implement TNDriveMotionConfigDelegate

See DriveMotionConfigDelegate

Note

If you need to re-initialize the DriveMotion SDK or effect the updated configs, please call shutdown() and then initialize().
You can use isInitialized() API to check whether the SDK initialized or not.

Warning

The fields apiKey, apiSecret, cloudEndPoint, appInfo, userId, deviceGuid of TNSDKOptions must be filled because they are mandatory for DriveMotion functionality.

Log Settings

The DriveMotion SDK allows external applications to customize the logging behavior by configuring basic information before initializing the DriveMotion SDK. In the absence of explicit configuration, the SDK defaults to initializing the log with default settings during the DriveMotion initialization process.

Initialize TNLoggerSettings

Customize the logging system using three parameters, then set TNLoggerSettings to DriveMotionSettings.

[[TNLoggerSettings alloc] initWithLevel:TNLogLevelAll rootPath:rootPath fileNamePrefix:@"sdk_log"];

level: The lowest level of log, default is all.
rootPath: log file root path, default is ./Documents.
fileNamePrefix: file prefix name, default is log, file name is log_2023-11-16.

Initialize Bluetooth

Trigger the Bluetooth permission request by initializing the system’s CBCentralManager. This method should be called by the integration app at an appropriate time to control when the Bluetooth permission prompt appears.

=== "Swift"

    ```swift
        try TNDriveMotionService.initializeBluetooth()
    ```

=== "Objective-C"

    ```objc
        NSError *error;
        [TNDriveMotionService initializeBluetoothAndReturnError:&error];
    ```

This method must be called before using any Bluetooth-related features in the SDK.
Internally, this will instantiate a CBCentralManager, prompting the system to request Bluetooth permission if not yet granted.
This API gives developers explicit control over the timing of the system permission dialog.

Warning

if this method is not called, SDK components that rely on Bluetooth may not function properly.