Guides
SIGN INSIGN UP

Methods for iOS app

First, initialize a new RPEntry class instance with a specified device ID. This method must be the first method calling from TelematicsSDK in the applicationdidFinishLaunchingWithOptions.

SDK Initialization

First, initialize a new RPEntry class instance with a specified device ID. This method must be the first method calling from TelematicsSDK in the applicationdidFinishLaunchingWithOptions method.

RPEntry.initializeSDK()
[RPEntry initializeSDK];

Log in

try RPEntry.instance.setDeviceID(deviceId: "DEVICE_ID")
RPEntry.instance.setEnableSdk(true)
NSError *error = nil;
BOOL success = [[RPEntry instance] setDeviceIDWithDeviceId:@"DEVICE_ID"
                                                     error:&error];
if (!success) {
     NSLog(@"Failed to set device id: %@", error);
}
[[RPEntry instance] setEnableSdk:true];

Log out

RPEntry.instance.logout()
[[RPEntry instance] logout];

Enable/ Disable SDK

📘

Empty or nil token is not allowed

Enable SDK

RPEntry.instance.setEnableSdk(true)
[[RPEntry instance] setEnableSdk:true];

Disable SDK

Note: It is not necessary to remove virtual device token. If sdk is disabled no any data will be collected.

❗ Starting from 7.0.0 the method triggers the following actions: stops tracking -> stops heartbeats -> forces unsent data upload -> disables the SDK.

RPEntry.instance.setEnableSdk(false)
[[RPEntry instance] setEnableSdk:false];

Check SDK status

let isSDKEnabled = RPEntry.instance.isSDKEnabled()
BOOL isSDKEnabled = [[RPEntry instance] isSDKEnabled];

Check required permissions status

let isGranted = RPEntry.instance.isAllRequiredPermissionsAndSensorsGranted()
BOOL isGranted = [[RPEntry instance] isAllRequiredPermissionsAndSensorsGranted];

Enable/ Disable Tracking

📘

Disable tracking doesn't disable SDK and it will continue to send Heartbeats. If you want the SDK to stop sending any data, you have to use Disable SDK method

Enable tracking

RPEntry.instance.setDisableTracking(disableTracking: false) //enable tracking
[[RPEntry instance] setDisableTrackingWithDisableTracking:NO]; //enable tracking

Disable tracking

RPEntry.instance.setDisableTracking(disableTracking: true) //disable tracking
[[RPEntry instance] setDisableTrackingWithDisableTracking:YES]; //disable tracking

Manual start/ stop tracking

Manual start tracking

📘

Manual start tracking doesn't disable automatic stop tracking. Methods startTracking() and stopTracking() must be called on the Main Thread.

RPEntry.instance.startTracking()
[[RPEntry instance] startTracking];

Manual stop tracking

RPEntry.instance.stopTracking()
[[RPEntry instance] stopTracking];

Persistent Tracking

📘

Persistent tracking ignores all stop tracking reasons and continues before 'stopTracking' method will be called. Max persistent tracking duration max is 10 hours. then, it will be automatically terminated.

Method startTrackAsPersistent() must be called on the Main Thread.

RPEntry.instance.startTrackAsPersistent()
[[RPEntry instance] startTrackAsPersistent];

Set max persistent tracking interval

Sets the maximum duration for a single persistent tracking session, in minutes. The SDK uses 240 minutes (4 hours) by default.

Use this method to limit how long persistent tracking may continue before the SDK automatically stops it. This can be used for compliance, battery preservation, or business rules that require capping continuous background tracking.

📘

The allowed range is from 5 minutes up to 600 minutes (10 hours). The method throws an error if the provided value is outside the allowed range.

try RPEntry.instance.setMaxPersistentTrackingInterval(minutes: 240)
NSError *error = nil;
BOOL success = [[RPEntry instance] setMaxPersistentTrackingIntervalWithMinutes:240
                                                                         error:&error];
