Background data messages

Listen for silent data payloads and read the retained queue after a cold start.

Listen for data messages

Subscribe for a data payload as it arrives. These are data messages, not user-visible notifications — the result arrives on push.dataReceived, so subscribe before you read the queue.

Each live event is a BdkPushDataMessage without delivered. appState is foreground, background, or cold.

Property	Type	Description
`id`	`string`	Message id.
`receivedAt`	`number`	When the device received it.
`appState`	`string`	`foreground`, `background`, or `cold`.
`data`	`object`	The payload your provider sent.

Subscribe to push.dataReceived before you call getDataMessages(), or a live delivery can be missed.

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

const bdk = createBdkNative();

const off = bdk.on("push.dataReceived", (message) => {
  console.log(message.id, message.appState, message.data);
});

const queued = await bdk.push.getDataMessages();

if (!queued.ok) return;

// off() when the page unmounts

Read the retained queue

Read messages that arrived while the page wasn't listening. Newest first. The read does not remove them. The native side keeps the most recent 20.

When delivered is present, native attempted delivery — not that a page listener confirmed receipt.

This feature can be switched off in a given app build. Check await bdk.capabilities.has("push.data") before showing the UI. When it is off, the call resolves ok: false with code: "common/feature_disabled". See Detect features.

In a plain browser the call resolves ok: false with a code like common/feature_disabled — branch on !result.ok.

if (!(await bdk.capabilities.has("push.data"))) {
  // Hide the inbox UI — this build does not include it.
}

const result = await bdk.push.getDataMessages();

if (!result.ok) {
  return;
}

console.log(result.count);

for (const message of result.messages) {
  console.log(message.id, message.appState, message.data, message.delivered);
}

Send a data message

Send a data or silent payload from your push provider. There is no SDK call to send one from the page.