账号体系

关于文中出现的名词的含义，请参考名词解释，本文档中名词一般格式为：名词。

理解小雅OS账号体系

接入小雅OS，访问NLU、ASR、TTS等用户级接口前，应先登录到小雅OS，以登录后的身份访问小雅OS的其他接口。 一旦登录，或主动创建一个账号后，就会产生一个小雅OS账号。

小雅OS账号与其他账号的关系如下：

• 关系 1 - 接入方账号与小雅OS账号

请先理解：账号体系-ptfid概念

在同一个ptfId下，每个接入方账号都会生成一个独立的小雅OS账号。

一般情况下，如果接入方账号使用开放平台账号登录(例如使用喜马拉雅账号登录)时，那么不同的appKey(有的开放平台叫app_id/client_id等)，配置不同的ptfId，同一个用户登录也会导致产生不同的小雅OS账号。

接入方账号与小雅OS账号的关联方式请见：设备端登录模式、服务端登录模式

• 关系 2 - 设备与小雅OS账号

每个设备上，同时仅可登录一个小雅OS账号。设备的标识为：sn。在小雅OS账号在设备上登录后，在伴侣APP上可以控制设备的一些行为，例如：播放音频、暂停、显示当前对话的内容等。

对于无屏设备，还可以通过伴侣的配网功能帮助无屏设备连网，并登录同伴侣APP上已经登录的小雅OS账号。

• 关系 3 - 技能账号与小雅OS账号

用户在同技能交互时，在某些情况下需要登录技能。例如，A用户登录了他购买的小M音箱(使用小M公司账号，小雅OS账号为A1)，然后收听了喜马拉雅FM(需要登录喜马拉雅账号，登录技能账号为SA1)，又收听了酷我音乐(登录登录QQ账号，登录技能账号为SA2)。

一个小雅OS账号在一个技能上可以登录一个技能账号。同时又有以下规则：

• 多个技能可以使用同一个账号体系(ptfId)，这样登录其中一个，另外几个技能均登录成功。
• 技能账号仅与小雅OS账号关联，如果小雅OS账号不同，则技能账号不互通。
• 如果接入方账号和技能账号所属的ptfId相同，或使用了同样的domain name，那么这个技能无法退出，并共享接入方账号登录信息。
• 技能开发者在接入账号时，必须使用自有账号体系。

通过这些规则，作为设备开发者您可以：

1. 为设备开发智能家居控制技能，且在设备登录了自有账号体系后，技能不需要再登录直接可用。
2. 使用喜马拉雅账号登录您的设备，则所有喜马拉雅开发的技能均不需要再次登录即可使用(见喜马拉雅账号)。
3. 在不同的设备上，用同样的账号登录同样的技能，则播放进度、收藏记录等均可在设备间同步。
4. 同一个小雅OS账号在一个设备上登录了技能后，再登录另一台设备则不需要重新登录相同技能，两台设备的技能登录状态同步退出和登录。

技能登录方式请见：技能登录

喜马拉雅账号

注意：喜马拉雅账号不是小雅OS账号

• 喜马拉雅账号用于登录设备时，是作为接入方账号，每个喜马拉雅账号在同一个ptfId下对应一个小雅OS账号。此时喜马拉雅相关技能也会处于登录状态，无法退出。
• 喜马拉雅账号用于登录技能时，是作为技能账号，播放进度只跟技能账号有关。

设备端登录模式

设备端有三种登录模式，分别是：

1. credential模式 - 适用于开发者有自己的账号系统
2. 喜马拉雅账号模式 - 适用于开发者使用喜马拉雅开放平台账号登录设备
3. 设备SN模式 - 适用于开发者没有自己的账号系统，设备开机即用，且不考虑跨设备同步登录技能。

所有模式登录的用户标识，均为osAccessToken，后续所有以用户身份访问的接口，均需要传递此参数。

Credential模式

接入方需要实现credential登录回调接口，并将相应的URL配置到小雅OS开放平台。用户的登录过程完全由开发者实现，登录完成后，通过设备端相关登录接口进行登录。

credential登录接口：

设备端：

• API
• C SDK
• C++ SDK
• Android SDK
• iOS SDK

伴侣端:

• Android SDK
• iOS SDK

开发者需要实现的小雅OS回调接口：

• 登录回调接口

喜马拉雅账号模式

使用喜马拉雅账号登录设备，与喜马拉雅技能交互则不再需要登录。登录流程如下：

要使用喜马拉雅账号登录，请先在喜马拉雅开放平台申请账户，并创建一个移动应用或网页应用。 在应用的开发配置编辑页面中的oauth2授权回调地址中，填写由小雅开放平台中生成的信息：

