Migration Guide: v0.16.x to v0.17.0

API-compatible release. No types, signatures, or imports changed. Most apps require no action. Read on only if you build navigation apps or you previously relied on the iOS default activityType being .automotiveNavigation.

What Changed

• The iOS CLLocationManager.activityType default is now LocationActivityType.OTHER (CLActivityType.other). Previously the library hardcoded .automotiveNavigation for all callers.
• New LocationActivityType enum exposes five values: OTHER, AUTOMOTIVE_NAVIGATION, FITNESS, OTHER_NAVIGATION, AIRBORNE. Set via the new optional TrackingOptions.activityType field.
• iOS auto-resumes location updates inside the didPauseLocationUpdates delegate when tracking is active and foregroundOnly: false. The LOCATION_UPDATES_PAUSED warning event is still emitted for observability.

The change is iOS-only. Android behavior is unchanged.

Migration Steps

Most apps: no action required

If you do not pass activityType, you will get the new .other default. For stationary, mixed-motion, fleet-style, or general background-location use cases this is the correct value and you should not change anything.

Navigation apps: opt back into .automotiveNavigation

If your app explicitly tracks vehicle navigation and you want iOS to keep the previous activity-type hint (better dead reckoning during highway driving, more aggressive pause behavior when the device is stationary), set activityType explicitly on startTracking:

import {
  startTracking,
  LocationAccuracy,
  LocationActivityType,
} from '@gabriel-sisjr/react-native-background-location';

await startTracking({
  accuracy: LocationAccuracy.HIGH_ACCURACY,
  activityType: LocationActivityType.AUTOMOTIVE_NAVIGATION,
});

Why This Changed

The previous hardcoded .automotiveNavigation activity type caused iOS to pause location updates approximately 2–3 minutes after the device became stationary, including in non-driving use cases. This produced unexpected gaps in tracking data for fleet, courier, and personal-tracking apps where the device is regularly stationary but tracking should continue. The new default of .other is stationary-friendly and gives apps that need driving behavior an explicit opt-in via LocationActivityType.AUTOMOTIVE_NAVIGATION.

Reference

• LocationActivityType enum - all five values + native mappings
• TrackingOptions.activityType - field signature and default
• iOS Background Behavior: activityType - detailed iOS behavior and auto-resume logic

Need Help?

If you hit a migration issue not covered here:

• File an issue at github.com/gabriel-sisjr/react-native-background-location/issues
• Include the before/after of the failing code and the exact behavior observed
• Tag with migration and v0.17.0

For projects upgrading from earlier versions, follow the v0.14.0 migration guide first.