if (!success) {
    NSLog(@"Failed to set max persistent tracking interval: %@", error);
}

Get max persistent tracking interval

Retrieves the current maximum duration, in minutes, allowed for a single persistent tracking session. The SDK uses this value to automatically stop long-running background tracking sessions once the limit is reached.

let maxPersistentTrackingInterval = RPEntry.instance.getMaxPersistentTrackingInterval()
NSInteger maxPersistentTrackingInterval = [[RPEntry instance] getMaxPersistentTrackingInterval];

Set tracking mode

Sets the tracking mode used by the SDK for both automatically and manually started tracking sessions.

Use this method to define whether tracking sessions started by SDK triggers, such as motion or location activity, should run in .standard or .persistent mode. Persistent tracking continues operating in the background and across app launches until explicitly stopped or until the maximum persistent tracking interval is reached.

📘

Using .persistent may increase battery usage and background activity. Ensure your app is configured with the required location permissions, background modes, and usage descriptions.

RPEntry.instance.setTrackingMode(.standard)
[[RPEntry instance] setTrackingMode:RPTrackingModeStandard];

Get tracking mode

Returns the tracking mode used by the SDK for both automatically and manually started tracking sessions. This value determines whether SDK-triggered tracking sessions run in .standard or .persistent mode. The default value is .standard.

let trackingMode = RPEntry.instance.getTrackingMode()
RPTrackingMode trackingMode = [[RPEntry instance] getTrackingMode];

Trip metadata

Use trip metadata to associate trips with business entities, such as an order, driver, vehicle, or shift.

Properties

Properties are a persistent flat key-value dictionary attached to trips.

Setting Properties replaces the whole dictionary. When tracking is active, changing the dictionary ends the current trip and starts a new trip with the updated Properties. Passing the same dictionary does not restart tracking.

Properties remain active for subsequent trips until they are replaced or cleared. They are cleared automatically on logout or when the device ID changes.

Set Properties

Sets the whole Properties dictionary. If tracking is active and the dictionary differs from the current one, the SDK completes the current trip and starts a new trip with the updated Properties.

do {
    try RPEntry.instance.setProperties(dict: [
        "order_id": "12345",
        "shift": "morning"
    ])
} catch {
    print("Unable to set Properties: \(error)")
}
NSError *error = nil;
BOOL success = [[RPEntry instance] setPropertiesWithDict:@{
    @"order_id": @"12345",
    @"shift": @"morning"
} error:&error];

if (!success) {
    NSLog(@"Unable to set Properties: %@", error);
}

Get Properties

Returns the current Properties dictionary. Use it to inspect the active metadata or to update one entry before setting the complete replacement dictionary.

let properties = RPEntry.instance.getProperties()
NSDictionary<NSString *, NSString *> *properties = [[RPEntry instance] getProperties];

Clear Properties

Removes all Properties. If tracking is active and Properties are not already empty, the SDK completes the current trip and starts a new trip without Properties.

RPEntry.instance.clearProperties()
[[RPEntry instance] clearProperties];
📘

Properties must contain from 1 to 20 entries. Keys and values must not be empty and must not exceed 255 characters. Use clearProperties() to remove all Properties.

Sub-units

Sub-units are a persistent flat key-value dictionary for analytical trip classification, for example a driver, vehicle, or session.

Setting or clearing Sub-units does not restart active tracking. Changes made while a trip is active are applied to the next trip. Sub-units remain active until they are replaced or cleared, and are cleared automatically on logout or when the device ID changes.

Set Sub-units

Sets the whole Sub-units dictionary. This method does not restart tracking.

do {
    try RPEntry.instance.setSubUnits(dict: [
        "DriverId": "D-001",
        "VehicleId": "V-042"
    ])
} catch {
    print("Unable to set Sub-units: \(error)")
}
NSError *error = nil;
BOOL success = [[RPEntry instance] setSubUnitsWithDict:@{
    @"DriverId": @"D-001",
    @"VehicleId": @"V-042"
} error:&error];

