Deep links

Listen for custom URI-scheme links, read a pending launch link, and build links with your registered schemes.

Listen for deep links

Subscribe with onReceived to handle custom URI-scheme links — it fires for warm deliveries and replays one unconsumed cold-start link, deduped by id. Don't also call get() for the same launch. Branch dynamic links are a separate server feature — see Branch deep links.

The payload is a BdkDeepLinkRecord. Path-form links (form: "path") are for you to route. URL-form links are already applied by native — don't navigate again.

This feature can be switched off in a given app build — check await bdk.capabilities.has("deeplink.scheme") before showing the UI. See Detect features. When it's off, get() resolves ok: false with code: "common/feature_disabled".

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

const bdk = createBdkNative();

const off = bdk.deeplink.onReceived((link) => {
  if (link.form === "path") {
    routeTo("/" + link.path, link.query);
    return;
  }

  // URL-form: native already opened targetUrl. Don't navigate again.
  console.log(link.targetUrl, link.coldStart);
});

// later
off();

Read a pending link

Call get() to consume the stored link — use this when you are not using onReceived. received is false when there is none. A received record includes coldStart (whether this link launched the app) and consumed (whether a previous get() already took it).

const result = await bdk.deeplink.get();

if (!result.ok) {
  console.warn(result.code, result.message); // e.g. common/feature_disabled
} else if (!result.received) {
  console.log("No pending link");
} else {
  console.log(result.form, result.coldStart, result.consumed);
}

List your schemes

schemes() returns the app's registered URI schemes in preference order. It returns [] when the capability is absent.

const schemes = await bdk.deeplink.schemes();
const preferred = schemes[0]; // undefined when this build has no scheme

Build a link

buildLink encodes a URL-form or path-form link with the first registered scheme. URL-form is scheme://open?url=…. Path-form is scheme://path?query. It returns null when the build has no scheme.

const openPage = await bdk.deeplink.buildLink({
  url: "https://app.example.com/orders/123"
});
// com.example.app://open?url=https%3A%2F%2Fapp.example.com%2Forders%2F123