Trace a Visitor
draftFollow 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
| Ending | When |
|---|---|
| You end it | leaveTrace() |
| It expires | 12 hours after it was joined |
| It hits the cap | after 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
- Debug Mode — verbose console diagnostics
- Inspector — check a live page without touching a console
- Web SDK reference — the full method surface
- Error codes — what a refusal means