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 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.
5. 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.
Device-specific identifier (IDFA on iOS, GAID on Android).
Vendor identifier (IDFV on iOS).
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 Supported events for more details.
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
Controlling when ads load
You can fine-tune ad frequency by controlling when new messages are passed to theAdsProvider.
This lets you dynamically adjust the ratio of ads to chat messages.
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.