Migration Guide 3.9

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.9.0

Bluetooth Peripheral Priority Numbers

Version 3.9.0 adds priority numbers to Bluetooth peripheral lists, allowing apps to filter and prioritize peripherals based on their importance for trip matching.

New Feature: - Each Bluetooth peripheral in the recommended list now includes a priority number (1-11) - Priority levels indicate the importance of the peripheral for trip matching: - Priority 1: A2DP and/or HFP and "White list" names (highest priority) - Priority 3: A2DP and HFP - Priority 5: A2DP or HFP - Priority 7: A2DP and/or HFP and "grey list" names (Earphones, Bose, Beats, Speaker, Sound, Sony, JBL, Headset, etc.) - Priority 9: A2DP and/or HFP and "black list" names (watch, airpod, meta glass, Ring) - Priority 11: Non-CAR "blacklisted" profiles like HPP (lowest priority) - Apps can use priority numbers to filter out low-priority peripherals from their UI

Detailed Error Codes in SDK Public API

Version 3.9.0 enhances error handling by providing detailed error codes in SDK exceptions, making it easier to diagnose and handle specific error conditions.

Enhancement: - DriveMotionException now includes an errorDetails field containing detailed error information - Error details include error codes that can be used for programmatic error handling - See API Error Code Detail for complete list of error codes

Trip Sync Status API

Version 3.9.0 introduces a new API to check if trip synchronization is in progress, allowing apps to determine if sync is active before querying coaching data.

New API: - getIsSyncInProgressPublisher() -> AnyPublisher<Bool, Never>? - Returns a publisher that emits a boolean value indicating whether trip sync is currently in progress - Returns true when sync is in progress, false when sync is idle or completed - Apps should check sync status before calling coaching APIs to ensure data is up to date - The publisher emits updates whenever the sync status changes

Insights Habitual Filter

Version 3.9.0 applies a new habitual filter to coaching insights to ensure that standouts represent genuine habitual patterns across different time periods.

Behavior Change: - Insights are now filtered to ensure they represent genuine habitual patterns: - TimeOfDay: Requires at least 8 different days in the specified time period - DayOfWeek: Requires at least 2 different weeks in the specified day of week - TripLength: Requires at least 1/5 of total trips in the specified trip length bucket - RoadType: Requires at least 1/7 of total distance in the specified road type bucket - DayOfMonth: No filtering applied - This means fewer but more accurate insights will be shown - Insights that don't meet the habitual pattern requirements will be filtered out

Impact: - Apps may see fewer insights than before, but they will be more accurate - Insights will better represent genuine driving patterns - No code changes required - this is an automatic filtering improvement

Trip Order Guarantee

Version 3.9.0 fixes an issue where the order of trips returned by getTripsByIdsRequest in cloud mode did not match the order of the input trip ID list.

Fix: - Trips are now guaranteed to be returned in the same order as the input trip ID list - Applies to all modes: default, offline, and cloud - Ensures consistent behavior across all SDK modes

Impact: - Apps can now rely on trip order matching the input list - No code changes required - this is a bug fix that improves consistency

Backward Compatibility

All changes in version 3.9.0 are backward compatible. The new priority numbers, error details, and status API are optional enhancements. Apps can continue to work without using these new features, but are encouraged to adopt them for better user experience and error handling.