当前属于邀请内测阶段，个人认证的开发者账号需要申请加入白名单才能接入 APP应用开发，企业认证的开发者账号不需要申请白名单，推荐APP开发者使用企业认证的开发者账号。如果您想成白名单开发者，请加入我们的开发者钉钉交流群（31630820）申请。

一、开发前准备

1 设计规范

UI 规范请参考天猫精灵CC应用接入设计规范.zip。请重点关注字号、间距这些规范。如有疑问，请联系精灵支持人员或精灵设计师沟通。

2 测试设备获取

可以在天猫精灵旗舰店购买开发测试设备，定制机接入可以联系对接的同学获取。

设备类型为带屏设备。开发者除了屏幕尺寸（用来做屏幕适配）外，不需要关注不同型号设备的其他方面。目前市场上天猫精灵带屏设备有两种屏幕尺寸。7寸屏系列：分辨率 1024x600px，10寸屏系列：分辨率 1280x800px。

3 打开USB口

把设备反面的电源口上的封条撬开，露出 USB 口。

打开前：

打开后：

4 APK需要确认的问题

为了避免出现 APK 安装之后，mic 无法收音的问题。请提前确认以下几点：

采样率 48K。设备后续都将支持 48K 采样率收音
双声道
精灵设备只有一个 camera，ID 是 0，和手机有些区别。
PS: 摄像头 ID 跟数量有关，一般手机有 2 个摄像头，后摄主摄像头是 0，前摄是 1。

二、语音能力接入

接入了天猫精灵语音能力之后，语音指令的传输路径简单理解：

天猫精灵负责 ASR（语音转文字），NLU（自然语音理解），处理之后以意图的形式输出给到开发者
开发者根据拿到的结果进行具体业务逻辑的处理，将结果在 APK 上进行展示
同时可以调用天猫精灵 TTS 的能力对用户发起对话

整个语音接入基本分为4个步骤

创建APP类型智能应用
配置语音交互模型
APK端上集成语音SDK
APK验收

1 创建APP类型智能应用

1.1 登录

点此进入 智能应用平台 登录页，输入您的淘宝账户进行登录，登录后会自动跳转至智能应用控制台。
PS：淘宝子账户暂不支持，淘宝子账号除了电商，很多业务是不支持的，天猫精灵app也不行。

1.2 新建APP类型智能应用

1.3 信息填写

应用名称：APP应用的名称，会展示在设备的应用商店中。
应用属性：私有应用是生态设备开发者为自己的用户开发的应用；公有应用是给天猫精灵设备用户开发的应用，公有应用可以选择此应用的使用设备类型：精灵设备（天猫精灵自研设备，如 CC/CCH/CC10）或生态设备（使用天猫精灵语音能力的生态设备）。
应用调用词：也称为 唤醒词，是用户唤起这个 APP应用 所需要说的关键字。如“天猫精灵，抛硬币”，则使用了调用词为“抛硬币”的应用。
应用调起链接：在唤起 APP应用 时，打开 APP应用 对应的设备端 APP 程序；应用调起链接的生成请转至应用启动URI配置
应用标签设置：应用标签是开发者设置的与应用相关的标签。
- 适合屏幕：选择apk中UI支持的屏幕类型
- 适用年龄：能够使用本应用的最低适用年龄，请根据应用的情况合理选择。
- 收费情况：应用可以选择 免费 / 付费 / 应用内购买。
- 交互方式：在触屏交互的基础上，可以选择应用是否还能够 语音 / 手势 交互。
- 场景标签：应用适用的设备有哪些，可以选择 车内 / 随身 / 家里 等场景设备，最多可选三个。
- 类别标签：应用所属的类别，可以选择 社交 / 购物 / 休闲娱乐 / 游戏 等类别，最多可选三个。
- 其他标签：选择应用主要服务的用户类型或场所类型，用户类型有 教师 / 车主 / 男性 / 女性 等，场所类型有医院 / 养老 / 社区 / 聚会 等，最多可选三个。
应用展示设置：可以标识应用是内部还是外部。
APP 展示：如果勾选了不在 APP 中展示，应用上线后用户能够使用此应用，但无法在天猫精灵 APP 的应用广场中搜索到此应用。

当以上应用信息都填写完成后，点击 确认创建 即可创建一个APP应用了。

2 配置语音交互模型

2.1 实体配置

以查询天气的业务为例：查询天气需要提供“城市”才能查询，所以我们需要创建一个城市名称的实体，相当于提供一个词典，让算法模型知道如何去识别用户语句中的城市。关于实体，想了解更多可参考【实体】。

从顶部选择 语音交互模型创建，进入语音交互模型配置页面，点击左侧：实体标签，打开实体配置页面，点击创建实体，填写实体名称和实体标识名：

实体创建.gif

