Skip to content

Migration Guide 3.8

Migration SDK from Old Versions

This section provides a detailed description of API changes introduced or removed in recent SDK upgrades.
We strongly recommend reading this documentation when upgrading the SDK version to understand the differences and update your API calls accordingly.

Migration to Version 3.8.0

Location Permission Validation Enhancement

Version 3.8.0 improves location permission validation during SDK initialization. The SDK now properly checks all location permission states including "denied" and "restricted" cases, not just "not determined".

Behavior Change: - Previously, the SDK only checked the "not determined" case for location permissions - Now, the SDK checks all three cases: "not determined", "denied", and "restricted" - All three cases are treated as "NO PERMISSION" and will prevent successful initialization

Impact: - Apps that previously initialized successfully without proper location permissions may now fail initialization - Ensure location permissions are properly requested and granted before initializing the SDK

Expanded Telematics Events

Version 3.8.0 introduces comprehensive event tracking for better observability and troubleshooting. New event types are automatically sent to Logshed.

New Event Types:

  1. API_INVOCATION - Tracks all public API calls
  2. Records API name, parameters, success/failure status

  3. Helps identify API usage patterns and issues

  4. TRIP_DETECTION_STATUS - Tracks trip detection lifecycle

  5. Status values: START_PENDING, START_DETECTED, START_FAILED, END_PENDING, END_DETECTED, END_FAILED

  6. Provides visibility into trip detection process

  7. DM_SDK_LIFE_CYCLE_STATUS - Tracks SDK lifecycle events

  8. Status values: INITIALIZED, OPTED_IN, STARTED_TRIP_DETECTION, STOPPED_TRIP_DETECTION, OPTED_OUT, SHUTDOWN

  9. Monitors SDK state transitions

  10. SDK_EXCEPTION - Tracks SDK exceptions

  11. Records exceptions like geofence addition failures

  12. Aids in troubleshooting

  13. PERIPHERAL_COLLECTION - Tracks recommended peripherals collection

  14. Records when peripheral list is collected
  15. Helps with Bluetooth troubleshooting

No Code Changes Required: - Events are automatically sent to Logshed - No additional configuration needed - Events are sent asynchronously and do not impact SDK performance

Network Reachability Fix:

Version 3.8.0 fixes an issue where offline events were not uploaded when the SDK was first initialized. The SDK now properly checks network reachability status during initialization.

Behavior Change: - Previously, offline events depended solely on NetworkReachability callbacks, which might not fire on first initialization - Now, the SDK actively checks network status during initialization - Offline events will be uploaded immediately if network is available

Impact: - Trip start and end events will be uploaded more reliably - No code changes required - this is an internal fix

Distraction Co-relation with Safety Events

Version 3.8.0 adds support for distraction co-relation with safety events in contextual coaching APIs.

New Feature: - Contextual coaching responses now include distraction events that occurred within a specified time window (e.g., 10 seconds) of safety events (HA/HB) - Supports filtering by: Road Category, Trip Length, Day of Week, Day of Month, and Time of Day

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
let request = try driveMotionAnalyticsClient
    .postContextualCoachingRequest(
        startTime: startTime,
        endTime: endTime,
        timeZoneId: timeZoneId
    )
    .asset(assetId: assetId, assetContext: assetContext)
    .scoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

// Response will include distraction co-relation data
// showing how many distractions occurred near safety events

1
2
3
4
5
TNPostContextualCoachingRequestBuilder *builder = [client postContextualCoachingRequestWithStartTime:startTime endTime:endTime timeZoneId:timeZoneId];
[builder assetWithAssetId:assetId assetContext:assetContext];
TNPostContextualCoachingRequest *request = [builder buildAndReturnError:&error];

// Response will include distraction co-relation data

Backward Compatibility

All changes in version 3.8.0 are backward compatible. The new event tracking is automatic and does not require any code changes. Location permission validation is more strict, so ensure permissions are properly granted before initialization.