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.
We are preparing a new v4 release of the Flutter SDK. The documentation below covers the current shipping version — once v4 lands, this page will be updated.
Flutter SDK
See how easy it is to integrate high-performance ads into your Flutter app using our lightweight SDK.
Requirements
- Flutter: 3.24.0 or later
- Dart: 3.5.0 or later
- Android:
minSdkVersion >= 21,compileSdk >= 34, AGP version>= 7.3.0(use Android Studio - Android Gradle plugin Upgrade Assistant for help), support forandroidx(see AndroidX Migration to migrate an existing app) - iOS:
12.0+, --ios-language swift, Xcode version>= 15.0
Getting started
WebView prerequisites (flutter_inappwebview)
The Flutter SDK renders ads inside a WebView using flutter_inappwebview.
To prevent WebView initialization errors, add this to your app entry point:
1. Installation
To get started, you will need to set up a publisher account to get a
publisherToken and code.pubspec.yaml:
2. Set up the Character object
Define the assistant’s character information:
3. Set up the Regulatory object
Next, define the user’s regulatory context:
4. Set up IFA (Identifier for Advertisers)
- iOS: add
NSUserTrackingUsageDescriptiontoios/Runner/Info.plist. The SDK auto-prompts for ATT and reads IDFA from there. - Android (13+): declare
com.google.android.gms.permission.AD_IDinandroid/app/src/main/AndroidManifest.xml— this is an install-time permission with no runtime prompt.
5. Set up SKAdNetwork (iOS only)
Add the SKAdNetwork identifiers we provide during onboarding toios/Runner/Info.plist. The SDK reads them and forwards them on every /init so DSPs can measure conversions.
See SKAdNetwork for the full guide.
6. Set up the AdsProvider
Wrap your app (or the part of it that contains ad placements) with the AdsProvider.
The AdsProvider is responsible for fetching and managing ads, and it requires access to the current chat messages.
7. Display your first ad
An ad slot is a designated area in your UI where an ad can be rendered. In most cases, it appears below a chat message. During onboarding, you’ll receive a uniquecode for each ad slot you plan to use.
Example using the InlineAd format:
💡 Note:InlineAddoes not always display an ad. Whether an ad is shown depends on the context of the ongoing conversation. If no ad is available,InlineAdautomatically returns aconst SizedBox.shrink(), so it won’t take up any extra space in your layout.
API documentation
AdsProvider properties
Your unique publisher token.
List of messages between the assistant and the user.
Unique identifier that remains the same for the user’s lifetime (used for retargeting and rewarded ads).
Email of the user.
Unique ID of the conversation.
Placement codes enabled for the conversation. Example:
['inlineAd'].The character object used in a conversation.
Regulatory compliance information.TCF (Transparency and Consent Framework) signals —
gdpr and gdprConsent — are handled automatically by the SDK if you have a TCF-compliant CMP (Consent Management Platform) integrated in your app. You do not need to set these manually.Publisher-provided identifier for the user cohort (for A/B testing).
Used to pass publisher-specific information to Kontext.
Flag indicating if the ads are disabled.
Callback triggered when an event occurs. See AdEvent types for more details.
The widget subtree wrapped by
AdsProvider.InlineAd properties
The ad format code that identifies the ad to be displayed.
A unique identifier for the message associated with this ad.
AdEvent types
ad.clicked
The user has clicked the ad.
ad.viewed
The user has viewed the ad.
ad.filled
Ad is available.
ad.no-fill
Ad is not available.
ad.render-started
Triggered before the first token is received.
ad.render-completed
Triggered after the last token is received.
ad.error
Triggered when an error occurs.
reward.granted
Triggered when the user receives a reward.
video.started
Triggered when the video playback starts.
video.completed
Triggered when the video playback finishes.
Guides
Handling no-fill events
You can detect when no ad is available by using theonEvent callback and listening for the ad.no-fill event.
Troubleshooting
Missing plugin warnings
If you see warnings likeMissingPluginException or errors about a plugin not being registered, try the following:
flutter run or restarting your IDE.