IDs and tokens

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.

Every Kontext integration uses a handful of identifiers. Some you supply when creating a session; some are issued by Kontext during onboarding; others are read by the SDK directly from the OS. This page covers what each is, who generates it, and what it is used for.

​

publisherToken

Kontext issues you a publisherToken during onboarding. It identifies your account, governs which placements and ad formats your app may render, and is the key that the ad server uses to attribute revenue to you. You’ll typically have two tokens:

• A development token that returns test ads (the standard test creatives, useful for end-to-end testing during integration).
• A production token that participates in the real auction.

You can ship the production token in the client app — it is not a server secret. Treat it like a public API key with limited scope: do not actively publish it, but losing it from the client binary is not a security incident.

​

Placement code

A placement code identifies a specific kind of ad slot in your app. The default code is inlineAd, which most apps use without further configuration. Kontext issues additional codes during onboarding if your app uses more than one ad slot type. You pass the placement code on every ad component (for example, <InlineAd code="inlineAd" messageId="..." />). If your app uses custom or multiple placement codes, also pass the list of codes you may render in enabledPlacementCodes when creating the session — the SDK only attempts to fill placements whose codes appear in this list.

​

userId

userId is your identifier for this user. It should be:

• Stable across conversations. The same user starting a new conversation tomorrow should arrive with the same userId. This is what makes retargeting and rewarded ads work — the ad server needs to know it is talking to the same user it has seen before.
• Not personally identifiable. Pass an anonymized internal user id. The ad server does not need PII to do its job.
• Unique per user. Different users must get different userIds — anonymous fallback values ("anonymous", null, the empty string) collapse everyone into one record and break retargeting.

If your app doesn’t yet have a stable user id, generate a UUID on first launch and persist it; that is enough.

​

conversationId

conversationId is your identifier for this conversation. Generate a new one whenever the user starts a new conversation, and reuse it for as long as the conversation lasts. The session is bound to one conversationId — see Session lifecycle for the rules around when to create or reuse. A conversationId should be unique across all conversations from a given user. Reusing one will mix ad cache and analytics from unrelated chats; the SDK will keep working but the data will be wrong.

​

Advertising identifier (IFA)

The SDK reads the platform’s standard Identifier for Advertisers when one is available and the user has granted permission:

• iOS — IDFA. Gated by Apple’s App Tracking Transparency (ATT) prompt since iOS 14. Your app must declare NSUserTrackingUsageDescription in Info.plist and trigger the prompt at a natural moment in the app flow.
• Android — GAID. Declared via the com.google.android.gms.permission.AD_ID permission, which the SDK contributes through manifest merger. Respected by the user’s Google account ad-personalization settings.
• Web. No direct equivalent.

You don’t pass the IFA in — the SDK reads it directly from the OS. When the IFA is available it is forwarded on every ad request; when it is not (permission denied, OS-level opt-out, or no IFA on the platform) the SDK falls back to a first-party identifier it generates internally. See Compliance for the consent and platform-policy details.

​

IDFV

IDFV is the Identifier for Vendor on iOS — a UUID Apple assigns to your app vendor on a device. Unlike IDFA, it does not require ATT permission and is always available on iOS. The SDK reads it via UIDevice.current.identifierForVendor and forwards it on every ad request as a stable iOS-side companion to the IFA. It is per app vendor on a device: every app from the same developer team shares the same IDFV on that device, and the IDFV resets when the user uninstalls every app from that vendor.

​

Where to next