喜马拉雅车载 SDK 账户互通对接实现

本页讲怎么落地对接喜马拉雅车载 SDK 的「账户互通」(账号绑定 / 同登同退)。它与标准 OIDC/OAuth2 的差距、风险与改造建议,单独成文:喜马拉雅账户互通:与 OIDC/OAuth2 标准的差距。

依据喜马拉雅《车载 SDK 文档》→「账户」→「账户互通」(最低版本 1.0.6.0)。

这是什么

车机端 / TSP 服务端接入喜马拉雅 SDK,用车机自己的用户体系打通喜马拉雅账户:

绑定 / 同登:车机用户一键登录到喜马拉雅账户;
解绑 / 同退:车机退出时同步退出喜马拉雅。

核心是:通过车机的用户信息,在喜马拉雅侧完成双方账户绑定,从而用车机端用户信息登录喜马账户。

准备工作(向喜马申请)

thirdAppId —— 账户互通的客户标识。申请邮箱 [email protected]:
- 同品牌多车型要互通 → 各车型共用同一个 thirdAppId;
- 车型间账号独立 → 申请各自独立的 thirdAppId(可分别提供测试 / 正式的验证接口 URL)。
第三方账户信息验证接口(公网可访问) —— 由你方实现,喜马云端回调它校验用户合法性并拿回第三方 uid 用于绑定。见下文第三方账户信息验证接口。

接入流程

绑定 / 同登

车机用户中心            车机端 APK                喜马 SDK / 云端
   │  触发绑定/同登          │                          │
   │ ─────────────────────► │  ① 查询是否已与喜马绑定    │
   │                        │ ───────────────────────► │
   │                        │  已绑定 → SDK 已登录,同登成功
   │                        │  未绑定 ↓                 │
   │                        │  ② 调 SDK 扫码登录喜马账户 │
   │                        │  ③ 登录后调 bind 接口绑定  │
   │                        │ ───────────────────────► │
   │                        │  ④ 收到绑定成功           │
   │  ⑤ 同步 TSP 绑定状态 ◄─ │                          │

车机已登录状态下,由车机用户中心触发,跳到车机端应用界面,先查询是否已与喜马绑定;
已绑定 → 喜马 SDK 已处于登录态,同登成功;
未绑定 → 车机 APK 调用喜马 SDK 的扫码登录能力登录喜马账户(接口见喜马 SDK 文档「用户 → 二维码登录」);
扫码登录后,车机 APK 调 bindThirdAccount 绑定;
收到绑定成功通知后,车机 APK 同步 TSP 服务端。

解绑 / 同退

同退:直接调喜马 SDK 的退出登录接口即可;
解绑:带第三方账户信息调 unbindThirdAccount,喜马云端完成第三方账户信息验证后解绑;
解绑后,车机 APK 同步解绑关系到 TSP 服务端。

SDK 端接口(Android · `IXmCarAdvanceAPI`)

四个方法签名一致,均为 (String thirdAppId, String body, ResultReceiver callback):

方法	作用
`loginByThird(thirdAppId, body, cb)`	用第三方账户信息登录(已绑定则成功;未绑定失败,需走扫码流程)
`bindThirdAccount(thirdAppId, body, cb)`	账户绑定
`unbindThirdAccount(thirdAppId, body, cb)`	账户解绑
`getThirdAccountBoundState(thirdAppId, body, cb)`	查询第三方账号绑定状态

入参

字段	说明
`thirdAppId`	账户互通客户标识,向喜马申请
`body`	调用第三方账号接口的入参报文(JSON),喜马回调你方验证接口时原样透传

回调返回值(ResultReceiver 的 Bundle)

KEY	类型	说明
`XmConstants.EXTRA_ERR_CODE`	Int	成功 `CODE_SUCCESS`;失败 `CODE_REMOTE_ERROR`(`loginByThird`/`bind` 中"未绑定"也返回 `CODE_REMOTE_ERROR`)
`XmConstants.EXTRA_ERR_MSG`	String	异常原因
`XmConstants.EXTRA_DATA`	Bundle	详细信息(含下表);`getThirdAccountBoundState` 操作成功时无论是否绑定都会返回

EXTRA_DATA Bundle 内字段:

字段	说明
`thirdUid`	第三方 UID(查询接口下未绑定为 null)
`ximaUid`	喜马拉雅 UID(查询接口下未绑定为 null)

第三方账户信息验证接口(你方实现)

喜马云端会用绑定/解绑等接口里传入的 body 回调此接口来校验用户。

方法:POST,application/json
URL:http(s)://合作方域名/合作方path
入参:即各 SDK 接口传入的 body(喜马原样透传)
返回:

成功:

{ "code": 200, "third_uid": "xxxxx" }

失败:

{ "code": 500, "msg": "该用户不存在", "third_uid": null }

返回字段	类型	必须	说明
`code`	int	是	成功 200,其他 500
`third_uid`	String	否	第三方 uid(或 openID);报错 / 不存在可不填
`msg`	String	否	报错原因,`code=500` 时需要

安全提示

文档未定义任何签名 / 加密 / 来源认证,喜马通过公网 HTTP(S) 调你方接口且只透传 body。务必自行在 body 里带签名 + 时间戳(如 HMAC + 防重放)并强制 HTTPS,否则接口在公网裸奔。这一点及其它与标准的差距详见标准差距评价。