if (!success) {
    NSLog(@"Unable to set Sub-units: %@", error);
}

Get Sub-units

Returns the current Sub-units dictionary. Use it to inspect the active metadata or to update one entry before setting the complete replacement dictionary.

let subUnits = RPEntry.instance.getSubUnits()
NSDictionary<NSString *, NSString *> *subUnits = [[RPEntry instance] getSubUnits];

Clear Sub-units

Removes all Sub-units. This method does not restart tracking.

RPEntry.instance.clearSubUnits()
[[RPEntry instance] clearSubUnits];
📘

Sub-units must contain from 1 to 5 entries. Keys and values must not be empty and must not exceed 255 characters. Use clearSubUnits() to remove all Sub-units.

Activity Log

Use Activity Log to attach business events to the current active trip without stopping or splitting it, for example a delivery, checkpoint, or depot arrival.

do {
    try RPEntry.instance.addActivityLog(
        text: "Delivered order #101",
        data: ["order_id": "101"]
    )
} catch {
    print("Unable to add Activity Log entry: \(error)")
}
NSError *error = nil;
BOOL success = [[RPEntry instance] addActivityLogWithText:@"Delivered order #101"
                                                     data:@{@"order_id": @"101"}
                                                    error:&error];

if (!success) {
    NSLog(@"Unable to add Activity Log entry: %@", error);
}
📘

Activity Log entries can be added only while tracking is active. Each trip supports up to 100 entries. The text parameter is required and limited to 1,000 characters. The data dictionary is optional; pass an empty dictionary when no additional metadata is needed.

When Properties change during tracking, the current trip is completed. Its existing Activity Log entries remain attached to that completed trip; the new trip starts with an empty Activity Log.

Get SDK states

Get device ID registration state

Returns the latest known device identifier registration state.

Use this method to inspect whether the SDK has determined if the current device identifier is registered. The returned state includes both the registration status and the timestamp of the last check. A checkedAt value of 0 means the status has not been checked yet.

RPDeviceIdRegistrationState contains:

  • status - the latest known registration status.
  • checkedAt - the Unix timestamp, in seconds, when the registration status was last checked.

Available RPDeviceIdRegistrationStatus values: .notSet, .unknown, .registered, .notRegistered.

let deviceIdRegistrationState = RPEntry.instance.getDeviceIdRegistrationState()
RPDeviceIdRegistrationState *deviceIdRegistrationState = [[RPEntry instance] getDeviceIdRegistrationState];

Get tracking state

Returns the current tracking state of the SDK.

Use this method to asynchronously inspect whether tracking is currently available or unavailable. The result is delivered through the completion handler after the coordinator resolves the latest state.

RPTrackingState contains:

  • automaticTrackingStatus - status for automatic tracking.
  • manualTrackingStatus - status for manual tracking.

Available RPTrackingStatus values: .enabled, .deviceIdNotSet, .sdkDisabled, .disabledBySettings, .disabledByServer, .disabledBySchedule.

RPEntry.instance.getTrackingState { state in
    // Handle current tracking state
}
[[RPEntry instance] getTrackingStateWithCompletion:^(RPTrackingState * _Nonnull state) {
    // Handle current tracking state
}];

Enable Aggressive Heartbeats

The telematics SDK supports two operational modes for heartbeats;

Aggressive heartbeats- heartbeats are sent every 20 minutes. SDK is always active.
Normal Heartbeats - heartbeats are sent every 20 minutes but when SDK turns into Standby mode, it will be activated only by a new trip, and heartbeat will be sent respectively.

Note: Aggressive heartbeats significantly increases battery usage

Example:

RPEntry.instance.setAggressiveHeartbeats(false)
[[RPEntry instance] setAggressiveHeartbeats:NO];

Check state

