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.
我们正在准备 Flutter SDK 的 v4 版本。下方文档对应当前正式版本——一旦 v4 发布,本页会同步更新。
Flutter SDK
看看用我们轻量的 SDK 接入高性能广告有多简单。
环境要求
- Flutter:3.24.0 或更高版本
- Dart:3.5.0 或更高版本
- Android:
minSdkVersion >= 21,compileSdk >= 34,AGP 版本>= 7.3.0(可使用 Android Studio 的 AGP 升级助手 协助升级),并支持androidx(如需迁移已有项目,参考 AndroidX Migration) - iOS:
12.0+,--ios-language swift,Xcode 版本>= 15.0
快速开始
WebView 前置条件(flutter_inappwebview)
Flutter SDK 使用 flutter_inappwebview 在 WebView 中渲染广告。为避免 WebView 初始化错误,请在应用入口添加:
1. 安装
在开始之前,你需要先建立一个 发布方账号 来获取
publisherToken 和 code。pubspec.yaml:
2. 配置 Character 对象
定义助手的角色信息:
3. 配置 Regulatory 对象
接着定义用户的合规上下文:
4. 配置 IFA(广告标识符)
- iOS: 在
ios/Runner/Info.plist中加入NSUserTrackingUsageDescription。SDK 会自动触发 ATT 弹窗并据此读取 IDFA。 - Android(13+): 在
android/app/src/main/AndroidManifest.xml中声明com.google.android.gms.permission.AD_ID——这是 install-time 权限,无需运行时弹窗。
5. 配置 SKAdNetwork(仅 iOS)
请把 onboarding 时提供的 SKAdNetwork 标识符追加到ios/Runner/Info.plist 中。SDK 会读取它们,并在每次 /init 时一并转发,以便 DSP 衡量转化。
完整指南见 SKAdNetwork。
6. 配置 AdsProvider
把你的应用(或其中包含广告位的部分)用 AdsProvider 包裹起来。AdsProvider 负责获取与管理广告,并且必须能访问到当前聊天的 messages。
7. 展示你的第一个广告
广告位(ad slot)是 UI 中专门用来渲染广告的区域,通常出现在聊天消息下方。Onboarding 时,你会拿到每个广告位的唯一code。
使用 InlineAd 形式的示例:
💡 说明:InlineAd并不总是会展示广告。是否展示取决于当前对话的上下文。 若没有可用的广告,InlineAd会自动返回const SizedBox.shrink(),不会在布局中占用任何额外空间。
API 文档
AdsProvider 属性
你的 publisher token。
用户和助手之间的消息列表。
在用户整个生命周期内保持不变的唯一标识(用于再营销与奖励广告)。
用户邮箱。
对话的唯一 ID。
本次对话启用的 placement code。例如:
['inlineAd']。对话中使用的 character 对象。
合规相关信息。如果你的应用集成了兼容 TCF 的 CMP(Consent Management Platform),SDK 会自动处理 TCF(透明度与同意框架) 信号(
gdpr 与 gdprConsent)——你无需手动设置这两个字段。发布方提供的用户分群标识(用于 A/B 测试)。
用于把发布方自有信息透传给 Kontext。
是否禁用广告的标志位。
事件发生时的回调。详见下方的 AdEvent 类型章节。
被
AdsProvider 包裹的 widget 子树。InlineAd 属性
用于标识所展示广告的格式 code。
本广告所关联消息的唯一标识。
AdEvent 类型
ad.clicked
用户点击了广告。
ad.viewed
用户已查看广告。
ad.filled
有可投放的广告。
ad.no-fill
没有可投放的广告。
ad.render-started
在第一个 token 到达之前触发。
ad.render-completed
在最后一个 token 到达之后触发。
ad.error
出现错误时触发。
reward.granted
用户获得奖励时触发。
video.started
视频开始播放时触发。
video.completed
视频播放完成时触发。
实践指南
处理 no-fill 事件
可以通过onEvent 回调并监听 ad.no-fill 事件感知广告何时不可用。
故障排查
提示插件缺失
如果看到MissingPluginException 或某插件未注册的报错,可尝试:
flutter run 重新构建,或重启 IDE。