nativedocs

Receive shared content

Handle text, links, and files other apps share into yours.

Listen for incoming shares

Subscribe at startup so you don't miss a share that arrived before the page loaded. onReceived registers a callback and returns an unsubscribe function. It listens for new shares and replays any that are already pending; a share can settle later with the same shareId and a new status, and the listener fires again.

This feature can be switched off in a given app build. Check await bdk.capabilities.has("share.inbound") before showing the UI — see Detect features.

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

const bdk = createBdkNative();

const off = bdk.share.onReceived((share) => {
  console.log(share.shareId, share.status);
  // Same shareId fires again when status changes (pending → complete / partial / failed).
});

off(); // when the page unmounts

Read pending shares

Pull pending shares yourself when you are not using onReceived. A successful read acknowledges the shares it returns — newest first.

Use onReceived or getPending, not both. onReceived already replays pending shares once.

This feature can be switched off in a given app build. Check await bdk.capabilities.has("share.inbound") before showing the UI — see Detect features. When it's off — or in a plain browser — the call resolves ok: false with code: "common/feature_disabled". Branch on !result.ok.

const result = await bdk.share.getPending();

if (!result.ok) {
  console.log(result.code ?? "Share unavailable");
  return;
}

for (const share of result.shares) {
  console.log(share.shareId, share.status);
}

Track upload progress

Watch each file item as it uploads. The share.uploadProgress event reports bytesSent, totalBytes, and progress for one item at a time — subscribe at startup so you don't miss a share that is already uploading.

PropertyTypeDescription
shareIdstringThe share this item belongs to.
itemIndexnumberIndex of the item in share.items.
bytesSentnumberBytes uploaded so far.
totalBytesnumberTotal bytes for this item.
progressnumberUpload progress for this item.
bdk.on("share.uploadProgress", ({ shareId, itemIndex, bytesSent, totalBytes, progress }) => {
  console.log(shareId, itemIndex, bytesSent, totalBytes, progress);
});

Retry a failed upload

Retry every failed upload on a share. Call it when an item's upload.status is failed.

When the feature is off, the call resolves ok: false with code: "common/feature_disabled".

bdk.share.onReceived((share) => {
  for (const item of share.items) {
    if ("upload" in item && item.upload.status === "failed") {
      void retry(share.shareId);
    }
  }
});

async function retry(shareId: string) {
  const result = await bdk.share.retryUpload({ shareId });

  if (!result.ok) {
    console.log(result.code, result.message);
    return;
  }

  console.log("retrying", result.retrying);
}

What a share looks like

A BdkInboundShare has a source (ios-extension or android-intent), a status (pending, complete, partial, or failed), and items — text, a url, or a file (image / video / file) with an upload state (pending, uploading, uploaded, failed, rejected, skipped). The SDK exposes upload outcomes, never raw file bytes or device paths.

bdk.share.onReceived((share) => {
  console.log(share.source, share.status);

  for (const item of share.items) {
    if (item.kind === "text") console.log(item.text);
    if (item.kind === "url") console.log(item.url);
    if ("upload" in item) console.log(item.name, item.upload.status);
  }
});