Skip to main content

BackgroundSyncSetting

BackgroundSyncSetting is a themed switch for Bluetooth background scanning. Render it beneath BTProvider, where useBackgroundSync can reach the active Bluetooth runtime:

import { useState } from "react";
import { BackgroundSyncSetting } from "@ovok/native/ui";
import { BTProvider } from "@ovok/native/bt-management";

function MonitoringSettings() {
  const [backgroundEnabled, setBackgroundEnabled] = useState(false);

  return (
    <BTProvider
      bleManager={bleManager}
      acceptedDevices={acceptedDevices}
      backgroundSync={{
        enabled: backgroundEnabled,
        storage: measurementStorage,
        onResult: uploadMeasurement,
      }}
    >
      <BackgroundSyncSetting
        enabled={backgroundEnabled}
        canEnable={platformPolicy.allowsBluetoothBackground}
        onEnabledChange={async (enabled) => {
          setBackgroundEnabled(enabled);
          await saveBackgroundPreference(enabled);
        }}
      />
    </BTProvider>
  );
}

The app owns the preference. Pass its current value to both the setting and BTProvider.backgroundSync.enabled, and persist changes in onEnabledChange. The setting's enabled prop initializes its local switch state; it does not subscribe to later prop changes. Keep the two values in sync from app-owned state.

Props​

BackgroundSyncSetting accepts UseBackgroundSyncOptions plus:

PropTypeDescription
titlestringLabel shown above the current state. Defaults to Background sync.
descriptionReactNodeSupporting copy. Defaults to platform-specific background work text.
statusLabelsPartial<Record<"on" | "off" | "restricted" | "blocked", string>>Replace the visible status labels.
reasonLabelsPartial<Record<string, string>>Replace the message for a returned reason.
testIDstringTest identifier forwarded to the card.
theme, slotsOvokUiPropsUse the shared UI theme and slot overrides.
enabledbooleanInitial switch state; defaults to false.
canEnable() => Promise<boolean>Optional app policy check. Return false to show the restricted state.
onEnabledChange(enabled: boolean) => void | Promise<void>Persist or update app-owned preference state.

The hook returns on, off, restricted, or blocked. A false canEnable result sets restricted and exposes the reason background access is restricted. A thrown policy or change callback sets blocked and exposes the error. The app should make any permission rationale or system settings flow clear in its own UI.

Enabling this control changes the Bluetooth manager's background-scan flag. It does not create durable storage, upload results, schedule Health Connect work, or enable HealthKit observer delivery. Configure the queue through BTProvider.backgroundSync and native capabilities in the background sync guide.