Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kontext.so/llms.txt

Use this file to discover all available pages before exploring further.

Regardless of which SDK you use, all platforms follow the same workflow and share the same basic requirements. Our ads can be integrated into many types of apps, but the most common scenario is companion apps, where long conversations take place between a user and an assistant (chatbot, character). When the user sends a message, the companion app generates a reply — and immediately beneath that reply, our SDK displays an ad.

​
Two Phases: Preload and Stream

The full ad workflow consists of two distinct phases: preload and stream.

​
Preload Phase

The preload phase begins immediately after the user sends a message, before the assistant’s response is generated. During this phase, the SDK calls the Preload API to:
  • analyze the latest conversation context
  • request ads from DSPs
  • select the best ad for the user and conversation
This selection happens in parallel with the assistant message being generated.

​
Stream Phase

Once the assistant message is generated, the SDK enters the stream phase. Here, the SDK takes the previously selected ad and streams it under the assistant’s message inside an HTML iframe.

​
Flow

  1. The user sends a message.
  2. Two things start simultaneously:
    • The app begins generating the assistant’s response.
    • The SDK enters the preload phase, calling the Preload API with all necessary parameters.
  3. The assistant’s message is generated and displayed in the app.
  4. Once preload finishes, the SDK moves to the stream phase and begins streaming the ad.
Why two phases? Why not do everything at once?Because of speed.Analyzing context and selecting an ad can take up to ~1 second.Instead of waiting for that delay after the assistant’s message, we use the “free time” while the app is generating its AI response.Thanks to this, the ad is ready the moment the assistant message appears, resulting in a fast and seamless user experience.

​
What We Need to Generate Great Ads

To serve high-quality, high-performing ads, the publisher must provide several key parameters.

​
1. Messages

We support two message roles:
  • user: what the user types
  • assistant: AI-generated replies
There is no limit to how many messages you send — but the more context we have, the better the ad targeting.

​
2. User ID

You must provide a persistent unique ID for each user of your app. The format does not matter, but the ID must remain the same across conversations. This is important for:
  • retargeting
  • frequency capping
  • distinguishing new vs returning users
If user IDs are not persistent, every request looks like a new user, which dramatically reduces ad performance.

​
3. IDFA, GAID, IDFV

These are standard device identifiers used across the advertising ecosystem. They help advertisers recognize users across apps and platforms and dramatically increase the number and quality of available ads. Providing them significantly improves:
  • fill rate
  • revenue
  • ad relevance

​
4. Character Parameters

In companion apps, the character is the bot the user talks to. Providing character details (at minimum: id, name, avatarUrl) enables us to generate interstitial rewarded ads, which are currently the highest-performing ad format.

​
5. Regulatory Parameters

While not strictly mandatory, it is strongly recommended to send regulatory and consent data, such as:
  • GDPR
  • COPPA
  • GPP
  • US Privacy (CCPA/LSPA)
This ensures:
  • full compliance
  • maximum advertiser demand
  • no blocked traffic due to missing consent signals