Skip to main content
engage

Push events

active
Audience: developerUpdated 2026-09-01

Lookup 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. bb_ is Binoban's reserved system-event namespace, so don't name an event of your own with it; see Track → The bb_ prefix is reserved.

EventEmitted whenPlatforms
bb_notification_registeredYou hand a push token to the SDK.Web · Android · iOS · React Native
bb_notification_deliveredThe notification was displayed.all — iOS foreground only
bb_notification_clickedThe body or an action button was tapped.all
bb_notification_closedThe user dismissed the notification.all
bb_notification_failedThe notification could not be displayed.all
bb_notification_openedThe 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​

PropertyValue
keyThe push token you registered.
device_idThe SDK's device identifier.
package_nameThe app package. Native only.
sdkWEB, 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:

PropertyValue
idThe notification's tracking token (the payload's id).
actionIdThe tapped action button's id, or absent for a body tap.
urlThe resolved target URL or deep link, when there was one.
reasonWhy 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.

EndpointFired 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.

KeyRead byMeaning
sourceallAlways "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.
idallOpaque tracking token; also the notification's identity.
titleallNotification title.
bodyallNotification body.
imageallLarge image URL.
actionallMain target URL or deep link.
actionsallJSON array of { title, action }. Native displays up to 3 buttons, the web service worker up to 2.
customDataAndroid · iOS · React NativeJSON object of string values, surfaced as NotificationInteraction.customData.
iconWebSmall icon URL.
badgeWebBadge URL.
requireInteractionWebKeeps the notification on screen until the user acts.

customData is not surfaced on the web — the service worker does not read it.

Next steps​