跳转到主要内容

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 或更高版本
  • AndroidminSdkVersion >= 21compileSdk >= 34AGP 版本 >= 7.3.0(可使用 Android Studio 的 AGP 升级助手 协助升级),并支持 androidx(如需迁移已有项目,参考 AndroidX Migration
  • iOS12.0+,--ios-language swift,Xcode 版本 >= 15.0

快速开始

WebView 前置条件(flutter_inappwebview

Flutter SDK 使用 flutter_inappwebview 在 WebView 中渲染广告。为避免 WebView 初始化错误,请在应用入口添加:
import 'package:flutter/widgets.dart';

void main() {
  // 必须先调用,确保插件已就绪。
  WidgetsFlutterBinding.ensureInitialized();

  runApp(const MyApp());
}

1. 安装

在开始之前,你需要先建立一个 发布方账号 来获取 publisherTokencode
把包加入你的 pubspec.yaml
dependencies:
  kontext_flutter_sdk: ^<latest_version>
安装依赖:
flutter pub get
请确认项目满足上方列出的 Android min/compile SDK 与 iOS/Xcode 要求。若遇到问题,请核对插件的平台要求:https://inappwebview.dev/docs/intro/

2. 配置 Character 对象

定义助手的角色信息:
final character = Character(
  id: 'id-123',
  name: 'Ava',
  avatarUrl: 'https://example.com/avatar.png',
  greeting: 'Hi there! How can I help you today?'
);

3. 配置 Regulatory 对象

接着定义用户的合规上下文:
final regulatory = Regulatory(
  coppa: 0, 
  // ... 其他合规属性
);

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
import 'package:kontext_flutter_sdk/kontext_flutter_sdk.dart';

// 用户与助手之间的消息
final messages = [
  Message(
    id: 'msg-001',
    role: MessageRole.assistant,
    content: 'Hello! How can I help you today?',
    createdAt: DateTime.parse('2025-08-31T10:00:00Z'),
  ),
  Message(
    id: 'msg-002',
    role: MessageRole.user,
    content: 'Show me today's workout plan.',
    createdAt: DateTime.parse('2025-08-31T10:00:05Z'),
  ),
  Message(
    id: 'msg-003',
    role: MessageRole.assistant,
    content: 'Here's a 30-minute routine to start with.',
    createdAt: DateTime.parse('2025-08-31T10:00:10Z'),
  ),
];

Widget build(BuildContext context) {
  return AdsProvider(
    publisherToken: '<your-publisher-token>',
    userId: 'user-1234',                 
    conversationId: 'conv-5678', 
    enabledPlacementCodes: ['inlineAd'],
    messages: messages,
    character: character,  // 来自第 2 节
    regulatory: regulatory, // 来自第 3 节
    otherParams: {
      'theme': 'dark',
    },
    child: YourChatWidget(),
  );
}

7. 展示你的第一个广告

广告位(ad slot)是 UI 中专门用来渲染广告的区域,通常出现在聊天消息下方。Onboarding 时,你会拿到每个广告位的唯一 code 使用 InlineAd 形式的示例:
ListView.builder(
  itemCount: messages.length,
  itemBuilder: (context, index) {
    final message = messages[index];
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text(message.content),
        InlineAd(
          code: '<your-code>',
          messageId: message.id,
        ),
      ],
    );
  },
)
💡 说明: InlineAd 并不总是会展示广告。是否展示取决于当前对话的上下文。 若没有可用的广告,InlineAd 会自动返回 const SizedBox.shrink(),不会在布局中占用任何额外空间。

API 文档

AdsProvider 属性

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

InlineAd 属性

code
String
必填
用于标识所展示广告的格式 code。
messageId
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 clean
flutter pub get
这会清除构建缓存并确保插件被重新注册。如果问题仍未解决,请尝试 flutter run 重新构建,或重启 IDE。

链接