Skip to main content
我们正在准备 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:
安装依赖:
请确认项目满足上方列出的 Android min/compile SDK 与 iOS/Xcode 要求。若遇到问题,请核对插件的平台要求:https://inappwebview.dev/docs/intro/

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 权限,无需运行时弹窗。
完整设置见 IFA 与 ATT——必填 key、弹窗时机的坑,以及如何自己管理弹窗。

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 属性

String
必填
你的 publisher token。
List<Message>
必填
用户和助手之间的消息列表。
String
必填
在用户整个生命周期内保持不变的唯一标识(用于再营销与奖励广告)。
String
用户邮箱。
String
必填
对话的唯一 ID。
List<String>
必填
本次对话启用的 placement code。例如:['inlineAd']。
Character
必填
对话中使用的 character 对象。
Regulatory
合规相关信息。如果你的应用集成了兼容 TCF 的 CMP(Consent Management Platform),SDK 会自动处理 TCF(透明度与同意框架) 信号(gdpr 与 gdprConsent)——你无需手动设置这两个字段。
String
发布方提供的用户分群标识(用于 A/B 测试)。
Map<String, dynamic>
用于把发布方自有信息透传给 Kontext。
bool
是否禁用广告的标志位。
void Function(AdEvent event)
事件发生时的回调。详见下方的 AdEvent 类型章节。
Widget
必填
被 AdsProvider 包裹的 widget 子树。

InlineAd 属性

String
必填
用于标识所展示广告的格式 code。
String
必填
本广告所关联消息的唯一标识。

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。

链接