实体名称：要求中文字符，是此实体的中文名，便于开发者在多个实体中快速找到需要的实体。
实体标识名：是实体被意图中参数引用的标识，实体标识名可以使用各种字符。

在实体值部分选择“添加实体”，在输入框输入想要添加的实体值内容。支持多个实体值同时输入(最多20个)，实体值之间要以空格分隔，然后回车键添加实体。

实体值输入.gif

当某条实体值还有其它同义词时，需要将同义词配置到相应的实体后。点击编辑，单击同义词的输入框，逐条输入该实体值的同义词，每输入一条同义词按一次回车完成输入，全部输入后点击保存。
要使实体值的变动立即生效，可以点击右侧的语音交互模型训练，立即对实体值训练，使实体值可用。

同义词输入.gif

查询天气还需要用到日期。平台有提供日期的 公共实体，不需要开发者去创建，直接引用这个公共实体即可。点击 引用公共实体，把 sys.date 实体后的引用按钮打开，返回到实体列表页面可以看到引用的 sys.date 实体。

公共实体引用.gif

2.2 意图配置

意图是为了达成一个目的而产生的，关于意图，想了解更多可参考【意图】。
进入意图菜单，点击 创建意图，输入意图名称、意图标识、意图描述，打开默认意图按钮。点提交创建意图：

意图创建.gif

PS：APP智能应用 默认会生成一个意图，通常情况下，只需对意图进行语料和参数配置即可使用。

创建后点击编辑，先找到到单轮对话表达，这里配置的是我们认为用户查询天气的语句，利用这些语句，算法会进行建模，这样用户说到类似的话时，我们就能识别出他是在询问天气，然后进行相应的处理了。

语料输入.gif

上面的语句中，不少包含了天气查询所需要的日期和城市，我们需要对语句进行标注，告诉算法模型，这些词语可以由标注的实体值动态替换。

鼠标选中我们需要标注的部分，页面上会自动弹出支持标注的实体。如 “杭州今天天气”这句语料，我们分别标注“杭州”为city，“今天”为sys.date(公共实体)。标注后会自动生成参数city和sys.date(公共实体)。

语料标注.gif

平台支持批量标注，当第一次标注后，可以发现所以其他语料中“杭州”词语都被标注了city参数，“今天”词语都被标注了sys.date(公共实体)参数。所以在输入语料时，所有绑定同一个参数的词语都设为相同的，这样就不需要每条语料挨个去标注参数了。

第一次标注后，自动生成的参数如下：
自动生成的参数.png

添加语料的时候，我们也可以选择类型为模板，关键词部分使用 @{参数名称} 占位。
模板语料输入.gif

注意：NLU透传的情况，由于逻辑处理为端上的APP程序，因此，平台无法进行多轮交互，如精灵追问，多轮对话等均无法使用。

2.3 回复逻辑-默认回复逻辑NLU结果透出

APP应用 默认生成了意图和 NLU结果透出 回复逻辑，配置完语料和参数后，平台就能在用户说到相关的语句时识别出用户的意图，并且解析出其中的参数，下发给端上的 APP 触发语音回调。

NLU结果透出字段说明:

属性名	说明
domain	应用名称
query	用户原始语句
intent	意图
slots	属性槽，用来存放领域属性

slots说明

属性名	说明
domainSlot	slot和实体的映射关系
liveTime	slot存在轮数
value	归一化之后的结果
norm	已废弃，请使用value
name	slot名称

3 上传初版APK包

APP 类型智能应用依赖 APK 进行视觉交互，需要上传一个 APK包。上传初版APK安装包是为了获取 APK 的添加语音能力时需要用到的 SecretKey。

@Override
public void getAppContextData(AppContextData appContextData) {
     //此处设置技能的配置信息
     appContextData.setSecretKey("YourSecretKey");  //应用的secretKey
}

注意：初次上传APK后，APK包名 和 Fingerprint 就不允许修改。所以要求初次上传的 APK 证书不能是 debug 版本，需要和正式发布版本的 APK 证书相同。

点击 开发上传APK 页面，在第5步 上传APK包 中上传初版 APK 安装包。
上传APK位置.png

3.1 上传APK包

请选择您自己的 APK包 并上传，上传所需时间取决于您上传时所在网络环境和上传 APK 包大小，请耐心等待。
上传成功.png

3.2 填写APK信息

上传完成后，会展开 apk 信息填写输入框，说明如下：

填写字段	示例值	说明
APK包名	com.zjy.test	APK包Release版本的包名，填写后无法修改，请慎重。
版本号	1.0.0	APK版本
版本Code	3	版本code
Fingerprint	xxxx	APK包Release版本的Fingerprint，填写后无法修改，请慎重。获取方法见附录。

3.3 获取SecretKey