Example:

RPEntry.instance.isAggressiveHeartbeats()
[[RPEntry instance] isAggressiveHeartbeats];

Enable Accidents detection.

Accidents detection is disabled by default. You can enable detection.
In order for accidents detection to work, you need to enable high-frequency data collection

RPEntry.instance.setAccidentDetectionEnabled(true)
[[RPEntry instance] setAccidentDetectionEnabled:YES];

Change Accident detection sensitivity.

Accident detection sensitivity is normal by default. You can change sensitivity. Sensitivity options which is available to apply: .normal, .sensitive, .tough

RPEntry.instance.setAccidentDetectionSensitivity(sensitivity: .normal)
[[RPEntry instance] setAccidentDetectionSensitivityWithSensitivity:RPAccidentDetectionSensitivityNormal];

Tags

📘

The detailed information about using Tags is available here

Get a list of trips

RPEntry.instance.api.getTracksWithOffset(0, limit: 10) { tracks, error in
    if let error {
        /// Implement updating your ViewController with error
        return
        }
        /// Implement updating your ViewController with new data
 }
[[RPEntry instance].api getTracksWithOffset:0
                                      limit:10
                                  startDate:nil
                                    endDate:nil
                                  ompletion:^(NSArray<RPTrackProcessed *> * _Nonnull tracks, NSError * _Nullable error) {
    if (error) {
        /// Implement updating your ViewController with error
        return;
    }
        /// Implement updating your ViewController with new data
    }];

Get trip details

RPEntry.instance.api.getTrackWithTrackToken("SELECTED_TRACK_TOKEN") { track, error in
    if let error {
        /// Implement updating your ViewController with error
        return
    }
    if let track {
        /// Implement updating your ViewController with new data
    }
}
[[RPEntry instance].api getTrackWithTrackToken:@"SELECTED_TRACK_TOKEN"
                                    completion:^(RPTrackProcessed * _Nullable track, NSError * _Nullable error) {
    if (error) {
        /// Implement updating your ViewController with error
        return;
    }
    if (track) {
        /// Implement updating your ViewController with new data
    }
}];

Change a Transportation type

RPEntry.instance.api.changeTrackOrigin(.originalDriver, forTrackToken: "SELECTED_TRACK_TOKEN") { code, error in
            
}

//Avilable origins:
//.originalDriver
//.bus
//.motorcycle
//.other
//.passenger
//.running
//.taxi
//.train
//.walking
[[RPEntry instance].api changeTrackOrigin:RPTrackOriginCodeOriginalDriver
                            forTrackToken:@"SELECTED_TRACK_TOKEN'"
                               completion:^(RPStatusCodeResponse * _Nullable status, NSError * _Nullable error) {
        
}];

//Avilable origins:
//RPTrackOriginCodeOriginalDriver
//RPTrackOriginCodeBicycle
//RPTrackOriginCodeBus
//RPTrackOriginCodeMotorcycle
//RPTrackOriginCodeOther
//RPTrackOriginCodePassenger
//RPTrackOriginCodeRunning
//RPTrackOriginCodeTaxi
//RPTrackOriginCodeTrain
//RPTrackOriginCodeWalking

Upload unsent trips

RPEntry.instance.uploadUnsentTrips()
[[RPEntry instance] uploadUnsentTrips];

Get unsent trips

RPEntry.instance.getUnsentTripCount { unsentTripsCount in
  print("unsent trips count - \(unsentTripsCount)")        
}
[[RPEntry instance] getUnsentTripCountWithCompletion:^(NSInteger unsentTripsCount) {
   NSLog(@"unsent trips count - %ld", (long)unsentTripsCount);   
}];

Send a custom heartbeat

RPEntry.instance.sendCustomHeartbeat("CustomHeartbeat")
[[RPEntry instance] sendCustomHeartbeat:@"CustomHeartbeat"];

Updated 11 days ago

Did this page help you?