接入指南

概述简介

SDK V2使用图灵websocket接口，集成了图灵云端的ASR(语音识别)、TTS(在线语音合成)、NLP（语义理解）、绘本识别、语音对话（ASR+NLP+TTS）。

功能结构

结构图如下

集成指南

创建机器人

集成SDK前需要申请APIKey与Secret，请在图灵开放平台注册登录。在机器人管理界面中创建机器人，注意选择接入方式为SDK，创建成功之后可在机器人信息界面获取APIKey与Secret，并联系图灵同事给对应Apikey开通SDK权限。

下载SDK和Demo

可在SDK下载页面下载SDK库和对应Demo。具体内容如下图所示：

sdk_zip_file

Demo：可以直接导入Android Studio运行的Demo；

res：Demo中绘本识别模块-->本地图片识别所需要的图片资源；

SDK：SDK库aar文件，其中包含turingsdk-release、openvideo-release、iqyvideo-release三个aar文件，其中openvideo-release和iqyvideo-release是基于历史V1版本的扩展工具包，主要作用为打开第三方app的工具包，有用到的可以直接替换，没用到的可以忽略；

版本更新记录：SDK版本更新的日志信息。

SDK兼容性

类别	兼容范围
系统	支持Android 4.1 以上版本 API LEVEL 16
支持的ABI	使用VAD和翻页检测功能仅支持armeabi-v7a，不使用则全支持
硬件要求	要求设备上有麦克风
网络	支持移动网络、WIFI等网络环境
开发环境	建议使用最新版本Android Studio 进行开发（SDK开发使用Android Studio 3.2）

建议开发环境：

AndroidStudio 3.5.2
Gradle 4.6
com.android.tools.build:gradle:3.2.0
buildToolsVersion "29.0.2"

Demo运行

第一步：将已经创建好的机器人Apikey和Secert复制到ConfigActivity对应的变量中；

1603437396261

第二步：运行Demo，测试时请直接用真机进行测试。

集成SDK步骤

第一步：添加依赖库

将turingsdk-release.aar复制到您的项目的app/libs/目录下

修改您的项目的app/build.gradle文件，将下面依赖库添加到您的依赖目录中。

implementation(name: 'turingsdk-release', ext: 'aar')
//必须依赖库
implementation 'com.google.code.gson:gson:2.6.2'
implementation "org.java-websocket:Java-WebSocket:1.4.0"
implementation 'androidx.appcompat:appcompat:1.1.0'
//IOT模块 可选依赖库
implementation 'org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.1.0'
implementation 'org.eclipse.paho:org.eclipse.paho.android.service:1.1.1'

备注：当未使用到IOT模块时不需要添加可选依赖库。

第二步：添加用户权限

在工程 AndroidManifest.xml 文件中添加如下权限：

    <!--网络-->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <!--文件读写-->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <!--录音 -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <!--deviceID-->
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <!--MQTT 可选-->
    <uses-permission android:name="android.permission.WAKE_LOCK" />

备注：android 6.0 以上版本权限需动态申请。

若使用到IOT模块，除了增加权限之外，还需要增加MQTT的服务

 <service android:name="org.eclipse.paho.android.service.MqttService" />

第三步：初始化

初始化用于鉴权并获取功能模块的基础参数，具体参考下面初始化的说明。

第四步：创建TuringOSClient

TuringOSClient是SDK提供外部功能的管理类，每个模块的功能调用都需要使用TuringOSClient实例开启，具体使用参考下面创建TuringOSClient说明。

初始化

初始化方法

