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"
  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; inside the app it resolves as soon as device info arrives, and in a plain browser it resolves to null when the timeout elapses. It never rejects, and it doesn't block rendering — only the code after the await.

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. For an instant answer, bdk.environment() reports "native" synchronously on current app builds — treat "unknown" as "wait" and use ready().

isNative() reads false until device info arrives — at page load that's the wrong answer inside the app. Always await bdk.ready(...) before branching.

await bdk.ready(3000);

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();