填写好以上信息并提交后，平台会生成 SecretKey 并在页面上展示。

4 配置页面意图

APP 在设备交互时，设备通常处于APP应用的某个页面，要使页面支持语音交互，需要为页面配置页面意图，当用户话术命中意图语料时，触发页面语音交互。

在 语音交互模型创建 页面，点击左侧 配置页面意图，然后点击 新增配置，进入 配置页面执行意图 页面，填写APP代码中的 页面地址（APK中的pageId），勾选需要执行的 页面执行意图，提交保存即可生效。
注意：需要先上传APK包才可以在配置页面意图中新增配置。

apk中在页面启动注册语音回调时设置 pageId，意思是要在当前页面里支持哪些意图的语音指令。代码如下：

@Override
public void getAppContextData(AppContextData appContextData) {
        Log.d(TAG, "before getAppContextData.");
        appContextData.setSecretKey("5b35ceb8-8c18-4c9b-997e-9e252e91d1c4");
        appContextData.setCanExitSkill(true);
        SelectListData selectListData = new SelectListData();
        selectListData.setPageId("/page/play");
        appContextData.setSelectListData(selectListData);
        Log.d(TAG, "after getAppContextData.");
}

如果不设置 pageId 可以开启默认配置，未配置 pageId 的页面默认执行所有意图。

后续可通过 配置页面执行意图 列表，点击详情，查看详细配置信息，如有需要，还可以通过编辑进行修改。

三、APK端上集成语音SDK

1 添加依赖

语音 SDK 可以在 开发上传APK 页面第一步 下载 SDK 和 Demo 中下载。

下载到本地后，就可以添加到项目中。

// 天猫精灵AGIS SDK依赖
 implementation fileTree(dir: 'path/to/libs', includes: ['*.aar'])

2 添加语音能力

动态意图的引入和处理，以及 SDK 中其他语音能力，详见 SDK 使用手册。

private OnASRCommandListener mOnASRCommandListener = new OnASRCommandListener() {
        @Override
        public void onASRStatusUpdated(ASRStatus asrStatus, Bundle bundle) {
        }
        @Override
        public void onASRServiceStatusUpdated(ASRServiceStatus asrServiceStatus) {
        }
        @Override
        public ASRCommandReturn onASRResult(String s, boolean b) {
            return null;
        }
        @Override
        public ASRCommandReturn onNLUResult(String domain, String command, String params, Bundle nlpResult) {
          //TODO: 此处接收语音指令，并做相应的处理。
            return null;
        }
        @Override
        public void getAppContextData(AppContextData appContextData) {
           //此处设置技能的配置信息
            appContextData.setSecretKey("YourSecretKey");  //技能的secretKey
        }
        @Override
        public Bundle getSceneInfo(Bundle bundle) {
            return null;
        }
        @Override
        public Bundle asrToClient(Bundle bundle) {
            return null;
        }
};
public void initAgisSDK(Context context){
        mAsrClient = new ASRClient(context);
        mAsrClient.setBackgroundService(false);//设置常驻服务是否接收语音
        mAsrClient.setOnASRCommandListener(mOnASRCommandListener); //注册语音回调
        mAsrClient.setASRListenerType(OnASRCommandListener.ASRListenerType.DEFAULT_LISTENER);
        mAsrClient.init(context, true); //初始化 AliTVManager
}

建议：一个进程只初始化一个 ASRClient.
DEMO 代码：AGISDemo.zip

3 接收语音回调

当用户在apk页面内说出语音指令时，平台会将NLU的结果下发给设备，触发apk页面的语音回调。页面内接收语音回调的方法是：

@Override
public ASRCommandReturn onNLUResult(String commandDomains, String command, String commandParams, Bundle nlpResult) {
    Log.d(TAG, commandDomains);
    //TODO: 此处接收语音指令，并做相应的处理。
    return null;
}

在语音回调内，apk能够获取用户所说的语音指令内容，平台识别到的意图，以及从语料中抽取到的参数。apk获取到这些信息后，按照用户的语音指令处理业务和切换页面。

四、测试验证

1 在线测试

进入测试页面，可以在输入框输入语句进行测试。可以只输入调用词，就可以访问默认意图；或直接输入调用词+语料，访问指定意图。由于执行逻辑在APP程序控制，因此在线测试只能测试语料能否正确进入意图，效果如下图所示：
NLU透传方式在线测试效果.png

2 真机测试

如果在线测试没有问题，则可以在带屏设备上进行真机测试，验证应用在真机设备上的使用效果。详情参考【真机测试】。

使用真机测试功能，并辅助 APP 的设备对话信息，你可以验证语音识别和交互的真实效果。如果你的唤醒词和例句包含专有名词、生僻词、同音词，可能导致识别结果达不到预期，建议你调整唤醒词和例句为更容易识别的词句。

