onAccessPermissionChanged

Optional callback prop on <BTProvider>. Fires whenever the OS-level Bluetooth + Location permission grant state changes — on initial mount with the current state, and again whenever the user toggles it in Settings while the app is alive.

Children remain mounted by default while access is pending or unavailable. Set gateOnPermission to true to replace them with permissionFallback (or the default fallback) until permission is granted.

Signature

onAccessPermissionChanged?: (accessPermission: boolean) => void;

accessPermission is the provider's current coarse access result. It becomes true only when every permission requested by the provider is reported as granted. On Android 31 and later that means both Bluetooth scan and connect; on older Android versions it means the requested location permission. The iOS input is the Bluetooth permission result.

When it fires

Trigger	Value
Initial mount, a requested grant is present	true
Initial mount, no requested grant is present	false
User backgrounds app → opens Settings → grants permission → returns	true
User backgrounds app → opens Settings → revokes permission → returns	false
OS revokes Bluetooth at runtime (rare)	false

The callback fires synchronously on app foreground via a listener registered by the provider. You do not need to poll or check permission status yourself.

Usage with permissionFallback

import React, { useCallback, useState } from "react";
import { Button, Linking, Text, View } from "react-native";
import { BleManager } from "react-native-ble-plx";
import { BTProvider, IntegratedDevices } from "@ovok/native";

const bleManager = new BleManager();
const acceptedDevices = [IntegratedDevices.BP2] as const;

function PermissionDeniedCard() {
  return (
    <View style={{ padding: 24, gap: 12 }}>
      <Text style={{ fontSize: 18, fontWeight: "600" }}>
        Bluetooth Permission Required
      </Text>
      <Text>
        We need Bluetooth permission to pair with your medical device. Tap below
        to open Settings and grant access.
      </Text>
      <Button title="Open Settings" onPress={() => Linking.openSettings()} />
    </View>
  );
}

function MyApp() {
  const [hasPermission, setHasPermission] = useState<boolean | null>(null);

  const handleAccessPermissionChanged = useCallback((granted: boolean) => {
    setHasPermission(granted);
    if (!granted) {
      console.warn("Bluetooth permission denied — children will not mount");
    }
  }, []);

  return (
    <BTProvider
      bleManager={bleManager}
      acceptedDevices={acceptedDevices}
      onAccessPermissionChanged={handleAccessPermissionChanged}
      gateOnPermission
      permissionFallback={() => <PermissionDeniedCard />}
    >
      <YourScreens />
    </BTProvider>
  );
}

What permissionFallback actually renders

When gateOnPermission is true and the grant state is false, BTProvider mounts permissionFallback() IN PLACE OF children. This means BT-dependent UI inside children is guaranteed not to render without permissions. Without that opt-in, children stay mounted and the app can manage its own pending/denied UI.

With gating enabled, only permissionFallback is rendered while access is missing. The moment the user grants access (via Settings → return to app), the provider mounts children and resumes scanning.

If gating is enabled and permissionFallback is omitted, BTProvider renders its default localized DefaultPermissionFallback, which opens system settings through its retry action.

Difference from onError permission failures

onError also fires for permission-related BLE errors (e.g. a scan started before grant + permission denied mid-scan). The distinction:

• onAccessPermissionChanged(false) → the OS-level grant flipped. This is the right place to swap UI.
• onError({ error }) with a permission message → an in-flight BLE operation hit a permission wall. Often a transient artifact; the next onAccessPermissionChanged will follow with the actual grant state.

Treat onAccessPermissionChanged as authoritative. Use onError for telemetry, not for state.

Requests and settings

BTProvider requests the platform permissions on mount and again when the app returns active. The fallback is for explaining or reopening Settings after a denial; an app may also use useBluetoothState when it needs an explicit permission request action.

Related

• BTProvider — full provider reference (including permissionFallback)
• on-error — transient permission errors during BLE ops