Patterns and recipes for common Kotlin SDK integration tasks.
Handling no-fill
Subscribe to AdEvent.NoFill to know when no ad was returned (geo-restriction, frequency cap, etc.). The skipCode payload tells you why.
onEvent = { event -> if (event is AdEvent.NoFill) { android.util.Log.d("kontext", "no fill: ${event.skipCode}") }}
Lifecycle management
Always call session.destroy() (or its alias session.close()) when the conversation ends or the screen is closed. It cancels in-flight preloads, tears down every mounted ad, finalizes the OMID session, and releases WebView resources. Idempotent.In Compose, anchor it to the screen-level DisposableEffect:
override fun onCleared() { session.destroy() super.onCleared()}
Live-updating session options
A subset of session options can be live-updated without recreating the session. Updates are read on the next /preload, so changes take effect on the next user message.
Live-updateable fields: variantId, regulatory, userEmail, advertisingId. Non-null fields overwrite; null fields are left unchanged. To clear a field, recreate the session.
publisherToken, userId, conversationId, enabledPlacementCodes, and character are not live-updateable. Changing them mid-session would desync the /init registration or leave the accumulated message history targeted at the wrong persona. Recreate the session instead.
Live-updating consent mid-session
When the user updates their consent in your CMP, call:
The next preload picks up the new value — no session recreation needed.
Switching character
The active character cannot be live-updated — the accumulated message history belongs to the original persona, so swapping mid-session would leave messages targeted at the wrong character.To switch character, destroy the current session and create a new one:
The same applies to publisherToken, userId, conversationId, and enabledPlacementCodes — recreate the session whenever any of those change.
Loading older messages (conversation restore)
When restoring a conversation from your backend, call addMessage(...) once per historical message in order. Preloads are debounced, so rapid sequential calls coalesce into a single preload for the most recent user message — you won’t fire one preload per restored message.
for (historical in loadedFromBackend) { session.addMessage( Message( id = historical.id, role = historical.role, content = historical.content, ), )}
Pass every message, suppress ads with trackOnly
Always feed every message into the session, even when you don’t want an ad to appear (e.g. when a user is on a paid tier, in a no-ads region, or you’ve decided to show ads only every Nth message). Skipping addMessage(...) calls breaks the conversation context the server relies on for targeting. See Pacing for the full pattern.
When trackOnly = true, the preload still fires (server keeps full analytics) but no AdEvent.Filled will arrive for that message and session.createAd(...) won’t resolve to a fillable ad.
Theming
Pass a publisher-defined theme string to the InlineAd composable; it propagates into the iframe’s update-iframe payload and is available to ad creatives.
Theme is part of the Ad identity key — flipping it for the same messageId causes the iframe to reload with the new value.
View interop (non-Compose)
For apps not on Jetpack Compose, use InlineAdView (a FrameLayout subclass). Inflate or instantiate it like any other view, then call bind(messageId, session):
import so.kontext.ads.ui.InlineAdViewval adView = InlineAdView(context)adView.layoutParams = ViewGroup.LayoutParams(MATCH_PARENT, WRAP_CONTENT)adView.onHeightChange = { newHeight -> // Resize the surrounding row if you're inside a RecyclerView requestRowLayout()}adView.bind(messageId = assistantMessageId, session = session)container.addView(adView)
The view follows the same lifecycle rules as the composable — call session.destroy() on screen teardown; the view’s WebView is recycled by the session’s pool.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Kontext Documentation","colors":{"primary":"#FF682F","light":"#FF682F","dark":"#FF682F"},"logo":{"light":"https://mintcdn.com/kontext/cSTBM3iNvsT_Fm-X/logo/light.svg?fit=max\u0026auto=format\u0026n=cSTBM3iNvsT_Fm-X\u0026q=85\u0026s=31c1ad1d9c273a4f7ae529ee4ef3bedb","dark":"https://mintcdn.com/kontext/cSTBM3iNvsT_Fm-X/logo/dark.svg?fit=max\u0026auto=format\u0026n=cSTBM3iNvsT_Fm-X\u0026q=85\u0026s=22c43eed074c01e3ffb02e7028b8ae5b"},"favicon":"https://mintcdn.com/kontext/cSTBM3iNvsT_Fm-X/favicon.svg?fit=max\u0026auto=format\u0026n=cSTBM3iNvsT_Fm-X\u0026q=85\u0026s=7fcf8285ddde4170884f9cc8f6141b71","navbar":{"links":[{"href":"mailto:support@kontext.so","label":"Support"}],"primary":{"type":"button","label":"Go to kontext.so","href":"https://kontext.so"}},"styling":{"latex":false},"navigation":{"languages":[{"language":"en","href":"overview"},{"language":"zh","href":"zh/overview"}]}},"deployment":{"deploymentMetadataValue":{"subdomain":"kontext","hasAudioNarration":false,"actualSubdomain":"kontext","customDomains":["docs.kontext.so"],"gitSource":{"type":"github","owner":"kontextso","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6af2488cd4107adac0a78a43","clientVersion":"0.0.4177","searchFilterCounts":[{"language":"en","tag":"SDKs","count":61},{"language":"zh","tag":"SDK","count":61},{"language":"en","tag":"Conversational Ads","count":52},{"language":"en","tag":"Video Ads","count":51},{"language":"zh","tag":"对话广告","count":51},{"language":"zh","tag":"视频广告","count":50},{"language":"en","tag":"Guides","count":30},{"language":"en","tag":"Kotlin Video SDK","count":18},{"language":"zh","tag":"Kotlin 视频 SDK","count":18},{"language":"en","tag":"Swift Video SDK","count":16},{"language":"zh","tag":"Swift 视频 SDK","count":16},{"language":"zh","tag":"实践指南","count":15},{"language":"zh","tag":"指南","count":15},{"language":"en","tag":"Concepts","count":13},{"language":"zh","tag":"核心概念","count":13},{"language":"en","tag":"Resources","count":10},{"language":"zh","tag":"资源","count":8},{"language":"en","tag":"Players","count":7},{"language":"zh","tag":"播放器","count":7},{"language":"en","tag":"JavaScript SDK","count":6}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"sdk/kotlin/guides","slug":"/sdk/kotlin/guides","pageMetadata":{"title":"Guides","description":"Patterns and recipes for common Kotlin SDK integration tasks.","href":"/sdk/kotlin/guides"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Patterns and recipes for common Kotlin SDK integration tasks.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`2`,id:`handling-no-fill`,children:`Handling no-fill`}),`\n`,_jsxs(_components.p,{children:[`Subscribe to `,_jsx(_components.code,{children:`AdEvent.NoFill`}),` to know when no ad was returned (geo-restriction, frequency cap, etc.). The `,_jsx(_components.code,{children:`skipCode`}),` payload tells you why.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`onEvent = { event ->`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (event `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`is`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AdEvent.NoFill) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` android.util.Log.d(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"kontext\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:'\"no fill: ${event.skipCode}\"'}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`lifecycle-management`,children:`Lifecycle management`}),`\n`,_jsxs(_components.p,{children:[`Always call `,_jsx(_components.code,{children:`session.destroy()`}),` (or its alias `,_jsx(_components.code,{children:`session.close()`}),`) when the conversation ends or the screen is closed. It cancels in-flight preloads, tears down every mounted ad, finalizes the OMID session, and releases WebView resources. Idempotent.`]}),`\n`,_jsxs(_components.p,{children:[`In Compose, anchor it to the screen-level `,_jsx(_components.code,{children:`DisposableEffect`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`DisposableEffect(session) {`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` onDispose { session.close() }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`In a ViewModel:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`override`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` fun`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` onCleared() {`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` session.destroy()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` super`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.onCleared()`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`live-updating-session-options`,children:`Live-updating session options`}),`\n`,_jsxs(_components.p,{children:[`A subset of session options can be live-updated without recreating the session. Updates are read on the next `,_jsx(_components.code,{children:`/preload`}),`, so changes take effect on the next user message.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` so.kontext.ads.model.MutablePublisherOptions`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`session.updateOptions(MutablePublisherOptions(variantId = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"new-variant\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`))`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Live-updateable fields: `,_jsx(_components.code,{children:`variantId`}),`, `,_jsx(_components.code,{children:`regulatory`}),`, `,_jsx(_components.code,{children:`userEmail`}),`, `,_jsx(_components.code,{children:`advertisingId`}),`. Non-null fields overwrite; null fields are left unchanged. To clear a field, recreate the session.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`publisherToken`}),`, `,_jsx(_components.code,{children:`userId`}),`, `,_jsx(_components.code,{children:`conversationId`}),`, `,_jsx(_components.code,{children:`enabledPlacementCodes`}),`, and `,_jsx(_components.code,{children:`character`}),` are `,_jsx(_components.strong,{children:`not`}),` live-updateable. Changing them mid-session would desync the `,_jsx(_components.code,{children:`/init`}),` registration or leave the accumulated message history targeted at the wrong persona. Recreate the session instead.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`live-updating-consent-mid-session`,children:`Live-updating consent mid-session`}),`\n`,_jsx(_components.p,{children:`When the user updates their consent in your CMP, call:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` so.kontext.ads.model.Regulatory`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`session.updateOptions(MutablePublisherOptions(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` regulatory = Regulatory(gdpr = 1, gdprConsent = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\u003cnew-TCF-string>\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`),`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`))`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`The next preload picks up the new value — no session recreation needed.`}),`\n`,_jsx(Heading,{level:`2`,id:`switching-character`,children:`Switching character`}),`\n`,_jsxs(_components.p,{children:[`The active `,_jsx(_components.code,{children:`character`}),` cannot be live-updated — the accumulated message history belongs to the original persona, so swapping mid-session would leave messages targeted at the wrong character.`]}),`\n`,_jsx(_components.p,{children:`To switch character, destroy the current session and create a new one:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`11`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`session.destroy()`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`session = KontextAds.createSession(`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` context = applicationContext,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` options = SessionOptions(`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` publisherToken = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\u003cyour-publisher-token>\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` userId = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"user-1234\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` conversationId = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"conv-new\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` character = newCharacter,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ),`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The same applies to `,_jsx(_components.code,{children:`publisherToken`}),`, `,_jsx(_components.code,{children:`userId`}),`, `,_jsx(_components.code,{children:`conversationId`}),`, and `,_jsx(_components.code,{children:`enabledPlacementCodes`}),` — recreate the session whenever any of those change.`]}),`\n`,_jsx(Heading,{level:`2`,id:`loading-older-messages-conversation-restore`,children:`Loading older messages (conversation restore)`}),`\n`,_jsxs(_components.p,{children:[`When restoring a conversation from your backend, call `,_jsx(_components.code,{children:`addMessage(...)`}),` once per historical message in order. Preloads are debounced, so rapid sequential calls coalesce into a single preload for the most recent user message — you won’t fire one preload per restored message.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`9`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (historical `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` loadedFromBackend) {`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` session.addMessage(`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` Message(`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` id = historical.id,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` role = historical.role,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` content = historical.content,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` ),`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` )`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),`\n`,_jsxs(Heading,{level:`2`,id:`pass-every-message-suppress-ads-with-trackonly`,children:[`Pass every message, suppress ads with `,_jsx(_components.code,{children:`trackOnly`})]}),`\n`,_jsxs(_components.p,{children:[`Always feed every message into the session, even when you don’t want an ad to appear (e.g. when a user is on a paid tier, in a no-ads region, or you’ve decided to show ads only every Nth message). Skipping `,_jsx(_components.code,{children:`addMessage(...)`}),` calls breaks the conversation context the server relies on for targeting. See `,_jsx(_components.a,{href:`/concepts/pacing`,children:`Pacing`}),` for the full pattern.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`8`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` so.kontext.ads.model.AddMessageOptions`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`val`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` shouldShowAd = userMessageCount % 5 == 0`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`session.addMessage(`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` Message(id = msg.id, role = Role.USER, content = msg.content),`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AddMessageOptions(trackOnly = !shouldShowAd),`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`When `,_jsx(_components.code,{children:`trackOnly = true`}),`, the preload still fires (server keeps full analytics) but no `,_jsx(_components.code,{children:`AdEvent.Filled`}),` will arrive for that message and `,_jsx(_components.code,{children:`session.createAd(...)`}),` won’t resolve to a fillable ad.`]}),`\n`,_jsx(Heading,{level:`2`,id:`theming`,children:`Theming`}),`\n`,_jsxs(_components.p,{children:[`Pass a publisher-defined theme string to the `,_jsx(_components.code,{children:`InlineAd`}),` composable; it propagates into the iframe’s `,_jsx(_components.code,{children:`update-iframe`}),` payload and is available to ad creatives.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`InlineAd(`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` messageId = msg.id,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` session = session,`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` theme = `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (isSystemInDarkTheme()) `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"dark\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` else`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"light\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Theme is part of the `,_jsx(_components.code,{children:`Ad`}),` identity key — flipping it for the same `,_jsx(_components.code,{children:`messageId`}),` causes the iframe to reload with the new value.`]}),`\n`,_jsx(Heading,{level:`2`,id:`view-interop-non-compose`,children:`View interop (non-Compose)`}),`\n`,_jsxs(_components.p,{children:[`For apps not on Jetpack Compose, use `,_jsx(_components.code,{children:`InlineAdView`}),` (a `,_jsx(_components.code,{children:`FrameLayout`}),` subclass). Inflate or instantiate it like any other view, then call `,_jsx(_components.code,{children:`bind(messageId, session)`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`10`,language:`kotlin`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`kotlin`,children:_jsxs(_components.code,{language:`kotlin`,numberOfLines:`10`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` so.kontext.ads.ui.InlineAdView`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`val`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` adView = InlineAdView(context)`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`adView.layoutParams = ViewGroup.LayoutParams(MATCH_PARENT, WRAP_CONTENT)`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`adView.onHeightChange = { newHeight ->`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` // Resize the surrounding row if you're inside a RecyclerView`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requestRowLayout()`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`adView.bind(messageId = assistantMessageId, session = session)`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`container.addView(adView)`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The view follows the same lifecycle rules as the composable — call `,_jsx(_components.code,{children:`session.destroy()`}),` on screen teardown; the view’s `,_jsx(_components.code,{children:`WebView`}),` is recycled by the session’s pool.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Guides","description":"Patterns and recipes for common Kotlin SDK integration tasks.","href":"/sdk/kotlin/guides"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Handling no-fill","slug":"handling-no-fill","depth":2,"children":[]},{"title":"Lifecycle management","slug":"lifecycle-management","depth":2,"children":[]},{"title":"Live-updating session options","slug":"live-updating-session-options","depth":2,"children":[]},{"title":"Live-updating consent mid-session","slug":"live-updating-consent-mid-session","depth":2,"children":[]},{"title":"Switching character","slug":"switching-character","depth":2,"children":[]},{"title":"Loading older messages (conversation restore)","slug":"loading-older-messages-conversation-restore","depth":2,"children":[]},{"title":"Pass every message, suppress ads with trackOnly","slug":"pass-every-message-suppress-ads-with-trackonly","depth":2,"children":[]},{"title":"Theming","slug":"theming","depth":2,"children":[]},{"title":"View interop (non-Compose)","slug":"view-interop-non-compose","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"kontext","siteName":"Kontext Documentation","title":"Guides - Kontext Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{"en":{"href":"/sdk/kotlin/guides","matchLevel":0},"zh":{"href":"/zh/sdk/kotlin/guides","matchLevel":1}}},"lastModified":"2026-05-20T19:44:58.955Z","originalFileLocation":"sdk/kotlin/guides.mdx","locale":"en"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Patterns and recipes for common Kotlin SDK integration tasks.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Kontext Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Guides - Kontext Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"Patterns and recipes for common Kotlin SDK integration tasks.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Kontext Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.kontext.so/sdk/kotlin/guides\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://kontext.mintlify.site/_mintlify/api/og/v2?division=Kotlin+SDK\u0026amp;title=Guides\u0026amp;description=Patterns+and+recipes+for+common+Kotlin+SDK+integration+tasks.\u0026amp;theme=44e9612051797cc564ea14ef\u0026amp;signature=278eb6111cfa217362144472a6c2ebaa5c3792d22f62f41e7a63bcff7cfa43b5\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Guides - Kontext Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Patterns and recipes for common Kotlin SDK integration tasks.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://kontext.mintlify.site/_mintlify/api/og/v2?division=Kotlin+SDK\u0026amp;title=Guides\u0026amp;description=Patterns+and+recipes+for+common+Kotlin+SDK+integration+tasks.\u0026amp;theme=44e9612051797cc564ea14ef\u0026amp;signature=278eb6111cfa217362144472a6c2ebaa5c3792d22f62f41e7a63bcff7cfa43b5\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/kontext/3zw6PkR8hX7T_tb1/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Kontext Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FF682F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.kontext.so/sdk/kotlin/guides\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/sdk/kotlin/guides.md\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"en\" href=\"https://docs.kontext.so/sdk/kotlin/guides\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"zh\" href=\"https://docs.kontext.so/zh/sdk/kotlin/guides\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"x-default\" href=\"https://docs.kontext.so/sdk/kotlin/guides\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.kontext.so/#organization\",\"name\":\"Kontext Documentation\",\"url\":\"https://docs.kontext.so\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/kontext/cSTBM3iNvsT_Fm-X/logo/light.svg?fit=max\u0026auto=format\u0026n=cSTBM3iNvsT_Fm-X\u0026q=85\u0026s=31c1ad1d9c273a4f7ae529ee4ef3bedb\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.kontext.so#website\",\"name\":\"Kontext Documentation\",\"url\":\"https://docs.kontext.so\",\"publisher\":{\"@id\":\"https://docs.kontext.so/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.kontext.so/sdk/kotlin/guides#webpage\",\"url\":\"https://docs.kontext.so/sdk/kotlin/guides\",\"name\":\"Guides\",\"description\":\"Patterns and recipes for common Kotlin SDK integration tasks.\",\"dateModified\":\"2026-05-20T19:44:58.955Z\",\"isPartOf\":{\"@id\":\"https://docs.kontext.so#website\"},\"breadcrumb\":{\"@id\":\"https://docs.kontext.so/sdk/kotlin/guides#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.kontext.so/sdk/kotlin/guides#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"SDKs\",\"item\":\"https://docs.kontext.so/sdk/swift\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Kotlin SDK\",\"item\":\"https://docs.kontext.so/sdk/kotlin\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Guides\",\"item\":\"https://docs.kontext.so/sdk/kotlin/guides\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.kontext.so/sdk/kotlin/guides#article\",\"headline\":\"Guides\",\"name\":\"Guides\",\"description\":\"Patterns and recipes for common Kotlin SDK integration tasks.\",\"url\":\"https://docs.kontext.so/sdk/kotlin/guides\",\"mainEntityOfPage\":{\"@id\":\"https://docs.kontext.so/sdk/kotlin/guides#webpage\"},\"dateModified\":\"2026-05-20T19:44:58.955Z\",\"publisher\":{\"@id\":\"https://docs.kontext.so/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.kontext.so#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Kontext Documentation\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Kontext Documentation\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/sdk/kotlin/guides.md","siteName":"Kontext Documentation","nav":{"global":null,"languages":[{"language":"en","tabs":[{"tab":"Conversational Ads","groups":[{"group":"Get Started","pages":[{"title":"Overview","href":"/overview"},{"title":"Advertisers","href":"/advertisers"},{"title":"Publishers","href":"/publishers"}]},{"group":"Concepts","pages":[{"title":"How it works","href":"/concepts/how-it-works"},{"title":"Session lifecycle","href":"/concepts/session"},{"title":"IDs and tokens","href":"/concepts/ids-and-tokens"},{"title":"Messages","href":"/concepts/messages"},{"title":"Displaying ads","href":"/concepts/displaying-ads"},{"title":"Ad formats","href":"/concepts/ad-formats"},{"title":"Ad engine","href":"/concepts/ad-engine"},{"title":"Ad lifecycle events","href":"/concepts/events"},{"title":"Pacing","href":"/concepts/pacing"}]},{"group":"Guides","pages":[{"title":"Testing","href":"/guides/testing"},{"title":"Debugging","href":"/guides/debugging"},{"title":"IFA \u0026 ATT","href":"/guides/ifa"},{"title":"SKAdNetwork","href":"/guides/skadnetwork"},{"title":"ads.txt \u0026 app-ads.txt","href":"/guides/ads-txt"},{"title":"TCF \u0026 CMP","href":"/guides/tcf-cmp"},{"title":"Advertiser pixel","href":"/guides/advertiser-pixel"},{"title":"Best practices","href":"/guides/best-practices"}]},{"group":"SDKs","pages":[{"group":"Swift SDK","pages":[{"title":"Swift SDK","sidebarTitle":"Overview","href":"/sdk/swift"},{"title":"Installation","href":"/sdk/swift/installation"},{"title":"Showing your first ad","href":"/sdk/swift/first-ad"},{"title":"API reference","href":"/sdk/swift/api"},{"title":"Guides","href":"/sdk/swift/guides"},{"title":"Example app","href":"/sdk/swift/example"}]},{"group":"Kotlin SDK","pages":[{"title":"Kotlin SDK","sidebarTitle":"Overview","href":"/sdk/kotlin"},{"title":"Installation","href":"/sdk/kotlin/installation"},{"title":"Showing your first ad","href":"/sdk/kotlin/first-ad"},{"title":"API reference","description":"Every type and method exposed by the Kotlin SDK.","href":"/sdk/kotlin/api"},{"title":"Guides","href":"/sdk/kotlin/guides"},{"title":"Example app","description":"Run the bundled Compose demo against your own publisher token.","href":"/sdk/kotlin/example"}]},{"title":"Flutter SDK","href":"/sdk/flutter"},{"title":"React Native SDK","href":"/sdk/react-native"},{"title":"React SDK","href":"/sdk/react"},{"group":"Vue SDK","pages":[{"title":"Vue SDK","sidebarTitle":"Overview","href":"/sdk/vue"},{"title":"Installation","href":"/sdk/vue/installation"},{"title":"Showing your first ad","href":"/sdk/vue/first-ad"},{"title":"API reference","href":"/sdk/vue/api"},{"title":"Guides","href":"/sdk/vue/guides"},{"title":"Example app","href":"/sdk/vue/example"}]},{"group":"JavaScript SDK","pages":[{"title":"JavaScript SDK","sidebarTitle":"Overview","href":"/sdk/js"},{"title":"Installation","href":"/sdk/js/installation"},{"title":"Showing your first ad","href":"/sdk/js/first-ad"},{"title":"API reference","href":"/sdk/js/api"},{"title":"Guides","href":"/sdk/js/guides"},{"title":"Example app","href":"/sdk/js/example"}]}]},{"group":"Resources","pages":[{"title":"Changelog","href":"/resources/changelog"},{"title":"Demos","href":"/resources/demos"},{"title":"Compliance","href":"/resources/compliance"},{"title":"Subprocessors","href":"/resources/subprocessors"},{"title":"Support","href":"/resources/support"}]}]},{"tab":"Video Ads","pages":[{"title":"Video Ads","href":"/video/overview"}]}]},{"language":"zh","pages":[{"title":"zh","href":"/zh/sdk/kotlin/guides"}]}]},"basePath":"","title":"Guides - Kontext Documentation","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}