2.1 绑定真机测试设备

进入真机测试页面，按照页面提示绑定测试的带屏设备。

2.2 获取开发版本系统

绑定带屏设备后，点击 获取开发版本，平台会自动向这个设备推送开发版本的系统，您就可以在开发版本的系统上通过 adb 命令将您的 APK 安装到设备上。

注意：将 UUID 绑定触发推送时，若您的设备系统不是最新版本，请通过设置-设备管理-我的设备-检测新版本，可获得定向推送的系统版本升级。系统升级后，可以自行安装 apk。

2.3 adb 应用安装

电脑安装 adb 环境，用数据线把电脑和设备连接在一起
打开 cmd，使用命令安装 apk adb install [-r] apk包.apk

adb 安装应用失败错误码

在执行 adb shell 命令时，如果提示adb.exe: no devices/emulators found，一般是数据线或 USB 插口问题，请换根数据线或换个 USB 插口试试。
INSTALL_FAILED_INVALID_APK：无效的安装包,安装包已损坏
INSTALL_FAILED_OLDER_SDK：系统版本过低
INSTALL_FAILED_INSUFFICIENT_STORAGE：没有足够的存储空间
INSTALL_FAILED_INVALID_INSTALL_LOCATION：无效的安装位置
INSTALL_CANCELED_BY_USER：系统禁止安装未知来源的应用
INSTALL_PARSE_FAILED_INCONSISTENT_CERTIFICATES：安装包签名不一致
INSTALL_FAILED_INVALID_URI：应用为中文名, adb install 中文.apk时出现此问题。修改为英文名就 OK 了

2.4 应用实际使用效果测试

应用安装后，就可以在设备上通过调用词/调用词+语料 进入 app 应用进行真机测试。
注意: 带屏设备的绑定设备真机测试，需要在音箱的系统设置页面进行真机测试。首页（桌面）无法测试。

五、APK验收

验收标准请参考天猫精灵CC-三方应用接入验收标准_v0.4.xlsx。如有疑问，请联系精灵支持人员沟通。

六、上传最终版APK包

在 APK 开发并测试完成后、应用发布前，需要将最终版 APK 包上传到平台上，并填写 版本号 和 版本Code 。

七、应用发布

当以上步骤都完成后，就可以将此应用提交审核。当审核通过后，您就可以将这个 APP 应用发布到天猫精灵带屏设备上，供带屏天猫精灵用户使用。应用提交审核前需要填写一些信息，部分信息会展示到天猫精灵 APP 应用详情页中，帮助用户了解和使用此应用。详情请参考【首次发布】。

八、附录

1 应用启动 URI 配置

示例如下：

<activity android:name=".MainActivity">
            <!-- 给页面添加scheme启动方式-->
            <intent-filter>
                 <!--该页面的路径配置-->
                <data
                    android:host="com.zjy.test" //包名
                    android:path="/home" //页面路径,路径前要加 /
                    android:scheme="zjy"/> //推荐使用应用简写
                <category android:name="android.intent.category.DEFAULT"/>
                  <category android:name="android.intent.category.BROWSABLE" />
                <action android:name="android.intent.action.VIEW"/>
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
<activity>

还需在uri中添加pkg参数(用于做应用图标过滤)，则上图的完整的应用调起链接为：zjy://com.zjy.test/home?pkg=com.zjy.test

可以先通过命令行测试：

adb shell am start -d "zjy://com.zjy.test/home?pkg=com.zjy.test"

2 应用 icon 规范

天猫精灵CC 应用图标规范.png

3 关于 Fingerprint 的获取

Fingerprint 是由数字和小写字母组成的 Release 签名。示例如下：

 0ddf76f48596df17c2681d3dff9b0fd2a1cf1460

Fingerprint 的获取方式如下：
假定安装了 JDK，如果想查 HelloWorld.apk 所使⽤的签名的 FingerPrint，可以这样做：

解压 APK ⽂件，找到签名的 RSA ⽂件，假设 RSA ⽂件为：META-INF/CERT.RSA
获取签名信息：

keytool -printcert -file META-INF/CERT.RSA

假设获取到的信息如下：

 1. Certificate fingerprints: 
 2. MD5: BC:6D:BD:6E:49:69:2A:57:A8:B8:28:89:04:3B:93:A8
 3. SHA1: 0D:DF:76:F4:85:96:DF:17:C2:68:1D:3D:FF:9B:0F:D2:A1:CF:14:60 
 4. Signature algorithm name: SHA1withRSA 
 5. Version: 3

提取上⾯的 SHA1 值，去掉其中的冒号，并且把所有字⺟转为⼩写，则上⾯的签名的 FingerPrint 为：

 0ddf76f48596df17c2681d3dff9b0fd2a1cf1460

智能应用开放平台

天猫精灵APP接入