Push events
activeLookup reference for what the Binoban SDKs emit and read on the push and web-push channels. For the integration steps, start at Activate Engage.
The bb_notification_* events
Every SDK emits the same event family. You do not construct these — the SDKs emit them as a side effect of registering a token and of displaying and handling a notification.
| Event | Emitted when | Platforms |
|---|---|---|
bb_notification_registered | You hand a push token to the SDK. | Web · Android · iOS · React Native |
bb_notification_delivered | The notification was displayed. | all — iOS foreground only |
bb_notification_clicked | The body or an action button was tapped. | all |
bb_notification_closed | The user dismissed the notification. | all |
bb_notification_failed | The notification could not be displayed. | all |
bb_notification_opened | The app was launched from a notification carrying no target URI. | Android |
bb_notification_delivered fires on display, not on receipt — a message that
arrives but fails to render reports failed, not delivered. On iOS it is
reported from the foreground-presentation callback, so a notification displayed
while the app is backgrounded does not produce one.
bb_notification_registered
| Property | Value |
|---|---|
key | The push token you registered. |
device_id | The SDK's device identifier. |
package_name | The app package. Native only. |
sdk | WEB, ANDROID, or IOS. |
On the Native SDKs, setDeviceToken / Notification.refreshToken emit this
directly. On the Web SDK you call track('notification_registered', { key }) and
the SDK's push plugin renames the event to bb_notification_registered and adds
sdk: "WEB" plus device_id.
Interaction events
delivered, clicked, closed, failed, and opened carry the notification's
tracking token plus what the SDK knows locally:
| Property | Value |
|---|---|
id | The notification's tracking token (the payload's id). |
actionId | The tapped action button's id, or absent for a body tap. |
url | The resolved target URL or deep link, when there was one. |
reason | Why display or delivery failed. failed only. |
Campaign attribution — campaign, variation, profile, channel, provider — is
not sent by the SDK. The id is an opaque token that already encodes it, and
Binoban resolves those fields server-side. That is why a client only ever needs
to echo the token back.
Interaction callbacks
Alongside the events, the SDKs call these endpoints directly so interactions are
recorded even when an event batch has not flushed yet. Base is your apiHost.
| Endpoint | Fired for |
|---|---|
GET /api/tracker/general/delivered?token=<id> | Notification displayed. |
GET /api/tracker/general/click?token=<id>&url=<target> | Tap. The Web SDK also sends &button=<0|1|2> — 0 is a body tap. |
GET /api/tracker/general/close?token=<id> | Dismissal. |
GET /api/tracker/general/failed?token=<id> | Display failed. |
GET /api/tracker/general/open?token=<id> | App launched from a notification with no target. Android. |
The Native SDKs write the cached event first and then make this call, so an offline or killed-mid-call device still reports the interaction when it next opens. Delivery is at-least-once by design.
Push payload keys
Binoban always sends data-only messages — never an FCM notification
payload. These are the keys the SDKs read from the message data object.
| Key | Read by | Meaning |
|---|---|---|
source | all | Always "binoban", set by Binoban's backend — never by you. The SDKs ignore any payload where it isn't, so they coexist safely with your own push handling; branch on it in your own handler so Binoban's messages don't fall through into it. See Web push and App push. |
id | all | Opaque tracking token; also the notification's identity. |
title | all | Notification title. |
body | all | Notification body. |
image | all | Large image URL. |
action | all | Main target URL or deep link. |
actions | all | JSON array of { title, action }. Native displays up to 3 buttons, the web service worker up to 2. |
customData | Android · iOS · React Native | JSON object of string values, surfaced as NotificationInteraction.customData. |
icon | Web | Small icon URL. |
badge | Web | Badge URL. |
requireInteraction | Web | Keeps the notification on screen until the user acts. |
customData is not surfaced on the web — the service worker does not read it.
Next steps
- Activate Engage — what to integrate.
- Web push · App push — the recipes.
- Tracking API — how events reach Binoban.