Publisher SDK

IdleFlow shows a small sponsored card only while your AI app is loading, streaming, or thinking. An impression is billable only after five seconds of focused, visible display. Publishers keep 70% of verified revenue.

1. Create a publisher app

Sign in at /publisher, register your app, and verify the domain. Detection is automatic once the tag is in — see the full integration guide (also readable by AI coding agents like Cursor or Claude Code).

2. Add the tag

<script async
  src="https://YOUR_DOMAIN/sdk/publisher.js"
  data-publisher-id="pub_yourid"
  data-app-id="app_yourapp">
</script>

Zero-config: the SDK wraps fetch, XMLHttpRequest, and EventSource and treats an open streaming or long-lived LLM request as a wait — covering every page automatically with no selectors. For most AI apps this is all you need.

3. Mark AI calls explicitly (recommended)

For exact, bulletproof detection — including non-streaming or authenticated flows — wrap your model call. Counter-based, so nested/concurrent calls are fine. Always pair with try/finally.

window.idleflow.beginWait();   // before your AI request
try { /* await the model */ } finally { window.idleflow.endWait(); }

// legacy hard override still supported:
window.idleflow.signalBusy(true);   // force busy
window.idleflow.signalBusy(false);  // force idle

4. Test mode

Test mode renders a local test ad, never sends billing events, and shows a live detection HUD in the bottom-left of your own pages — trigger an AI action and confirm it reads 🟢 WAIT DETECTED with the tier that fired. The cheapest way to verify the integration on your real app.

<script async
  src="/sdk/publisher.js"
  data-publisher-id="test"
  data-mode="test">
</script>

Use the hosted SDK test page to verify that the card appears and the manual busy API behaves correctly.

5. Optional audience attributes

Only send coarse first-party bands with user consent. The server validates these values and rejects PII-shaped data.

window.idleflow.setUserAttributes({
  ageBand: "25-34",
  gender: "other",
  interests: ["developer-tools", "ai-coding"]
});

6. Events for your analytics

The SDK emits browser events you can listen to without touching billing logic.

window.addEventListener("idleflow:adShown", (e) => console.log(e.detail));
window.addEventListener("idleflow:impression", (e) => console.log(e.detail));
window.addEventListener("idleflow:click", (e) => console.log(e.detail));