初始化方法提供传入设备ID和不传入设备ID两种方式

 /**
     * 
     * @param context 应用的Context
     * @param apiKey 图灵开放平台注册的key
     * @param secert 图灵开放平台注册的secert
     * @param sdkInitializerListener
     * 不传入设备ID，默认去mac地址
     */
    public static void init(Context context, String apiKey, String secert, SdkInitializerListener sdkInitializerListener)

    /**
     * 
     * @param deviceID 用户设备的唯一ID
     * @param context 应用的Context
     * @param apiKey 图灵开放平台注册的key
     * @param secert 图灵开放平台注册的secert
     * @param sdkInitializerListener
     */
    public static void init(String deviceID, Context context, String apiKey,
                            String secert, SdkInitializerListener sdkInitializerListener)

    //调用
    SdkInitializer.init(deviceID, context, apiKey, secert, sdkInitializerListener);

参数说明

参数	类型	是否必须	说明
context	Context	是	应用的Context
turingApiKey	String	是	图灵授权的apikey
turingSecret	String	是	图灵授权的secret
deviceID	String	否	设备ID 默认取设备的mac地址
sdkInitializerListener	SdkInitializerListener	是	鉴权回调

设备ID说明

当apikey转入正式环境之后，需要在图灵开放平台提前上传设备ID列表；
设备ID为每一台设备与云端服务建立连接的必须参数，请开发者确保每一台设备输入的deviceID唯一且不会改变；
如果初始化时不传入设备ID，SDK内部会读取设备Mac地址作为设备ID进项初始化，并在初始化成功之后再回调接口中返回相应信息。如果Mac地址读取失败，则整个初始化过程失败；
为了方便管理每一台设备的ID，建议自行获取并备案设备ID，再作为初始化设备ID传入。

初始化结果

SdkInitializerListener接口说明

public interface SdkInitializerListener {
   /**
     * 
     * @param type "custom_id" or "mac" 传入devceID则为custom_id，否则为mac
     * @param userData 具体见UserData说明
     */
    void onSuccess(String type, UserData userData);

    /**
     * 初始化失败回调
     *
     * @param errorCode 错误码,错误码见参照错误码
     * @param errorMsg  鉴权失败信息
     */
    void onError(int errorCode, String errorMsg);
}

返回结果说明

type：当直接传入设备ID时，type=custom_id，当没有传入设备ID，默认SDK内部读取时，type=mac

UserData说明

参数	类型	说明
key	String	图灵授权的apikey
secert	String	图灵授权的secret
deviceID	String	设备唯一ID

Manifest.xml配置

初始化也可以使用AndroidManifest.xml配置的方式。

直接传入参数的方式或者Manifest.xml配置的方式任意选一种即可。

步骤一：

在application标签下配置meta-data，示例如下：

<meta-data
    android:name="TURING_APPKEY"
    android:value="图灵授权的APIKEY" />
<meta-data
    android:name="TURING_SECRET"
    android:value="图灵授权的SECRET" />

步骤二：

调用初始化方法，可以选则传入设备ID或者默认SDK去取mac地址两种方式

    //方法说明
    /**
     * 
     * @param context
     * @param sdkInitializerListener
     */
    public static void init(Context context, SdkInitializerListener sdkInitializerListener)

    /**
     * 
     * @param deviceID
     * @param context
     * @param sdkInitializerListener
     */
    public static void init(String deviceID, Context context, SdkInitializerListener sdkInitializerListener)

打开SDK Debug日志

    /**
     * 
     * @param dubugPath 日志关键文件的保存路径 不能为空，或者不合法的路径
     * @param isDebug 是否打开debug日志，默认为false
     */
    SdkInitializer.setDebug(path, true)

该方法需要在初始化之前，才能看到初始化的日志输出，建议放到初始化SDK之前调用；
path路径：不能为空，或者不合法的路径，主要保存语音识别的录音文件、编码文件，不保存SDK运行日志，SDK的运行日志需要用logcat查看或其他方式保存；
isDebug：当设置改参数为false之后将不会打印任何SDK运行的日志，也不保存语音识别的录音文件。

获取SDK版本号

    SdkInitializer.getVersion();

创建TuringOSClient

TuringOSClient是SDK提供外部功能的管理类，每个模块的功能调用都需要使用TuringOSClient实例开启，TuringOSClient在应用中为单例。

//创建
TuringOSClient turingOSClient = TuringOSClient.getInstance(mContext, userData);

