Kinz-ID SDK Docs

SDK Reference

Everything window.AdsKinz exposes: one init function, one controller method, and optional lifecycle events.

window.AdsKinz.init(options)

Creates and returns an ad controller for one placement. Call it once per format you use — if your Mini App shows both an interstitial and a pop interstitial at different points, create two controllers.

Parameters

OptionTypeRequiredDescription
kinzIdstringyesThe identifier issued when your Mini App was approved in the partner workspace.
format"interstitial" | "popInterstitial"yesWhich ad format this controller serves. Must be a format you enabled for this Mini App.
debugbooleannoWhen true, logs SDK lifecycle events to the console. Default false.

Returns

An AdController object with a single method, .show().

javascript
const AdController = window.AdsKinz.init({
  kinzId: "kz_live_9f3a2c1b",
  format: "interstitial"
});

AdController.show()

Requests and displays one ad. Returns a Promise.

Resolves with

typescript
{
  state: "completed" | "closed"
}
  • "completed" — the user watched the ad to the end (or a non-skippable format finished naturally).
  • "closed" — the user closed the ad before it finished. For popInterstitial this is normal and expected, not an error: the format is designed to be dismissible.

Rejects with

typescript
{
  code: "NO_FILL" | "NETWORK_ERROR" | "NOT_INITIALIZED" | "RATE_LIMITED"
}

Behavior notes

  • Calling .show() while an ad from the same controller is already showing is a no-op — the existing Promise is returned again, not a new request.
  • The SDK reads window.Telegram.WebApp.initDataUnsafe.user.language_code to request a creative already translated into the user's language. Unsupported languages fall back to English server-side — nothing to configure.

Events

For finer-grained lifecycle hooks than the Promise alone provides:

javascript
AdController.on("show", () => { /* ad started rendering */ });
AdController.on("complete", () => { /* user finished watching */ });
AdController.on("close", () => { /* user dismissed early */ });

Optional

Most integrations only need the .show() Promise.
←QuickstartReact Hook→