Migration Guide: v0.10.x to v0.12.0

Note: v0.11.0 was an internal release (geofencing) and was never published to npm. v0.12.0 includes all v0.11.0 features plus 3 breaking changes.

Quick Migration Checklist

• Update @gabriel-sisjr/react-native-background-location to ^0.12.0
• Replace permissionStatus.hasPermission with permissionStatus.hasAllPermissions
• Replace permissionStatus.status with permissionStatus.location.status
• Replace permissionStatus.canRequestAgain with permissionStatus.location.canRequestAgain
• Move all notification* fields into notificationOptions object (strip notification prefix)
• Update TypeScript imports for new types (LocationPermissionState, NotificationPermissionState)
• (iOS) Be aware: users will see an additional notification permission dialog
• Run pod install in your iOS directory after upgrading

---

Breaking Change 1: Granular Permission State

The flat PermissionState interface is now nested, separating location and notification permission states.

Before (v0.10.x)

const { permissionStatus } = useLocationPermissions();

if (permissionStatus.hasPermission) {
  console.log(permissionStatus.status);
  console.log(permissionStatus.canRequestAgain);
}

After (v0.12.0)

const { permissionStatus } = useLocationPermissions();

if (permissionStatus.hasAllPermissions) {
  console.log(permissionStatus.location.status);
  console.log(permissionStatus.location.canRequestAgain);
}

// New: notification permission status
console.log(permissionStatus.notification.status); // 'granted' | 'denied' | 'undetermined'
console.log(permissionStatus.notification.hasPermission); // boolean

Property Mapping

v0.10.x	v0.12.0
permissionStatus.hasPermission	permissionStatus.hasAllPermissions
permissionStatus.status	permissionStatus.location.status
permissionStatus.canRequestAgain	permissionStatus.location.canRequestAgain

Behavioral Changes

• Android: requestPermissions() now returns true even when POST_NOTIFICATIONS is denied. Previously returned false if any permission was denied.
• iOS: An additional notification permission dialog appears after the location permission dialogs.
• hasAllPermissions is true only when BOTH location AND notification permissions are granted.
• For location-only checks, use permissionStatus.location.hasPermission.

New Types

import type {
  LocationPermissionState,
  NotificationPermissionState,
  PermissionState,
} from '@gabriel-sisjr/react-native-background-location';

import { NotificationPermissionStatus } from '@gabriel-sisjr/react-native-background-location';
// NotificationPermissionStatus.GRANTED | .DENIED | .UNDETERMINED

---

Breaking Change 2: Unified NotificationOptions

The 11 flat notification* fields in TrackingOptions have been consolidated into a single notificationOptions object. This same NotificationOptions interface is now shared between tracking and geofencing notifications.

Before (v0.10.x)

startTracking({
  updateInterval: 5000,
  notificationTitle: 'Location Tracking',
  notificationText: 'Tracking in background',
  notificationChannelName: 'Background Location',
  notificationChannelId: 'location_channel',
  notificationPriority: NotificationPriority.LOW,
  notificationSmallIcon: 'ic_notification',
  notificationLargeIcon: 'ic_notification_large',
  notificationColor: '#4CAF50',
  notificationShowTimestamp: true,
  notificationSubtext: 'Example',
  notificationActions: [{ id: 'stop', label: 'Stop' }],
});

After (v0.12.0)

startTracking({
  updateInterval: 5000,
  notificationOptions: {
    title: 'Location Tracking',
    text: 'Tracking in background',
    channelName: 'Background Location',
    channelId: 'location_channel',
    priority: NotificationPriority.LOW,
    smallIcon: 'ic_notification',
    largeIcon: 'ic_notification_large',
    color: '#4CAF50',
    showTimestamp: true,
    subtext: 'Example',
    actions: [{ id: 'stop', label: 'Stop' }],
  },
});

Field Mapping

v0.10.x	v0.12.0
notificationTitle	notificationOptions.title
notificationText	notificationOptions.text
notificationChannelName	notificationOptions.channelName
notificationChannelId	notificationOptions.channelId
notificationPriority	notificationOptions.priority
notificationSmallIcon	notificationOptions.smallIcon
notificationLargeIcon	notificationOptions.largeIcon
notificationColor	notificationOptions.color
notificationShowTimestamp	notificationOptions.showTimestamp
notificationSubtext	notificationOptions.subtext
notificationActions	notificationOptions.actions

New Capability

The NotificationOptions interface adds an enabled field:

startTracking({
  updateInterval: 5000,
  notificationOptions: {
    enabled: false, // Explicitly suppress the notification
  },
});

---

Breaking Change 3: iOS Notification Permission

useLocationPermissions().requestPermissions() on iOS now includes a third step that requests notification permission via UNUserNotificationCenter.

Permission Flow (iOS)

1. Request "When In Use" location permission (existing)
2. Request "Always" location permission if foregroundOnly: false (existing)
3. Request notification permission (new in v0.12.0)

Impact

• Users will see an additional permission dialog on iOS
• This is required for geofencing notifications to display on iOS
• Non-blocking: requestPermissions() returns true when location is granted, even if notification permission is denied
• Notification denial only affects visual notifications -- geofencing JS callbacks work regardless

Checking Notification Permission Status

const { permissionStatus } = useLocationPermissions();

if (!permissionStatus.notification.hasPermission) {
  // Guide user to Settings to enable notifications
  console.log('Notification status:', permissionStatus.notification.status);
}

No Info.plist Changes Required

The notification permission request uses the system dialog. No additional Info.plist keys are needed beyond the existing location permission keys.

---

Search-and-Replace Patterns

Use these patterns to find code that needs updating in your app:

# Find old PermissionState usage
grep -rn "\.hasPermission" --include="*.ts" --include="*.tsx"
grep -rn "permissionStatus\.status" --include="*.ts" --include="*.tsx"
grep -rn "permissionStatus\.canRequestAgain" --include="*.ts" --include="*.tsx"

# Find old flat notification fields
grep -rn "notificationTitle\|notificationText\|notificationChannelName\|notificationChannelId\|notificationPriority\|notificationSmallIcon\|notificationLargeIcon\|notificationColor\|notificationShowTimestamp\|notificationSubtext\|notificationActions" --include="*.ts" --include="*.tsx"

---

New Features in v0.12.0

Since v0.11.0 was never published, v0.12.0 also includes all geofencing features:

• Cross-platform geofencing with useGeofencing and useGeofenceEvents hooks
• Per-geofence and per-transition notification overrides
• Template variables for dynamic notification content ({{identifier}}, {{transitionType}}, etc.)
• iOS geofence notifications via UNUserNotificationCenter
• Crash recovery for geofences on both platforms
• Hook rendering optimizations (internalized ref stabilization -- consumers no longer need useMemo/useCallback for inline objects)

See the Geofencing Guide for full documentation.

---

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 error
• Tag with migration and v0.12.0

For projects upgrading past v0.12.0, continue with the v0.14.0 migration guide.