然后将申请到的app_key和app_secret配置在小雅OS硬件开放平台-产品配置-配置服务。

开发者通过SDK或API等方式进行喜马拉雅OAuth2登录，得到accessToken后使用第三方登录接口换取小雅OS的osAccessToken即可完成登录。

第三方登录接口：

设备端：

• API
• [C SDK](不支持)
• [C++ SDK](不支持)
• [Android SDK](暂不支持)
• [iOS SDK](暂不支持)

伴侣端:

• Android SDK
• iOS SDK

设备SN模式

使用SN模式登录，用户完全无感知登录过程，即设备开机即可访问服务。但此模式也导致无法跨设备同步登录技能登录等缺点，不推荐此模式。

为保障您的设备SN不被盗用，您需预先将设备SN列表上传到小雅OS开放平台，设备SN必须上报才可登录。

SN登录模式需要同时上传XN用于校验SN的有效性。您上传了SN后即可下载相应的SN/XN对应关系文件，生产设备时将SN与XN一道烧入Flash中。如下图：

SN登录接口：

设备端：

• API
• [C SDK](不支持)
• [C++ SDK](不支持)
• [Android SDK](暂不支持)
• [iOS SDK](暂不支持)

伴侣端:

• [Android SDK](暂不支持)
• [iOS SDK](暂不支持)

---

服务端登录模式

服务端登录模式和客户端不同，客户端是以用户身份进行登录，而服务端是以产品身份进行登录。

以用户身份登录，所访问资源仅限于当前用户权限；而以产品身份进行登录，则此产品下所有用户的资源均可访问，并可访问创建用户等其他管理型接口。

接口请求的过程为：

步骤详解：

1. 您的程序本地判断，是否有缓存的osAccessToken，没有则走2。
2. 访问/serv/account/os-access-token接口获取osAccessToken。
3. 判断当前登录是否已经有了小雅OS用户标识osOpenId，没有则走4。
4. 访问/serv/user接口创建用户。

打通喜马拉雅账号

使用自有账号体系或SN登录小雅OS

可以使用技能登录的方式引导用户登录喜马拉雅账号。

使用喜马拉雅账号登录小雅OS

创建用户时，所使用的ptfId参数指的是喜马拉雅账号体系，则可以直接打通喜马拉雅账号登录相应的喜马拉雅技能。

根据/serv/user接口描述，关键参数openId/accessToken是由接入方账号体系提供的用户标识。要打通喜马拉雅账号，您需要：

1. 到喜马拉雅开放平台申请app_key和app_secret(过程参考：喜马拉雅账号模式)。
2. 集成喜马拉雅SDK，或通过集成API，并按说明集成登录过程。
3. 在用户选择登录技能后，将得到的openId和accessToken发送到您的服务器。
4. 使用这组数据创建一个用户(接口：/serv/user)，并绑定osOpenId和openId的对应关系。

此时，您使用此osOpenId访问小雅OS中喜马拉雅相关技能时，即处于登录状态。

---

技能登录

小雅OS支持两种技能登录触发条件，并提供三种技能登录模式，设备开发者根据设备的情况进行支持(推荐支持)。

技能登录触发条件：

1. 语音对话过程中，涉及到需要登录才可访问的资源时，例如付费音乐，在技能返回中包含需要登录的信息。
2. 技能详情接口返回登录状态及登录信息。

技能登录模式：

• 二维码登录
• H5登录
• APP跳转登录(未开放)

注：使用喜马拉雅账号登录设备时，喜马拉雅技能无法退出登录并始终处于登录状态。

技能登录触发条件 - 语音对话技能返回

对话过程中，技能可能要求登录才可继续提供服务。在技能返回值中要求登录时，针对不同类型的设备将需要采取不同的交互模式。以下为建议的几类交互模式：

• 无屏设备，同时没有伴侣APP。

直接播放TTS，例如："哎呀，这个故事我找不到了，换一个试试吧。"。

• 无屏设备或有屏无键盘设备，有伴侣APP。

通过您的推送通道，将登录信息推送到伴侣APP，然后播放提示TTS，例如："请打开您的小雅APP，登录之后继续听吧。"。

伴侣APP收到推送后，显示在通知栏、信息中心等处，用户点击即可登录。

• 有屏有键盘设备，无伴侣APP。

直接显示登录页面，用户输入账号密码后登录成功。

需要登录的技能，按照以下方式返回:

• 设备端 API
• 服务 API

技能登录触发条件 - 技能详情接口

一般情况下，用户在伴侣APP上打开技能详情页面时，通过技能详情接口得到登录信息。

获取技能详情：

• API
• Android伴侣 SDK
• iOS伴侣 SDK

