SDK for iOS app
Download the iOS Telematics SDK and install it in your environment
Introduction
Here you can find a short video guide, how to add Telematics SDK to your iOS app:
To utilize our telematics environment in your iOS app, you should integrate the Telematics SDK iOS framework into your app.
While you could manually add the framework, we strongly recommend using the CocoaPods dependency manager. If your project already uses other CocoaPods, continue after this first step:
Adding the SDK to your project
Install CocoaPods
Skip this step, If your project already has CocoaPods
- open a terminal window in the main project folder
- run the following commands to install CocoaPods and create a "Podfile":
$ sudo gem install cocoapods
$ pod init
Add the SDK to your Podfile
- locate 'Podfile' in the main project folder
- using your preferred text editor, add the following line to your Podfile:
pod 'RaxelPulse'
- open a terminal window in the main project folder
- run the following commands in a terminal window to re-evaluate the Podfile, and add the RaxelPulse library to your project
$ pod install
Setting up the SDK
Please check RaxelPulse target in pod Always
Embed Swift Standard Libraries: NO
Use this in your project target
Always Embed Swift Standard Libraries: YES
Enable capabilities
Configure the information property list file (Info.plist) with an XML snippet that contains data about your app.
Right-click info.plist, and choose Open As Source Code. Add capabilities for privacy, motion usage etc.
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Your explanation.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Your explanation.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your explanation.</string>
<key>NSMotionUsageDescription</key>
<string>Your explanation.</string>
Background location
<key>UIBackgroundModes</key>
<array>
<string>fetch</string>
<string>location</string>
<string>remote-notification</string>
</array>
Background location request explanation for users and Apple inc.
The most popular explanation is: We're using location services to determine your driving style.
Enable and Schedule Background Tasks
Starting from version 5.12 and new:
We use Background Tasks to improve upload recorded tracks, and send Heartbeats.
To configure your app to allow background tasks, enable the background capabilities that you need, and then create a list of unique identifiers for each task.
There are two types of background tasks: BGAppRefreshTask
and BGProcessingTask
. BGAppRefreshTask
is for short-duration tasks that expect quick results, such as downloading a stock quote. BGProcessingTask
is for tasks that might be time-consuming, such as downloading a large file or synchronizing data. Your app can use one or both of these.
To add the capabilities:
- Open the project editor and select the desired target.
- Click Signing & Capabilities.
- Expand the Background Modes section. If the target doesn’t have a Background Modes section, click + Capability, and then select Background Modes.
- If you’re using
BGAppRefreshTask
, select ”Background fetch.“ - If you’re using
BGProcessingTask
, select ”Background processing.“
You control which tasks run in the background by registering a list of permitted task identifiers.
To create this list, add the identifiers to the Info.plist
file.
- Open the project navigator and select your target.
- Click Info and expand Custom iOS Target Properties.
- Add a new item to the list and choose ”Permitted background task scheduler identifiers,“ which corresponds to the
BGTaskSchedulerPermittedIdentifiers
array. - Add the string for each authorized task identifier as a separate item in the array.
In iOS 13 and later, adding a BGTaskSchedulerPermittedIdentifiers
key to the Info.plist disables the application:performFetchWithCompletionHandler:
and setMinimumBackgroundFetchInterval:
methods.
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>sdk.damoov.apprefreshtaskid</string>
<string>sdk.damoov.appprocessingtaskid</string>
</array>
SDK Initialization
First, initialize a new RPEntry class instance with a specified device ID. This method must be the first method calling from RaxelPulse SDK in application didFinishLaunchingWithOptions
method.
RPEntry.initialize(withRequestingPermissions: false)
[RPEntry initializeWithRequestingPermissions:NO]
App delegate
[Important] Starting from version 6.0.1
- (void)applicationWillEnterForeground:(UIApplication *)application {
[RPEntry applicationWillEnterForeground:application];
}
func applicationWillEnterForeground(_ application: UIApplication) {
RPEntry.applicationWillEnterForeground(application)
}
Important notifications
Note that these notifications are customized, you can use your own text.
Low power mode
@interface AppDelegate () <RPLowPowerModeDelegate> {
[RPEntry instance].lowPowerModeDelegate = self;
}
class AppDelegate: RPLowPowerModeDelegate {
RPEntry.instance().lowPowerModeDelegate = self
}
Delegate method:
- (void)lowPowerMode:(Boolean)state {
if (state) {
// You can create push in this place and fire about this, as example
UNMutableNotificationContent *content = [[UNMutableNotificationContent alloc] init];
content.title = @"Low Power Mode";
content.body = [NSString stringWithFormat:@"Your trips may be not recorded. Please, follow to Settings=>Battery=>Low Power"];
UNTimeIntervalNotificationTrigger *trigger = [UNTimeIntervalNotificationTrigger triggerWithTimeInterval:1 repeats:NO];
UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:@"overspeed" content:content trigger:trigger];
[[UNUserNotificationCenter currentNotificationCenter] addNotificationRequest:request withCompletionHandler:nil];
}
}
func lowPowerMode(_ state: Bool) {
if (state) {
self.showNotification(title: "Low Power Mode", body: "Your trips may be not recorded. Please, follow to Settings=>Battery=>Low Power")
}
}
func showNotification(title: String, body: String) {
let content = UNMutableNotificationContent()
content.title = title
content.subtitle = body
content.sound = UNNotificationSound.default
let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 5, repeats: false)
let request = UNNotificationRequest(identifier: UUID().uuidString, content: content, trigger: trigger)
UNUserNotificationCenter.current().add(request)
}
Low accuracy
@interface AppDelegate () <RPAccuracyAuthorizationDelegate> {
[RPEntry instance].accuracyAuthorizationDelegate = self;
}
class AppDelegate: RPAccuracyAuthorizationDelegate {
RPEntry.instance().accuracyAuthorizationDelegate = self
}
Delegate method:
- (void)wrongAccuracyAuthorization {
// You can create push in this place and fire about this, as example
UNMutableNotificationContent *content = [[UNMutableNotificationContent alloc] init];
content.title = @"Precise Location is off";
content.body = [NSString stringWithFormat:@"Your trips may be not recorded. Please, follow to App Settings=>Location=>Precise Location"];
UNTimeIntervalNotificationTrigger *trigger = [UNTimeIntervalNotificationTrigger triggerWithTimeInterval:1 repeats:NO];
UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:@"overspeed" content:content trigger:trigger];
[[UNUserNotificationCenter currentNotificationCenter] addNotificationRequest:request withCompletionHandler:nil];
}
func wrongAccuracyAuthorization() {
self.showNotification(title: "Precise Location is off", body: "Your trips may be not recorded. Please, follow to App Settings=>Location=>Precise Location")
}
func showNotification(title: String, body: String) {
let content = UNMutableNotificationContent()
content.title = title
content.subtitle = body
content.sound = UNNotificationSound.default
let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 5, repeats: false)
let request = UNNotificationRequest(identifier: UUID().uuidString, content: content, trigger: trigger)
UNUserNotificationCenter.current().add(request)
}
Permissions wizard
Note that the SDK has a built-in Permissions Wizard and a Permissions Dialog that are fully customizable. Wizard for iOS app
Without these permissions, SDK can not be enabled.
Here you can find an example with the correct Permissions Wizard flow:
Permissions in iOS
Setting up the permissions wizard
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[[RPPermissionsWizard returnInstance] launchWithFinish:^(BOOL showWizzard) {
[RPEntry initializeWithRequestingPermissions:YES]; // Yes, if you don’t want to implement requesting by yourself
[RPEntry instance].disableTracking = NO;
[RPEntry application:application didFinishLaunchingWithOptions:launchOptions];
}];
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
RPPermissionsWizard.returnInstance().launch(finish: { _ in
RPEntry.initialize(withRequestingPermissions: true)
let token = NSString(string: "Please, enter your Token")
RPEntry.instance().virtualDeviceToken = token
let options = launchOptions ?? [:]
RPEntry.application(application, didFinishLaunchingWithOptions: options)
})
return true
}
App delegate methods
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(nonnull NSString *)identifier completionHandler:(nonnull void (^)(void))completionHandler {
[RPEntry application:application handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
}
- (void)applicationDidReceiveMemoryWarning:(UIApplication *)application {
[RPEntry applicationDidReceiveMemoryWarning:application];
}
- (void)applicationWillTerminate:(UIApplication *)application {
[RPEntry applicationWillTerminate:application];
}
- (void)applicationDidEnterBackground:(UIApplication *)application {
[RPEntry applicationDidEnterBackground:application];
}
- (void)applicationDidBecomeActive:(UIApplication *)application {
[RPEntry applicationDidBecomeActive:application];
}
- (void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
[RPEntry application:application performFetchWithCompletionHandler:^{
completionHandler(UIBackgroundFetchResultNewData);
}];
}
func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
RPEntry.application(application, handleEventsForBackgroundURLSession: identifier, completionHandler: completionHandler)
}
func applicationDidReceiveMemoryWarning(_ application: UIApplication) {
RPEntry.applicationDidReceiveMemoryWarning(application)
}
func applicationWillTerminate(_ application: UIApplication) {
RPEntry.applicationWillTerminate(application)
}
func applicationDidEnterBackground(_ application: UIApplication) {
RPEntry.applicationDidEnterBackground(application)
}
func applicationDidBecomeActive(_ application: UIApplication) {
RPEntry.applicationDidBecomeActive(application)
}
func application(_ application: UIApplication, performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
RPEntry.application(application) {
completionHandler(.newData)
}
}
Enable high-frequency data collection (HF)
We strongly recommend keeping it enabled by default
Enable high-frequency data collection to accurate and persistent dataset
[RPEntry enableHF:true];
RPEntry.enableHF(true)
Enable Accident detection.
Accident detection is disabled by default. You can enable detection.
In order for accident detection to work, you need to enable high-frequency data collection
[RPEntry enableAccidents:true];
RPEntry.enableAccidents(true)
Enable SDK
Set a DeviceToken to SDK to enable it / SDK Log in.
DeviceToken
Empty or nil DeviceToken is not allowed.
To get a unique deviceToken for each user, you need to
- Use a deviceToken of the test SDK user, created via DataHub earlier (follow this guide
- OR [Setup the SDK login and authorization] (https://docs.telematicssdk.com/docs/set-up-the-sdk-login-and-api-authentication) (via iOS LoginAuth Framework or API)
[RPEntry instance].virtualDeviceToken = @"VIRTUAL_DEVICE_TOKEN";
let token = NSString(string: "VIRTUAL_DEVICE_TOKEN") //REQUIRED!
RPEntry.instance().virtualDeviceToken = token
Log out SDK
[[RPEntry instance] removeVirtualDeviceToken];
RPEntry.instance().removeVirtualDeviceToken()
Usage example for log in/ log out to follow the host app
if ([self userIsAuthenticated]) {
[RPEntry instance].virtualDeviceToken = [self getDeviceToken];
} else {
/// empty device token is not allowed
/// Use removeVirtualDeviceToken method for log out from the host app.
[[RPEntry instance] removeVirtualDeviceToken];
}
if (userIsAuthenticated) {
let token = NSString(string: "VIRTUAL_DEVICE_TOKEN") //REQUIRED!
RPEntry.instance().virtualDeviceToken = token
} else {
/// empty device token is not allowed
/// Use removeVirtualDeviceToken method for log out from the host app.
RPEntry.instance().removeVirtualDeviceToken()
}
Update SDK
Regularly update SDK
We regularly make announcement emails for all registered in DataHub users about new critical SDK updates.
Stay in touch with the help of our detailed Changelog: https://docs.telematicssdk.com/changelog/sdk-for-ios
- open a terminal window in the main project folder
- run the following command in a terminal window
$ pod update
Update SDK to a specific version
In order to update to a specific version, you need to write in the PodFile:
pod 'RaxelPulse', '5.12'
where 5.12
- number of specific version
Updated 4 months ago