Flutter 接入

Flutter SDK 通过原生 Android 和 iOS 聊天页提供完整的咨询体验；无需自行实现聊天界面即可打开客服窗口。

接入准备

• Flutter 3.22 及以上、Dart 3.4 至 4.0 以下。
• Android 最低支持 API 23；iOS 最低支持 iOS 13。
• Android 工程需要能获取 99 客服原生 SDK 依赖；iOS 工程需要 CocoaPods 环境。

在 pubspec.yaml 中添加依赖：

dependencies:
  agentvisitor_flutter: ^0.0.1

然后执行：

flutter pub get

配置访客身份

应用登录后，向业务服务端请求当前用户的访客令牌。用户 ID 由业务服务端在访客令牌中确认；客户端配置昵称、头像，以及 attributes（即 visitor.attr 扩展信息）。API 密钥保留在服务端；令牌签发方式请参阅用户基础信息对接。

import 'package:agentvisitor_flutter/agentvisitor_flutter.dart';

await Visitor.configure(
  config: const VisitorConfig(
    baseUrl: 'https://live.99kf.com',
    language: 'zh-CN',
  ),
  auth: VisitorAuth.tokenProvider(() => appApi.fetchVisitorToken()),
  visitor: const VisitorProfile(
    nickname: '张三',
    avatar: 'https://www.99kf.com/avatar/12.jpg',
    attributes: [
      VisitorAttribute(key: 'phone', label: '电话', value: '13800138000'),
      VisitorAttribute(key: 'name', label: '姓名', value: '张三'),
    ],
  ),
);

其中 phone、name 需与客服端的访客字段设置一致。

打开聊天页

await Visitor.openChat(
  const VisitorChatOptions(
    groupId: 0,
    title: '在线客服',
  ),
);

传递业务上下文

支持在打开聊天页时传递当前商品、订单或其他业务资料，让客服能够结合业务信息接待访客：

await Visitor.openChat(
  const VisitorChatOptions(
    groupId: 0,
    contexts: [
      VisitorContext(
        key: 'order:ORDER-1001',
        type: 'order',
        title: '最近订单',
        fields: [
          VisitorContextField(
            key: 'status',
            label: '订单状态',
            value: '待发货',
          ),
        ],
      ),
    ],
  ),
);

字段格式和完整示例请参阅商品和订单对接。

平台权限

Android 需要网络权限；启用拍照、语音或媒体发送时，再按实际能力声明相机、麦克风和媒体读取权限。iOS 需在 Info.plist 中为已启用的相机、麦克风、相册能力补充用途说明。

增值服务

Flutter 接入属于增值服务。如需获取 Flutter SDK 源码包或安排接入支持，请联系我们。