参数说明

参数	类型	说明
mContext	Context	应用的Context
userData	UserData	SDK内部封装的用户信息，SdkInitializerListener中的返回值

使用示例：

//asr调用
TuringOSClient turingOSClient = TuringOSClient.getInstance(this.getApplicationContext(), userData);
turingOSClient.startAsrWithRecorder(asrRequestConfig, new TuringOSClientAsrListener())

语音识别ASR、语音合成TTS、语音聊天、语义理解等模块都使用turingOSClient来调用对应的方法实现功能；
每个模块的具体使用请参考每个模块的文档说明；

SDK输出说明

每个功能接口会返回封装过的BaseResp对象，以及原生json，json字段。

ASR返回示例如下：

{
    "asrResponse":{
        "binarysId":"96fdb319-e34a-4558-bdff-9e83af8fdb6a",
        "state":200,
        "value":"你好"
    },
    "code":200,
    "globalId":"129250722731483001",
    "message":"success"
}

TTS返回示例如下：

{
    "code":200,
    "globalId":"129251386794483001",
    "message":"success",
    "nlpResponse":{
        "intent":{
            "code":50101
        },
        "results":[
            {
                "groupType":0,
                "resultType":"text",
                "values":{
                    "ttsUrl":[
                        "http://turing-iot.oss-cn-beijing.aliyuncs.com/tts/tts-c8162cf54ada46bf883c0c19c8eba0de-292206bba2f14d528ca94ccbce4b3aa7.mp3"
                    ],
                    "text":"明天吃什么？"
                }
            }
        ]
    }
}

简要说明如下：

参数	类型	说明
code	int	请求响应Code，具体可参考Code说明
message	String	请求响应的消息描述
nlpResponse	NlpResponse	当请求语义理解、语音合成、绘本识别时，返回的内容体
asrResponse	AsrResponse	当请求语音识别时返回的内容

BaseResp只负责解析基础字段，包括ASR完整字段，TTS完整字段，NLP语义的基础字段输出；
但是NLP具体内容技能字段和绘本具体内容字段需要根据返回的结果自行实现Java实体对象，然后再次解析Json；
目前SDK Demo中已给大部分技能实体对象的解析示例；

大部分技能公用实体对象SkillParameters：

/**
 * 部分技能字段
 * 儿童聊天(100000) 英文对话(100102) 成语接龙(10005)
 * 知识库(100302) 歌曲点播(200101) 故事点播(200201)
 * 曲艺点播(200201) 十万个为什么(200205) 绕口令(200207)
 * 维基百科(200209) 脑筋急转弯(200211) 顺口溜(200212)
 * 动物叫声(200301) 大自然声音(200302) 乐器声音(200303)
 * 诗词背诵(200401) 拍照(200501) 跳舞(200701)
 * 日期查询(200702) 时间查询(200702) 闹钟(200710)
 * 笑话(201204) 四则运算(201501) 中英互译(201711)
 * 谁在叫(404003) 休眠(900101) 屏幕亮度(900110)
 * 电量查询(900110) 音量控制(900110) 开机提示语(1000010)
 * 主动交互(1000011)
 *
 *
 **/
public class SkillParameters implements Serializable

口语评测技能实体：

英文评测：OralEParameters
中文评测：OralCParameters

天气技能实体WeatherParameters；

绘本技能实体：

2.0协议：BookParameters

其他技能可根据返回的Json自行实现实体类来实现数据的解析。

混淆

-keep class com.iflytek.**{ *;}
-dontwarn com.iflytek.**

-keep class com.turing.**{ *;}
-dontwarn com.turing.**

-keep class org.java_websocket.**{*;}
-dontwarn org.java_websocket.**
-keep class org.slf4j.**{*;}
-dontwarn org.slf4j.**

-keep class org.eclipse.** { *; }
-dontwarn org.eclipse.**

-keep class net.idik.lib.cipher.so.encrypt.**{
    *;
}