From bd40d80128d2927ad1dfdbc19dfc3774c84a2636 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mikl=C3=B3s=20Fazekas?= Date: Wed, 28 Oct 2026 10:47:25 +0100 Subject: [PATCH] docs(navigation): the plugin always adds the audio background mode --- docs/navigation/install.md | 5 ++--- docs/navigation/troubleshooting.md | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/navigation/install.md b/docs/navigation/install.md index 35bfc0a1..faa59e9f 100644 --- a/docs/navigation/install.md +++ b/docs/navigation/install.md @@ -76,7 +76,7 @@ end ### Info.plist -Add `NSLocationWhenInUseUsageDescription`, and `audio` to `UIBackgroundModes` so voice instructions keep playing in the background. The Navigation SDK's voice controller asserts on the `audio` mode in debug builds when guidance starts. Declare it only if your app speaks guidance; App Review rejects unused background modes. +Add `NSLocationWhenInUseUsageDescription`, and `audio` to `UIBackgroundModes`: the Navigation SDK's voice controller asserts on it in debug builds on any guidance start, even with voice muted. ### Versions @@ -144,7 +144,7 @@ On iOS the `@rnmapbox/navigation` plugin: - sets `$RNMapboxMapsSwiftPackageManager = { link: false }` in the Podfile, see the iOS tab; - adds the Navigation SDK's binary frameworks to `rnmapbox-maps`' framework search paths, which Xcode 26 needs with React Native 0.87+; - sets `NSLocationWhenInUseUsageDescription`, unless `locationWhenInUsePermission` is `false`; -- adds `audio` to `UIBackgroundModes`, so voice instructions keep playing in the background, unless `backgroundAudio` is `false`. Without it the Navigation SDK asserts in debug builds when guidance starts. Turn it off if your app doesn't speak guidance; App Review rejects unused background modes; +- always adds `audio` to `UIBackgroundModes`: without it the Navigation SDK asserts in debug builds on any guidance start, even with voice muted; - with `carPlay: true`, adds the CarPlay scene and the `com.apple.developer.carplay-maps` entitlement, and with `carPlayRoot: true` also hands the `AppDelegate.swift` React Native factory to CarPlay. On Android the `@rnmapbox/maps` plugin already adds the Mapbox Maven repository, and the Navigation SDK's manifest adds the location, foreground service and notification permissions. With `androidAuto: true` the `@rnmapbox/navigation` plugin adds the Android Auto service, its metadata and the `androidx.car.app` navigation and surface permissions. With `RNMapboxNavigationVersion` it sets the Navigation SDK version in `gradle.properties`. @@ -162,7 +162,6 @@ On Android the `@rnmapbox/maps` plugin already adds the Mapbox Maven repository, | ----------------------------- | ------------------------------------------------------------------------------------------------------------ | | `RNMapboxNavigationVersion` | Navigation SDK version on both platforms. Set the maps plugin's `RNMapboxMapsVersion` to the matching 11.N. | | `locationWhenInUsePermission` | iOS `NSLocationWhenInUseUsageDescription`, or `false` to leave it unset. Defaults to a generic navigation string, unless the app already sets one. | -| `backgroundAudio` | `false` leaves iOS `UIBackgroundModes` unchanged. Defaults to `true`, which adds `audio`. | | `carPlay` | iOS CarPlay scene and entitlement. CarPlay is a prototype. | | `carPlayRoot` | With `carPlay`, lets CarPlay start React Native for `Navigation.registerCarPlayRoot` when it launches the app without its phone UI. Needs a Swift `AppDelegate`. | | `androidAuto` | Android Auto service and permissions. Experimental, not tested on a head unit yet. | diff --git a/docs/navigation/troubleshooting.md b/docs/navigation/troubleshooting.md index ca39208c..616bac3f 100644 --- a/docs/navigation/troubleshooting.md +++ b/docs/navigation/troubleshooting.md @@ -70,7 +70,7 @@ Both libraries pick the `-ndk27` artifacts with `targetSdkVersion` 35 or higher. ## iOS: assertion about UIBackgroundModes audio -Guidance crashes in a debug build, as soon as it starts, with an assertion from the Navigation SDK's voice controller about the `audio` background mode. The Expo config plugin adds it unless `backgroundAudio` is `false`. In a bare app, add it to `Info.plist`: +Guidance crashes in a debug build, as soon as it starts or when the voice is muted, with an assertion from the Navigation SDK's voice controller about the `audio` background mode. The Expo config plugin always adds it. In a bare app, add it to `Info.plist`: ```xml UIBackgroundModes @@ -79,4 +79,4 @@ Guidance crashes in a debug build, as soon as it starts, with an assertion from ``` -With Expo, remove `"backgroundAudio": false` from the `@rnmapbox/navigation` plugin options, or add `"UIBackgroundModes": ["audio"]` to `ios.infoPlist` in `app.json`, and run `npx expo prebuild` again. +With Expo, check that the `@rnmapbox/navigation` plugin is in `app.json` and run `npx expo prebuild` again.