Set up the client

Create the one client object you use for everything in the SDK.

Create the client

Create the client once at app startup and reuse the same instance everywhere. Import from @bdk/native/browser or the package root — both work.

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

export const bdk = createBdkNative();

Configure the client

Every option is optional with a safe default, so most apps pass nothing. Set removeLoading: "manual" to dismiss the native splash screen yourself, and pass onError to centralize error reporting (it receives a BdkError).

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

export const bdk = createBdkNative({
  removeLoading: "automatic",   // "automatic" | "manual"
  pageFit: "normal",            // "normal" | "cover"
  commandGapMs: 400,            // delay between dispatched commands
  queueRetryMs: 400,            // retry interval while waiting for the app
  maxPendingQueueMs: 15000,     // drop queued commands after this long
  installGlobals: true,         // install window callbacks the shell calls
  autoRequestDeviceInfo: true,  // fetch device info on init
  onError: (error) => {
    console.error(error.code, error.message);
  }
});

Wait for the app to be ready

Wait for device info at startup before using native features. Pass a timeout to wait that many milliseconds; in a plain browser it resolves to null when the timeout elapses.

const info = await bdk.ready(3000);

if (info) {
  console.log("Running natively on", info.deviceOS, "release", info.bdkRelease);
} else {
  console.log("No native shell — running as a normal web page");
}

Detect native vs. browser

Branch between native-only features and web fallbacks. bdk.isNative() returns true once device info has arrived; bdk.getDeviceInfo() returns the cached BdkDeviceInfo or null. Prefer await bdk.ready(...) first.

if (bdk.isNative()) {
  const info = bdk.getDeviceInfo();
  console.log(info?.playerId, info?.pushToken, info?.versionName);
} else {
  // Render a web-only experience
}

Clean up in tests

Tear down the client between instances, such as in tests or when hot-reloading a single-page app. You rarely need this in production.

bdk.dispose();