Debugging

The SDK exposes two callbacks. Pick whichever you need.

`onEvent` — public ad lifecycle

onEvent fires for the small set of public ad-lifecycle events: ad.filled, ad.no-fill, ad.viewed, ad.clicked, ad.error, plus the video and reward events. These are the ones you typically wire your UI and analytics to. The complete list with payloads lives on Ad lifecycle events.

`onDebugEvent` — detailed internal log

onDebugEvent fires for every internal step the SDK takes — preload requests starting and resolving, message-id pairing decisions, retry attempts, iframe loading milestones, and so on. It is verbose and not stable across SDK versions; treat it as a diagnostic log, not an API. Wire it up only while you’re investigating something, then turn it back off in production:

onDebugEvent: (name, data) => {
  console.log('[kontext]', name, data)
}

When something looks off

If an ad doesn’t appear, fires the wrong event, or the SDK behaves unexpectedly:

Re-enable onDebugEvent in your build.
Reproduce the issue.
Capture the full onDebugEvent output and share it with us at support@kontext.so.

The debug log is the fastest way for us to pinpoint what happened on your side without remote-debugging the integration.

`skipCode` reference

When an ad.no-fill event fires, its payload carries a skipCode explaining why no ad was returned. The values you might see:

`skipCode`	Meaning	What to do
`ads_disabled`	The SDK told the server ads are disabled for this request, because you called `addMessage` with `trackOnly: true`.	Expected in track-only mode.
`ad_skipped`	The server intentionally skipped this turn — typically because of pacing.	Expected; the next eligible turn will show an ad.
`ivt_blocked`	An invalid-traffic check blocked the request.	Real users shouldn’t see this. If recurring in production, contact support.
`unfilled_bid`	The auction ran but no bidder returned a usable ad.	Expected occasionally — fill rate is never 100%.
`illegal_content`	The conversation content was flagged as unsafe for ads.	Review the message text — some categories don’t get ads.
`unknown`	Catch-all for reasons we don’t yet expose individually.	Capture the `onDebugEvent` output and send it to support.

Get Started

Concepts

Guides

SDKs

Resources

`onEvent` — public ad lifecycle

`onDebugEvent` — detailed internal log

When something looks off

`skipCode` reference

​onEvent — public ad lifecycle

​onDebugEvent — detailed internal log

​When something looks off

​skipCode reference

`onEvent` — public ad lifecycle

`onDebugEvent` — detailed internal log

When something looks off

`skipCode` reference