客户端 SDK(iOS、Android、React Native)
在自己的应用中加入 GetMyBot 聊天、应用内消息和移动推送,了解身份验证与离线工作。
本页内容
SDK 是供应用开发者接入的程序库,为 iOS、Android 或 React Native 应用加入客服聊天与应用内消息。例如客户在 iOS 应用中提问,客服可在同一 GetMyBot 管理页面回复网站和应用的咨询。下面先介绍功能和项目设置,再说明代码、身份验证和协议。聊天使用机器人的网页渠道,应用内消息使用内容工作台文档。
SDK 能做什么
- 注册安装:首次运行取得长期安装令牌,保存于 Keychain 或 Android Keystore。
- 识别用户:匿名时是一个访客;
identify后与已识别客户合并,并共享其他 GetMyBot 页面中的历史。 - 离线排队:事件、资料属性、输入状态与推送令牌操作先存本地,有网时按序批量送出。
- 聊天:与客服同一对话的历史、发送、附件、未读数和已读游标。
- 实时更新:WebSocket 传送新消息、修改和删除,连接使用一次性票据。
- 应用内内容:展示内容工作台的弹窗文档,并记录展示、动作及转化回执。
- 移动推送:注册令牌供群发与活动使用,实际送达取决于服务器配置和有效令牌。
平台:iOS(Swift,iOS 15+,含 Objective-C 外观层和可选 UI 模块)、Android(Kotlin,minSdk 24,含 Java 外观层)、React Native(基于两个原生 SDK 的 TypeScript)。三者遵守同一协议,并通过同一组参考样例测试。
启用项目
每个机器人在管理页面单独配置 SDK。启用时指定获准接入的应用,取得两个不同的值:
应用列表。 填写 iOS bundle ID 和 Android package name,至少有一个才能创建项目,每份列表最多 64 个。不在列表的应用会得到与未知项目密钥完全相同的响应,不能据此探测有效密钥。
项目密钥形如 sdk1_eu_<24 hex>_<32 hex>,是公开值,会写进应用包,不能用于读取对话或改设置。地域标记供管理页面识别部署区;SDK 原样传递,不自行拆解。
身份密钥不同,永不进入应用。只在启用项目及每次轮换时显示一次,应立刻存入你自己后端的密钥仓库,管理页面和 API 不会再次显示。轮换后旧密钥再有效一天,便于发布服务端更新,不改变项目密钥或已安装设备。
撤销设备。 安装列表显示平台、应用 ID、SDK 版本、语言、时区、是否识别用户和最近活动时间(最多 200 条近期记录)。删除一条会立即撤销该安装的访问权。
安装突增。 新安装注册也会创建访客,使用与网站小组件相同的账户级限制:突增时返回 429 和 Retry-After: 60。已注册设备后续使用自己的令牌,不受此新访客限制;重装或清除密钥存储后重新注册则算新安装。见网站新访客限制。
部署密钥 CUSTOMER_SDK_KEY_SECRET
这是第三种密钥,属于整个 MyBot 部署,而非你的项目。项目密钥由它签名,每次启动 SDK 都会检查签名。
若服务器没有配置 CUSTOMER_SDK_KEY_SECRET,安装注册会像未知密钥一样返回 401,新项目启用返回 503;自己部署或测试部署的管理员必须检查它。轮换部署密钥会使全部已签发项目密钥失效,旧签名不能用新密钥验证,也无法重新签发相同密钥。已有应用会返回 401,只能把新项目密钥放进新应用版本并发布到商店。这是破坏兼容性的操作,不是日常密钥轮换。身份密钥与部署密钥无关;轮换身份密钥的一天重叠期不会影响项目密钥。
安装与启动客户端
SDK 源码在移动仓库 customer-sdk/:Swift 包 MyBotSDK(customer-sdk/ios)、命名空间 dev.gelfand.mybot.sdk 的 Gradle 模块 mybot-sdk(customer-sdk/android),以及 npm 包 @mybot/customer-sdk-react-native(customer-sdk/react-native)。
启动需项目密钥、你的 MyBot 部署基础地址及应用 ID。构建中只设置一个主机,SDK 不会按密钥中的地域自行切换。
let client = try await MyBotClient.start(
configuration: Configuration(
projectKey: "sdk1_eu_…",
baseURL: URL(string: "https://api.getmybot.dev")!,
appIdentifier: "dev.getmybot.example",
sdkVersion: "1.0.0"
)
)
val client = MyBotClient.start(
context,
MyBotConfiguration(
projectKey = "sdk1_eu_…",
baseUrl = "https://api.getmybot.dev",
),
)
const client = await MyBotClient.start({
projectKey: "sdk1_eu_…",
baseURL: "https://api.getmybot.dev",
appIdentifier: "dev.getmybot.example",
});
首次运行注册安装并保存令牌,以后继续同一安装。令牌仅发一次;丢失或怀疑泄漏时 SDK 可原地轮换,身份不变。
身份由你的后端签名,不由设备决定
设备不能自行声明用户身份。identify 接收由你已验证用户的后端使用身份密钥签名的短期 JWT,应用只转交不解析:
- 应用向你自己的后端请求当前用户身份。
- 后端已验证用户后签发 JWT。
- 应用把不透明字符串传给
identify。
服务器严格检查,任何不符都会整体拒绝。有效数据示例:
{
"alg": "HS256",
"project_key": "sdk1_eu_…",
"aud": "mybot-customer-sdk",
"jti": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"iat": 1730000000,
"exp": 1730000120,
"user_id": "acct_10293",
"properties": { "plan": "pro", "role": "admin" }
}
- 算法必须是
HS256,aud必须是mybot-customer-sdk,不能有iss、sub、nbf。 jti是规范 UUIDv4;iat不可晚于当前时间;exp - iat最多 300 秒。user_id是你自己的稳定不透明 ID(1–256 字节),不可用设备表单中输入的原始邮箱或电话。properties可选,最多 16 项,只能从account_id、plan、role、locale中选择,值为最长 256 字节的字符串。
同一用户重复 identify 幂等;换为另一用户时安装转到新用户。原始联系方式不能通过此 API 传递;资料接口和离线队列属性都使用同一封闭字段列表。
退出账户会推进身份时期
多人轮流使用一台手机时,前一人的消息不能以后一个人的身份发送。安装保存当前登录的身份时期,从 1 开始,每次登出加一。服务器每次请求都检查它,立即拒绝旧时期:
- 旧时期尚在队列的操作被丢弃,客户端删除它们,服务器也会整批拒绝。
- 本地序列号从 1 重新开始。
- 当前实时连接立即关闭,登出前发的票据不能再使用。
- 旧时期未完成的发送取消。
- 服务器在同一事务推进时期并撤销旧推送令牌,应用无需额外记忆。
- 清除旧用户的内容分配、未读角标和已存资料属性等缓存。
WebSocket 握手不能像普通 HTTP 请求一样携带身份时期请求头。因此 SDK 先通过 HTTPS 取得一次性票据;兑换时服务器重新从数据库读取安装时期,与票据签发时记录的时期比较。两者之间若已登出,即使票据未使用也不能升级连接。轮换安装令牌不是登出,用户和身份时期不变,也不执行上述清除。
离线队列
无网时记录的操作会按序批量发送。每批带客户端 ID、身份时期和连续序号。
| 操作 | 用途 |
|---|---|
track_event | 记录产品事件;实际名称须符合更严格的 ^[a-z][a-z0-9_.]{0,63}$ |
set_properties | 设置封闭字段 account_id、plan、role、locale |
register_push_token | 加密保存 APNs 或 FCM 令牌,区分 sandbox / production |
revoke_push_token | 撤销令牌,未知令牌也视为成功 |
notification_opened | 尽力记录通知打开 |
in_app_impression、in_app_action | 应用内内容的展示与动作回执 |
typing | 聊天中的输入状态 |
每批 1–100 个操作,序号须紧接上一批已接收的末尾,缺口或重叠会整批拒绝。相同安装和时期中,已接收的批次 ID 重发会返回“重复”,不再次执行,丢失响应后可安全重试。错误时期整批拒绝;其他错误按每个操作返回封闭代码,单个无效属性不影响同批有效事件。
三平台都有相同的本地队列上限:2,000 个操作、序列化数据 2 MiB、最多 7 天,优先淘汰最旧待发操作;正在发送的操作永不淘汰。每次淘汰触发诊断回调,只含本地 ID 和数量/容量/年龄原因,不含内容。失败重试从 30 秒起指数增加至 240 秒,带完全随机抖动;授权拒绝不会重试,因为它是明确拒绝,不是临时故障。
聊天
当网站与应用的关联历史功能可用且已启用时,iOS 和 Android SDK 可以分页读取网站历史及普通附件的元数据,并下载不超过 32 MiB 的文件。下载需要有效的已认证会话;不提供公开文件链接。目前不支持私密转发。历史按页读取;此方式不提供共享实时更新,也不会自动将会话标记为已读。
关联历史区域打开时,网站组件会定期检查应用的新消息,以及已加载消息的编辑和删除。移动应用可以通过显式 SDK 调用检查更新;SDK 不会启动后台轮询。这是定期检查,并非完整的共享实时功能。各渠道的已读状态和通知仍然独立。
在 iOS 上使用 linkedWebHistorySnapshot,在 Android 上使用 getLinkedWebHistorySnapshot 获取初始快照。将 mutationCursor 与 page.nextAfter 分开保存。需要时使用两个游标和最多 500 个已显示消息 ID 调用 linkedWebHistoryUpdates / getLinkedWebHistoryUpdates。如果 hasMutations 为 true,使用 through 重新读取显示范围,保留原有页面边界并处理删除。如果初始页面为空且没有 nextAfter,请将 nil/null 或空字符串作为 after:SDK 会从 0 开始检查。旧服务器可能不返回 mutationCursor;退出登录后应丢弃游标。
要在移动应用中确认消息已显示,请在 iOS 上显式调用 markLinkedWebHistorySeen(messageIds:),或在 Android 上调用 markLinkedWebHistorySeen(messageIds)。最多传入 500 个 ID,且仅限实际显示给访客的员工来信(direction: "in")。关联历史区域打开且可见时,网站组件会自动标记可见消息。这可能取消尚未发送的未读回复备用邮件,但不能撤回已发送的邮件,也不会同步 SDK 聊天的未读计数。
要获取关联网站历史中没有确认查看标记的消息独立计数,应用可在 iOS 上调用 linkedWebUnreadCount(),或在 Android 上调用 getLinkedWebUnreadCount()。该计数包括确认关联后创建且未标记为已查看的员工消息。标记实际显示的消息后,下次结果会相应变化。主 SDK 聊天中的阅读可能不会反映在此计数中,因此它不是精确的未读计数。nil/null 表示服务器不支持该计数,并非零。此计数独立于 SDK 聊天的主要未读计数,不会在后台或通过 push 自动更新;应用自行决定何时请求。
当网站与 SDK 的关联在服务器上可用且已启用时(WEB_SDK_LINK_ENABLED,默认关闭),可以查看两份历史的合并快照。普通聊天仍可使用,操作员看到的会话仍然独立。快照按最新消息优先返回,通过不透明的 nextCursor 分页,并包含安全内容块和普通附件元数据。unsupportedBlocks: true 表示部分内容被省略;不支持私密转发。使用 downloadMergedHistoryAttachment 经授权下载附件。
如需保留合并快照,请在 iOS 使用 versionedMergedWebHistory,在 Android 使用 getVersionedMergedWebHistory。比较各页的 linkVersion,并在重新显示已保存历史之前及恢复应用后,通过 mergedHistoryLinkVersion / getMergedHistoryLinkVersion 显式检查。如果版本变化或无法验证访问权限,请清除已保存的页面、游标和附件;退出登录后它们也会失效。合并视图不提供共享实时功能,不会将消息标记为已查看,也不会启动后台轮询。
合并快照打开且可见时,组件会定期检查变化并提示手动刷新历史。该信号是尽力而为的检查,不是有保证的事件队列或实时功能;操作员会话仍然独立。
在移动应用中,使用 iOS 的 observableMergedWebHistory 或 Android 的 getObservableMergedWebHistory 获取第一页,并保存其中不透明的 updatesBaseline。若该值缺失,服务器不支持此检查。需要时,使用该 baseline 和最多 500 个已显示消息 ID 调用 mergedWebHistoryChanges / getMergedWebHistoryChanges。hasNew 表示有新消息,hasChanged 表示所传 ID 中有编辑或删除;响应不包含消息内容。这些检查尽力而为,可能遗漏并发提交的更改;值为 false 不保证快照是最新的。需要最新数据时请刷新历史。将 linkVersion 与快照比较,若不同或无法验证访问权限,则清除页面、游标和附件。刷新后重新获取第一页及新的 baseline。SDK 不会启动后台轮询。
应用聊天就是手机上的机器人网页渠道:同一消息、同一客服收件箱,发送时触发相同自动化。
- 历史按游标向前分页,每页最多 50 条。
direction以客户端视角表示,in是客服或机器人发来的消息。 - 发送带客户端消息 ID,响应“已入队”只表示接受送达,不表示已送达;真实状态从实时流或后续历史读取。同 ID、同文字重试不重复发送;同 ID、不同文字报冲突,表明应用有错误。
- 附件一次一个文件,最多 10 MiB;在机器人范围内按内容哈希去重,返回可用链接。
- 未读数按每个安装自己的已读游标计,与客服已读分开;游标只前进。
- 实时流传送新消息、修改、删除和输入状态。连接时先补最多 50 帧离线期间的内容,再推送实时事件;客户端没有重连游标。
若机器人未连接网页渠道,所有聊天路由都会说明聊天不可用。应在应用中显示为功能关闭,而非临时错误。
应用内内容
GET /sdk/v1/content 返回已分配的内容项,包括类型、优先级、延迟、访问次数与频率规则、内容块和外观;空列表是正常响应。
是否展示由目标规则决定。若弹窗明确排除移动设备,就不会进入 SDK;未设设备目标表示所有设备,可进入。方案对具体用户确定性分配,匿名用户会反复看到同一方案,直至 identify 或登出重新计算。回执有 impression、action、conversion 三种。访客划掉消息是客户端最终状态,不会创建服务器事件,与网站上关闭弹窗相同。
移动推送令牌
register_push_token 保存当前安装与身份时期的 APNs 或 FCM 令牌,加密存储;revoke_push_token 撤销。未知令牌也成功,以免用响应探测别人是否已注册。安装信息可参与用户数据导出和删除,但令牌本身不导出。
SDK 配置的 pushEnabled: true 表示平台支持移动推送。真正发送仍需部署管理员配置 FCM;配置 APNs 后可直接向 iOS 发送。已发布 Push 文档可通过群发或活动的 mobile_push 渠道发送。管理页面的客服通知使用不同受众与设备存储。
登出时服务器撤销旧身份时期的活跃令牌;重新登录后须为新时期重新注册。仅有活跃安装及有效令牌才可发送。
错误
/sdk/v1 错误都用单字段 JSON 外层结构,SDK 按 HTTP 状态分类:
| 状态 | 含义 | SDK 处理 |
|---|---|---|
400 | 本地输入无效 | 不重试,展示客户端错误 |
401 | 授权拒绝:旧身份时期、已撤销令牌、未知项目、已使用票据 | 不用同一凭据重试 |
404 | 未知或属于别人的内容分配 | 永久删除本地项 |
409 | 机器人聊天不可用或幂等冲突 | 展示,不重试 |
413 | 附件超过 10 MiB | 重试前直接提示 |
500、503 | 临时错误 | 幂等操作稍后重试 |
隐私与诊断
SDK 路由不返回原始联系方式,属性列表全程封闭。诊断默认关闭;启用后只传封闭列表中的事件代码、时间和清理过的数字元数据,绝不传令牌、身份断言、推送令牌、链接或消息、属性、内容正文。SDK 安装归入 sdk_diagnostics 保存类别,默认保留 180 天,与其他客户数据一起参与订阅者合并、导出和删除。
协议
SDK 协议与所有者 REST API分开:个人令牌不适用于 /sdk/v1,安装令牌不适用于 /api。路由 OpenAPI 无需授权即可获取:
GET https://你的部署地址/sdk/openapi.yaml
移动仓库的 customer-sdk/contract/behavior.md 说明客户端状态变化、操作顺序、队列限制、重试延迟和错误处理。旁边有从服务器结构、枚举、限制和模板自动生成的描述,以及 75 个参考测试样例。同步脚本重新读取后端副本的描述并报告未写进协议的变化;iOS、Android、React Native 使用同一批样例检查行为一致。
API 与 MCP
个人令牌可访问项目管理路由,见 REST API。读取需要 customer_sdk:read 作用域和机器人的 customer_sdk.read 权限;写入需要 customer_sdk:write 和 customer_sdk.write,启用项目和轮换密钥还需要 integrations.secrets。MCP 提供两个只读工具,见 MCP。