Device & lifecycle

Read device info and control the native app shell — loading splash, navigation, the launch page, and cache.

Read device info

Get device facts like playerId, deviceOS, versionName, or a permission status.

bdk.getDeviceInfo() returns the latest BdkDeviceInfo, or null if it hasn't arrived yet (for example, in a plain browser or before the first deviceInfo event).

BdkDeviceInfo fields (each string or null unless noted):

Property	Type	Description
`playerId`	`string`	OneSignal player id for push.
`pushToken`	`string`	Device push token.
`deviceModel`	`string`	Device model name.
`deviceOS`	`string`	Operating system.
`deviceOSVersion`	`string`	OS version.
`deviceLanguage`	`string`	Device language.
`deviceWidth`	`string \| number`	Screen width.
`deviceHeight`	`string \| number`	Screen height.
`versionName`	`string`	Host app version name.
`versionCode`	`string \| number`	Host app version code.
`biometricsAvailable`	`boolean`	Whether biometric login is available.
`smartLoginAvailable`	`boolean`	Whether smart login is available.
`cameraPermissionStatus`	`string`	Camera permission state.
`contactsPermissionStatus`	`string`	Contacts permission state.
`audiorecordPermissionStatus`	`string`	Audio-record permission state.
`externalstoragePermissionStatus`	`string`	External-storage permission state.
`locationPermissionStatus`	`string`	Location permission state.
`idfa`	`string`	iOS advertising id. iOS only.

Getting null at startup? Wait for the value with await bdk.ready(timeoutMs), or subscribe to the deviceInfo event.

import { createBdkNative } from "@bdk/native/browser";

const bdk = createBdkNative();

const info = bdk.getDeviceInfo();
if (info) {
  console.log(info.playerId, info.deviceOS, info.versionName);
}

Detect the native app

Check whether your page is running inside the native app. Branch on it to enable native-only UI or fall back to web behavior.

bdk.isNative() returns true once device info is available, false otherwise.

if (bdk.isNative()) {
  await bdk.device.vibrate();
} else {
  // web fallback
}

Refresh device info

Request a fresh BdkDeviceInfo, typically after a state change like a permission prompt. You don't need this at startup, since createBdkNative() requests device info automatically unless you pass autoRequestDeviceInfo: false.

bdk.app.requestDeviceInfo().

The fresh value arrives on the deviceInfo event (and updates getDeviceInfo()), not in the returned promise. Subscribe before you call.

bdk.on("deviceInfo", (info) => {
  console.log("fresh info", info.locationPermissionStatus);
});

await bdk.app.requestDeviceInfo();

Hide the loading splash

Dismiss the loading splash once your page is ready. Use this in "manual" mode to control exactly when the UI appears; with the default removeLoading: "automatic" you don't need to call it.

bdk.app.removeLoading().

const bdk = createBdkNative({ removeLoading: "manual" });

// ...once your UI is mounted:
await bdk.app.removeLoading();

Restyle the loading splash

Change the appearance of the loading splash.

bdk.app.updateLoading(options). Recognized LoadingScreenOptions keys: splash_layer_url, splash_layer_width, splash_layer_top, splash_layer_left, and splash_section_background.

await bdk.app.updateLoading({
  splash_layer_url: "https://cdn.example.com/splash.png",
  splash_layer_width: "60%",
  splash_layer_top: "40%",
  splash_layer_left: "20%",
  splash_section_background: "#0B0B0B"
});

Go back

Navigate back, the equivalent of the native back action.

bdk.app.goBack().

await bdk.app.goBack();

Change the launch page

Set which URL the app opens on next launch, then clear it when done.

bdk.app.setLaunchPage(options) sets the alternate launch URL. bdk.app.resetLaunchPage() removes the override and restores the default.

await bdk.app.setLaunchPage({ url: "https://app.example.com/home" });

Vibrate the device

Trigger device haptics.

bdk.device.vibrate(options?).

await bdk.device.vibrate();

Read the device contacts

Fetch the device address book. Ask for the contacts permission first.

bdk.device.getContacts().

The device address book arrives on the contacts event — an array of contacts, each with a name, phone number(s), and email(s) — not in the returned promise. Subscribe before you call.

bdk.on("contacts", (addressBook) => {
  console.log("contacts payload", addressBook);
});

await bdk.permissions.ask("contacts");
await bdk.device.getContacts();

Save and read cache values

Persist small values in native storage and read them back later — handy for flags like onboarding state.

bdk.device.saveToCache(options) and bdk.device.getFromCache(options).

The cached value arrives on the deviceVariable event as a DeviceVariableResult with the variable's name and its stored data value, not in the returned promise. Subscribe before you read.

await bdk.device.saveToCache({ key: "onboarded", value: "true" });

Lifecycle events reference

Subscribe with bdk.on(event, listener), which returns an unsubscribe function. The events:

deviceInfo → BdkDeviceInfo. The shell reported device info; also feeds getDeviceInfo() and ready().
contacts. The device address book from device.getContacts() — an array of contacts, each with a name, phone number(s), and email(s).
deviceVariable → DeviceVariableResult with the variable's name and its stored data value. A cached value from device.getFromCache(...).
backButtonPressed → undefined. The hardware back button was pressed.

If a listener throws, the error surfaces once as a BdkError with code BDK_LISTENER_ERROR, delivered to your onError config callback and the error event.

const offDeviceInfo = bdk.on("deviceInfo", (info) => console.log(info.deviceModel));
const offContacts = bdk.on("contacts", (book) => console.log(book));
const offVariable = bdk.on("deviceVariable", ({ name, data }) => console.log(name, data));
const offBack = bdk.on("backButtonPressed", () => console.log("back pressed"));

// call the returned functions to stop listening
offDeviceInfo();
offContacts();
offVariable();
offBack();