Skip to content

docs(navigation): the plugin always adds the audio background mode #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mfazekas merged 1 commit into from
Oct 29, 2026
Merged

docs(navigation): the plugin always adds the audio background mode #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/navigation/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`.
Expand All @@ -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. |
Expand Down
4 changes: 2 additions & 2 deletions docs/navigation/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<key>UIBackgroundModes</key>
Expand All @@ -79,4 +79,4 @@ Guidance crashes in a debug build, as soon as it starts, with an assertion from
</array>
```

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