入口、身份与凭据
公开入口标识和服务端密钥不能混用。
凭据说明
| 名称 | 放在哪里 | 用途 |
|---|---|---|
| baseUrl / key / entryId | 宿主客户端,可公开 | HTTPS 主机、入口公开 key 与入口 ID,不是管理授权 |
| visitor Bearer | SDK 管理的本地会话存储 | 服务端签发,只能访问对应访客范围;不要自行生成 |
| userScope / clientSession | 宿主本地隔离编号 | 隔离本地会话,不是身份认证或客户查询权限 |
| visitorContext | 可选客户资料 | 自述信息,不能证明会员或 openid 身份 |
| API Key | 你自己的服务端环境变量 | 访问明确授权的 /v1/operations 操作,不能放前端 |
| AppSecret / 回调签名密钥 | 服务端渠道配置或验签服务 | 第三方授权与签名,不能放进 SDK 包 |
访客授权与 Cookie
SDK 使用 Authorization: Bearer 访客令牌。显式 Authorization 优先,不能失败后回退其他用户 Cookie。带 x-yunfu-visitor-auth: bearer 的隔离入口忽略共享访客 Cookie;创建会话也不写共享访客 Cookie。普通网页的兼容 Cookie 流程独立保留。
可信身份边界
设置名字、客户 ID、手机号、userScope 或 clientSession 不会认证客户。当前客户端未实现宿主登录态的服务端签名身份交换,不开放基于这些自报字段读取私有 CRM 或跨设备合并历史。
实现依据 · 仓库内路径
lib/channels/visitor-credentials.tslib/channels/hosted-client-session.tsbackend/services/channels/visitor-service.ts
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。