Branch deep links

Create a Branch deep link from your server.

Create a deep link

Generate a Branch deep link from your backend — a share link, invite URL, or anything you return from an API route. Server-only: import from @bdk/native/server/branch and never include it in a browser bundle.

Only deepLinkUrl is required. If it has no protocol, https:// is added; any urlParams are appended as query parameters.

On success, dynamicLink holds the link and errorMessage is null. If Branch returns no URL, the call resolves with dynamicLink: null and an errorMessage — check it. Transport or non-2xx errors throw a BdkError with code BDK_PROVIDER_ERROR, so wrap the call in try/catch.

import { createBranchLink } from "@bdk/native/server/branch";

const result = await createBranchLink({
  deepLinkUrl: "myapp://product/42"
});

if (result.dynamicLink) {
  console.log("Share this link:", result.dynamicLink);
} else {
  console.error(result.errorMessage);
}

Input and result types

Import these types for autocomplete on the options you pass and the result you get back. deepLinkUrl is the only required input.

CreateBranchLinkInput:

deepLinkUrl: string — the destination the link opens (required).
branchKey?: string — Branch key; falls back to env if omitted.
branchLinkDomain?: string — your Branch link domain; falls back to env if omitted.
desktopUrl?, iosUrl?, androidUrl?: string — platform fallback URLs. desktopUrl defaults to deepLinkUrl when not set.
alias?: string — a custom path for the generated link.
analytics?: BranchAnalytics — { channel?, feature?, campaign?, stage?, tags? }, where tags is a string[].
social?: BranchSocial — { title?, description?, imageUrl? }, mapped to Open Graph fields.
urlParams?: Record<string, string | number | boolean | undefined | null> — query parameters appended to deepLinkUrl.
baseUrl?: string — override the Branch API base (defaults to https://api2.branch.io/v1).
fetch?: FetchLike — provide a custom fetch implementation (defaults to the global fetch).

BranchLinkResult:

dynamicLink: string | null — the generated Branch URL, or null on failure.
errorMessage: string | null — a message when no URL was returned, otherwise null.
raw: unknown — the raw Branch response payload, for debugging or reading extra fields.

import type {
  CreateBranchLinkInput,
  BranchLinkResult,
  BranchAnalytics,
  BranchSocial
} from "@bdk/native/server/branch";

const input: CreateBranchLinkInput = {
  deepLinkUrl: "myapp://invite",
  urlParams: { ref: "user_123", utm_source: "share" }
};

Set your Branch credentials

Branch needs a key and a link domain. Set them once as environment variables, or pass them per call to target a different Branch app. A value on input always wins; otherwise these env vars are read in order:

branchKey — BDK_BRANCH_KEY, then BRANCH_KEY, then BRANCH_LIVE_KEY.
branchLinkDomain — BDK_BRANCH_LINK_DOMAIN, then BRANCH_LINK_DOMAIN.

If neither input nor env supplies a value, the call throws a BdkError with code BDK_VALIDATION_ERROR naming the missing field (e.g. branchKey is required.).

Only call createBranchLink from server-side code. Importing @bdk/native/server/branch into a browser bundle would leak your Branch key.

// Set in your server environment:
// BDK_BRANCH_KEY=key_live_xxx
// BDK_BRANCH_LINK_DOMAIN=example.app.link

import { createBranchLink } from "@bdk/native/server/branch";

const result = await createBranchLink({
  deepLinkUrl: "myapp://home"
});