得到的登录信息数据结构：

• SkillLoginDetail

技能登录模式 - 二维码登录

1. 客户端根据接口返回的二维码url地址，本地生成二维码。
2. 客户端根据接口返回的二维码ID - qrId，轮询调用二维码授权技能登录接口。
3. 在二维码有效期内，通过技能授权的APP扫描客户端生成的二维码并授权(例如：喜马拉雅技能即用喜马拉雅APP扫码授权)。
4. 二维码授权登录接口返回成功，登录完成。

技能登录模式 - H5

1. 客户端上设定要捕获的URL，用于关闭稍候打开的WebView页面，此URL称为closingUrl
2. 拼接URL：finalUrl={$SkillLoginDetail.h5.loginPage}&closingUrl={$closingUrl}
3. 跳转到finalUrl
4. 用户进行登录或取消
5. 跳转回closingUrl
6. 关闭WebView页

示例：

// 1. 设定closingUrl
final String closingUrl = "app://skill/oncomplete";

/**
 * Android WebView页所在的Activity
 */
// Activity rootActivity = null;

/**
 * 技能详情接口获取到的登录信息
 */
// SkillLoginDetail loginDetail = null;

webView.setWebViewClient(
  @Override
  public void onPageStart(WebView webView, String url, Bitmap favicon) {
    super.onPageStart(webView, url, favicon);
    if(url.startsWith(closingUrl)){
      rootActivity.finish();
    }
  }
  // ...
);

String finalUrl = loginDetail.h5.loginPage + "&closingUrl=" + UrlEncoder.encode(closingUrl, "UTF-8");

webView.load(finalUrl);

样式示例：

---

名词解释

账号体系 - PtfId

小雅OS账号系统核心概念，用于区分小雅OS映射的接入方账号体系。

辅助理解:

• 小美音箱使用美的账号登录，而小雅音箱使用喜马拉雅账号登录，它们使用不同的ptfId，生成了独立的小雅OS账号。
• 小雅Nano和小雅Nano测试版，都使用喜马拉雅账号登录，但创建了不同的ptfId，所以账号并不互通，生成了独立的小雅O 账号。
• 小雅Nano和晓雅Mini，都使用喜马拉雅账号登录，使用相同的ptfId，同一个用户则只有一个小雅OS账号。

同一个小雅OS账号表示：在不同设备上如果登录了同样的小雅OS账号，只要一台设备上登录了某个技能，其他所有设备都同步可以使用。

创建账号体系是在小雅OS硬件开放平台-产品配置-配置服务 中配置。

客户 - Client

指对接小雅OS的设备生产方，即使用小雅OS服务的B端客户，在小雅OS开放平台上注册一个账号，即成为一个客户。

产品 - Product

指由客户开发的硬件产品(云云对接模式下，客户服务器也可当成虚拟的硬件产品)。

产品是接入小雅OS的主体，由客户在小雅OS开放平台上创建，唯一标识为productId。

设备 - Device

每类产品，可以生产多款设备，唯一标识为deviceId(手机端)/sn(其他)

接入方账号 - ThirdUser

接入方即是设备开发者，接入方账号是由开发者提供的账号体系。

包含以下几种类型：

• SN

客户不需要建立服务器，每个设备的sn可作为一个接入方账号，其唯一标识为sn。

• 自有账号

客户有自己的账号系统，以百度为例，其一组账号名密码，即是一个接入方账号，其唯一标识一般为userId。

• 开放平台账号

客户不直接使用自己的账号系统，而是在外部开放平台注册了一个开发者，使用外部开放平台登录自己的应用或设备；每个开放平台账号登录，即是一个接入方账号，其唯一标识一般为openId。

小雅OS账号 - xyUser

指小雅OS账号体系的账号。

小雅OS账号可以登录到多款设备上，即使设备的productId不相同，每个小雅OS账号可以关联登录多个技能，每个技能可登录一个技能账号。

技能账号 - skillUser

天气查询、喜马拉雅儿歌，是两个技能，技能是在对话过程中，提供一个服务的主体。

对于喜马拉雅儿歌来说，某些资源需要登录后才可以收听。用户使用喜马拉雅账号登录后，即与技能和小雅OS用户关联，被称为技能账号。

小雅OS访问令牌 - OsAccessToken

客户端接入时，osAccessToken代表用户登录信息，用于访问客户端接口时鉴权及身份识别。

服务端接入时，osAccessToken代表产品级别登录信息，用于访问服务端接入时鉴权及身份识别。

账号OpenId - OsOpenId

在服务端接入时，要表示一个小雅OS账号，使用osOpenId，由服务端注册账号接口返回，永久有效。