Skip to main content
sdk

Trace a Visitor

draft
Audience: developerUpdated 2026-08-26

Follow one visitor's events from the call your code makes to what Binoban received.

A trace session is a short-lived, opt-in window. While it is active, every event that visitor's device sends carries a traceSessionId, and the SDK keeps a local record of what happened to each upload — including the ones the server refused. It is the tool for the question "I called track(), so why is nothing arriving?".

A trace is deliberately hard to leave running. It ends by itself after 12 hours or 250 events, whichever comes first, and the SDK enforces both without asking a server. Nothing starts a trace except an explicit call or a link the visitor opens.

Get a session code​

Trace codes are issued in the Binoban panel, under Data → Data Health. A code is 8 to 64 characters of A-Z a-z 0-9 - _. The panel issues them in lowercase, and the SDKs fold case and trim whitespace when you join, so a code read off the screen and typed in capitals joins the same session rather than a different one.

The panel shows the code as text and as a QR code. Both work; which one you use depends on whether you can reach the device.

Join the trace​

Web SDK​

Binoban.joinTrace('k4rq-8w2m-h7bd');

Every event after that call carries the session, including the page() call your loader fires on the next navigation. Call it from your own code, or paste it into the browser console on the page you are debugging.

To end the session early:

Binoban.leaveTrace();

You can also start a trace without touching any code, by adding the session code to the page URL as bnb_trace:

https://shop.example.com/checkout?bnb_trace=k4rq-8w2m-h7bd

The SDK reads that parameter once, while it is starting up, so the very first event of the page load is already inside the trace. This is what the panel's QR code encodes — on the web it needs nothing configured on your side, because a QR that opens a URL is just a link.

Native SDK (Android & iOS)​

// Android (Kotlin)
Binoban.activeInstance?.joinTrace("k4rq-8w2m-h7bd")
Binoban.activeInstance?.leaveTrace()
// iOS (Swift)
BinobanTrace.shared.join(traceSessionId: "k4rq-8w2m-h7bd")
BinobanTrace.shared.leave()

On mobile the QR path opens a deep link carrying ?bnb_trace=, which means it only works if your app has App Links (Android) or Universal Links (iOS) configured for that URL. When they are not configured, scanning the QR opens a browser and nothing happens, with no error anywhere — so read the code from the panel and join it manually instead. The manual code always works.

Android handles the link for you once Configuration.application is set. iOS has no equivalent hook, so forward the URL from your app delegate:

func application(_ app: UIApplication, open url: URL, options: ...) -> Bool {
BinobanTrace.shared.handleUrl(url: url)
return true
}

React Native​

binoban.joinTrace('k4rq-8w2m-h7bd');
binoban.leaveTrace();

Incoming links are handled for you by default — the client subscribes to Linking and joins any link carrying bnb_trace. Pass autoTraceLinks: false when you construct the client if you would rather forward links yourself with binoban.handleTraceLink(url).

Check whether a trace is running​

// Web SDK
Binoban.activeTraceSessionId(); // 'k4rq-8w2m-h7bd', or null
// Android (Kotlin)
Binoban.activeInstance?.activeTraceSessionId
// iOS (Swift)
BinobanTrace.shared.activeSessionId()

This returns null once the session has expired. Note that it still returns the id between the 250th and 251st event — the session ends on the next event the SDK tries to tag, not the moment the count is reached. If you are tracing and events have stopped appearing, assume the cap was reached and start a fresh session.

Read what happened to each upload​

While a trace is active, the SDK records the outcome of every upload into a small in-memory buffer — the last 100 — and this is the part that works entirely on the device. Each record holds the event name, the HTTP status, and, when the server refused the event, the code, field and reason it gave back.

// Web SDK
Binoban.traceDeliveryLog();
// Android (Kotlin)
Binoban.activeInstance?.traceDeliveryLog()
// iOS (Swift)
BinobanTrace.shared.deliveryLog()

A record looks like this:

{
"timestampMillis": 1756200000000,
"eventNames": ["checkout_started"],
"httpStatus": 400,
"code": "NOT_BLANK",
"field": "userId",
"reason": "must not be blank",
"clockState": "SYNCED",
"clockOffsetMillis": 0
}

This is the only place a rejection survives. A refused event is not stored anywhere on the server, so if you do not read it here, the reason it was refused is gone.

Three things about the log are worth knowing before you rely on it:

  • It holds error metadata only. Event payloads are never recorded, on any platform.
  • It does not survive the session. Ending a trace clears it, and so does hitting the cap or the expiry. Read it before you call leaveTrace().
  • It is per-device and in-memory. It does not survive a page reload on the web, and it is not sent anywhere. Copy what you need out of it.

httpStatus is 0 when there was no response at all — a dead connection, a blocked request, or an event that never left the device. A 500 and a timeout both read as 0 today; the message in reason is what tells them apart.

How a trace ends​

EndingWhen
You end itleaveTrace()
It expires12 hours after it was joined
It hits the capafter 250 events

The SDK enforces all three itself and never asks the server whether a trace is still valid — it cannot, because a trace may have been ended in the panel while the device is offline. This is deliberate: it is what stops a forgotten trace from becoming a permanent identifier for that visitor.

Joining a code while a different one is active replaces it. Re-joining the code that is already active does nothing at all — it does not extend the window, reset the count, or clear the log — which is what keeps a single-page app that re-reads its URL from extending a trace forever.

What a trace does not do​

  • It does not turn on console logging. For that, see Debug Mode.
  • It does not check a page from the outside, or produce a report you can hand to someone else. For that, see the Inspector.
  • It does not change what is collected. Consent and enablement are applied first, so an event the SDK would not have sent is not traced either.

See also​