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

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

Example Event Usage:

Events are automatically generated and sent. You can monitor them in Logshed for: - API usage analytics - Trip detection debugging - SDK lifecycle monitoring - Exception tracking - Bluetooth peripheral collection analysis

Enhanced Logging for Initialization Failures

Version 3.8.0 adds additional logging for DMSDK initialization failures to aid troubleshooting.

Improvement: - More detailed error logs when SDK initialization fails - Better error messages to identify root causes - Helps diagnose initialization issues faster

No Code Changes Required: - Logging is automatic - Check logs when initialization fails for detailed error information

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:

val request = driveMotionAnalyticsClient
    .postContextualCoachingRequest(startTime, endTime, timeZoneId)
    .withAsset(assetId, assetContext)
    .withScoreVersion(scoreVersion)
    .groupBy(groupFactors)
    .rankBy(rankMetrics)
    .build()

// Response will include distraction co-relation data
// showing how many distractions occurred near safety events
request.execute { response ->
    response.result?.let { result ->
        // Process coaching statistics with distraction co-relation
    }
}

Bluetooth Information Upload Enhancement

Version 3.8.0 uploads high priority Bluetooth information to the cloud for improved trip matching.

Improvement: - High priority Bluetooth devices (with HFP/A2DP capability) are now uploaded to cloud - Uploaded 45 seconds after trip start - Enables better trip matching and learning for RSO (Remote Service Operations)

No Code Changes Required: - Automatic feature - Improves trip matching accuracy - No impact on existing functionality

Trip Match Refinement on CarPlay

Version 3.8.0 improves trip matching for CarPlay scenarios.

Enhancement: - Better trip assignment when using CarPlay - Automatic binding of CarPlay to the same car as Bluetooth when appropriate - Improved trip matching for CarPlay-only trips

No Code Changes Required: - Automatic feature - Improves trip matching accuracy for CarPlay users

Backward Compatibility

All changes in version 3.8.0 are backward compatible. The new event tracking, logging enhancements, and trip matching improvements are automatic and do not require any code changes.