Gate
A Gate replaces the browse content on CarPlay, Android Auto and Android Automotive with a short message that you hand the library. It can also turn away voice searches.
Use it when part of your catalog is premium, login-only or region-locked, and you want to block it in the car without building a separate UI there.
One rule worth keeping in mind: a Gate blocks finding, never hearing. Whatever is already playing keeps going, a voice "resume" is never gated, and the queue is left alone.
A voice request to play something new is a search. The Gate refuses it unless your resolver lets search through (see Gating some requests, not others).
Two things it never touches:
- Your own in-app browse UI. The Gate only covers content the library serves; the screens you draw in your app are yours to gate with your own paywall.
- Playback. It lives on the find/resolve path, so audio is never interrupted.
It follows that the Gate is iOS and Android only. On web setGate and clearGate are no-ops and onGate never fires: there's no car surface to cover.
In-app browse UI is not the Gate's job on any platform. Calling the Gate functions from shared code is safe, and on web does nothing.
Voice search isn't only a "car" thing
A Siri or Google Assistant request ("Hey Siri, play jazz on App") can come from the phone or lock screen, not just the car. It still goes through the Gate.
That's why the common setup below gates browsing but lets search through: voice-play keeps working everywhere, while the car's browse tabs stay walled off.
Setting a gate
import { setGate, clearGate } from 'react-native-audio-browser'
setGate({ title: 'Premium', message: 'Subscribe to browse in the car.' })
// …later, when the user is entitled:
clearGate()setGate raises the gate (or updates it in place); clearGate drops it and the real content returns (on CarPlay, on the first tab; see the warning below).
Set it before the car connects and it'll be there the moment it does. A gate is global and singular — calling setGate again replaces the current one.
A Gate is independent of setupPlayer and configureBrowser — call setGate any time after import. The usual lifecycle is: set it once at startup, then clearGate (or re-setGate) whenever the user's entitlement changes (purchase, login, logout).
A gate is just a title and an optional message. How it renders depends on the surface:
- CarPlay: the tab bar stays, and each gated tab, or gated page you navigate to, shows a centered message page in place of its list (newlines in the message collapse to spaces). The Now Playing screen keeps its transport controls but hides the custom buttons from
ios.carPlayNowPlayingButtons. - Android Auto and Android Automotive: the tabs stay visible, and each gated tab's content becomes one non-playable list tile. The tile shows the title as its main line and the message as the subtitle (newlines collapse to spaces). Keep both short: it's a tile, not a full page.
There's no action button: Android Auto can't show one, and a car surface can't run a purchase flow anyway (see Reacting to gate hits for the deferred-upsell pattern).
Changing the gate resets CarPlay navigation
While CarPlay is connected, every setGate, and every clearGate that drops a gate that was up, pops any drilled-in pages back to the tab root. This includes a first setGate on logout and a clearGate after a purchase. A clearGate with no gate up does nothing.
A clearGate also rebuilds the tab bar, so CarPlay returns to the first tab; setGate keeps the selected tab. A gate set before the car connects does not affect navigation.
Gating some requests, not others
Pass a resolver as the second argument. The library calls it for every browse navigation and every search, and your return value decides what happens:
- return
false— let the request through - return
true— gate it with the default message (the firstsetGateargument) - return a gate object
{ title, message? }— gate it with a different message, just for this one
The request tells you what's being asked: request.kind is 'browse' or 'search'. A browse request carries a request.path; a search request carries request.params (the parsed query — see the Search guide).
The common case — gate browsing, but leave search open — so users can still play by voice:
setGate(
{ title: 'Premium', message: 'Subscribe to browse in the car.' },
(request) => request.kind === 'browse'
)The resolver is synchronous
A resolver returns Gate | boolean — never a Promise — so you can't await an auth check inside it. Rather than check entitlement in the resolver, drive the gate from a single place: gate while locked, clearGate once entitled.
const gateBrowsing = () =>
setGate(
{ title: 'Premium', message: 'Subscribe to browse in the car.' },
(request) => request.kind === 'browse' // gate browse, allow search
)
if (!isEntitled()) gateBrowsing() // your code, at startup
// entitlement changed (purchase / login / logout):
function onEntitlementChange(entitled: boolean) {
entitled ? clearGate() : gateBrowsing() // refresh the car surfaces
}Because the resolver sees the request, you can also gate by path — block one premium branch while the rest stays open — or show a different message per request:
setGate({ title: 'Premium', message: 'Subscribe to unlock.' }, (request) => {
if (request.kind === 'search') return false // search allowed
if (request.path.startsWith('/premium')) return true // gate this branch
return false // everything else
})A search request carries request.params — the parsed query (query, genre, artist, … — see Search) — so you can gate only premium queries:
setGate({ title: 'Premium', message: 'Subscribe to unlock.' }, (request) => {
if (request.kind === 'search') {
return request.params.genre === 'premium' // gate premium genres
}
return request.path.startsWith('/premium')
})You can also pass only a resolver, with no default message. Return a gate object for full control, or true to fall back to the generic built-in chrome.
That fallback is a generic built-in title with no body, so on CarPlay its message area is blank. Pass a default gate or return a gate object if you want body copy.
setGate((request) => request.kind === 'browse')If the resolver throws, the gate fails closed — the library gates the request rather than leak content. A deliberate return false is the only thing that lets a request through.
Reacting to gate hits
You can't complete a purchase on CarPlay or Android Auto — so the pattern is to record that a user bumped into the gate and surface the upsell next time your phone app opens. Subscribe to onGate:
import { onGate } from 'react-native-audio-browser'
// addListener returns an unsubscribe function — keep it and call it to
// clean up.
const unsubscribe = onGate.addListener((event) => {
// event.reason ('browse' | 'search') is the same axis as the resolver's
// request.kind. The event carries only the reason, not the path/params.
recordGateHit() // your own persisted flag
})In a component, wire it through useEffect so it unsubscribes on unmount:
useEffect(() => onGate.addListener((event) => recordGateHit()), [])onGate fires once per gated serve, whether the gate is static or resolver-driven. There's no de-duplication, so poking around a gated car UI fires several events — debounce on your side (once per session, per day, whatever fits) if you don't want them all.
Then, on your next app launch, read the flag and show the upsell:
if (consumeGateHit()) showPremiumUpsell() // your code: read + clear flag