Flutter SDK

一个面向 Respondo 客服聊天的纯 Dart 客户端——没有需要编译或调试的原生平台代码。

环境要求#

Dart >=3.4.0 <4.0.0。
Flutter >=3.16.0 （3.x 系列）。
纯 Dart：无原生桥接，无需 pod install，无需改动 Gradle。传递依赖都是纯 Dart 包（http、web_socket_channel、uuid）。

安装#

从 pub.dev 添加该包：

pubspec.yamlyaml

dependencies:
  respondo_sdk: ^0.1.2

Dartdart

import 'package:respondo_sdk/respondo_sdk.dart';

初始化#

将 Respondo.navigatorKey 绑定到您的 MaterialApp，以便 SDK 无需您的 BuildContext 即可打开聊天面板；调用一次 Respondo.init，然后调用 Respondo.open()。

main.dartdart

import 'package:flutter/material.dart';
import 'package:path_provider/path_provider.dart';
import 'package:respondo_sdk/respondo_sdk.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 文件存储目录来自宿主应用的插件；SDK 本身保持纯净。
  final dir = await getApplicationSupportDirectory();

  await Respondo.init(
    RespondoConfig(
      agentId: '<agent-uuid>',
      channelId: '<channel-uuid>',
      storageDirectory: dir.path,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Respondo.navigatorKey, // 必需，SDK 借此打开聊天
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => Respondo.open(),
            child: const Text('Support'),
          ),
        ),
      ),
    );
  }
}

所有门面方法都是幂等的，可在 init 之前安全调用（会缓冲并重放），且永远不会向您的应用抛出异常。

识别用户#

默认情况下，每位访客都是匿名的。首次启动时，SDK 会生成一个稳定的 visitor_id 并保存在本地存储中，因此回访用户能再次找到自己的对话。无需内嵌任何 API 密钥——每个对话都由后端签发的会话令牌保护，该令牌按每个对话独立生成，并在每条消息时向前滑动，因此匿名访客永远无需重新认证。

在用户登录之后调用一次 identify。这会附加上他们的真实身份，使其历史记录能跨设备、跨重装随之保留，并让他们的姓名和邮箱显示在您收件箱里对话的旁边，而不再是一位匿名访客。

userHash 是 由您的后端根据 agent 的 identity_secret 计算出的签名—— HMAC-SHA256(secret, userId) （当没有 userId 时则用 email），编码为小写十六进制。该密钥用于证明身份的真实性，因此必须只保存在您的后端，绝不能随应用一起分发。完整公式和服务器端示例请参见身份校验页面。

Dartdart

// 1. 向您自己的后端登录，并读取预先计算好的哈希
//    （例如登录响应中一并返回的字段）。
final session = await api.login(email, password);

// 2. 把算好的 userHash 交给 SDK——切勿在应用中计算它。
Respondo.identify(RespondoIdentity(
  userId: session.userId,
  email: session.email,
  name: session.fullName,
  userHash: session.respondoUserHash,
));

// 3. 退出登录时：吊销会话并开启一个全新的匿名访客。
Respondo.reset();

如果哈希缺失或错误，不会抛出任何异常：后端会静默地让访客保持匿名，聊天照常工作，您只是在提供有效哈希之前失去跨设备的关联。仅当 agent 设置了 identity_secret 时才会执行校验—— 在开发阶段将其留空，则 userId / email 会被原样接受。

可观察对象与回调#

一切都以广播 Stream、回调 setter 以及当前值 getter 的形式提供。

Dartdart

// 未读数的响应式流（用于角标）。
Respondo.unreadCountStream.listen((n) => setBadge(n));

// 或者用回调 setter。
Respondo.onUnreadChanged = (n) => setBadge(n);

// 拦截链接/CTA；若宿主已自行打开该 URL 则返回 true。
Respondo.onUrlRequested = (url) {
  openInAppBrowser(url);
  return true;
};

屏幕跟踪#

在每次导航时上报当前屏幕，以便主动式提示和页面级定向能与之匹配。传入 null 可清除它；每次变化时，主动式提示都会针对新屏幕重新评估。

Dartdart

Respondo.setCurrentScreen('pricing');

后续步骤#

添加推送通知和身份校验。完整的 API 接口、互动触达功能以及故障排查，都在 pub.dev 包页面上的 Flutter SDK 上手指南中说明。