H5-BOT-SDK (v1.9.0)

本文档规范

名词解释

SHOW：小度有屏音箱，
App：手机端的小度App和小度音箱App
SHOW ONLY：说明本方法仅适用SHOW设备，也就是小度有屏音箱设备
App ONLY：说明本方法仅适用小度音箱APP和小度App
1.4+ 说明本方法仅适用SDK 1.4及其以后的版本

GUID

一个H5应用接入到度秘需要哪些步骤？

H5类型技能尚处于内测阶段，需要进入到如下页面（若已激活，此步骤可跳过）激活，激活码: 8ea5dfe6-2b25-83d8-0f0b-8285ab6a7869-19c45ea4-6deb-a02d-fd36-410c8bb75e86。
创建一个技能，https://dueros.baidu.com/dbp/bot/index#/addbot/0，选择“自定义”目录下的"H5技能"，填写相应参数，创建技能。
在你的H5里集成本SDK，详见下方BotApp的引入
如果开发者有登录的需求，账号关联流程详见requireLinkAccount()
如果开发者有支付的需求，详见requireCharge()

H5游戏想要运行在小度App/小度音箱App上？需要如下工作(本渠道已暂停开放)

小度App/小度音箱App上运行的H5游戏需要额外调用以下几个方法才能实现小度有屏音箱上同样的功能：

使用isInApp()来判断当前H5应用的运行环境是否是小度App/小度音箱App；
需要在requireLinkAccount()中传入一个回调函数来获取App上的百度账号的授权结果；
需要在requireCharge()方法中再传入一个回调函数接收购买结果；
通过小度App debug包调试，需要手动输入如下地址调试：http(s)://xiaodu.baidu.com/saiya/sdk/iframe/h5game-wrapper.html?gameUrl=${gameUrl} (gameUrl为encodeURIComponent编码后的地址)。

BotApp的引入

接入益智乐园的H5游戏

如果是接入益智乐园和游戏中心的H5游戏，无需手动引入，小度智能屏已经强制注入了sdk的实例，开发者可通过window.botAppInstance直接获取到 BotApp 实例，后续在该实例上直接调用相关 API 即可

// 使用示例
window.botAppInstance.listen();

普通接入（非益智乐园和游戏中心场景）

通过script标签引入(支持https)

<script src="//duer.bdstatic.com/saiya/sdk/h5-bot-sdk.1.9.0.js"></script>

即可在全局环境下获取到BotApp对象

使用webpack进行打包的模块化的开发形式参考webpack配置文件中的 externals配置

开始使用

// 初始化botApp对象（益智乐园和游戏中心场景无需该步骤）
const botApp = new BotApp({
    random1: '3691308f2a4c2f6983f2880d32e29c84', // 随机字符串，长度不限，由开发者自己生成
    signature1: 'd85f5cfffe5450fe7855fec1fcfe0b16', // 将(random1 + 签名Key)的字符串拼接后做MD5运算得出
    random2: 'dc468c70fb574ebd07287b38d0d0676d', // 随机字符串，长度不限，由开发者自己生成
    signature2: '61dc2b99967e0b326e82e80b05571d22', // 将(random2 + 签名Key)的字符串拼接后做MD5运算得出
    skillID: '699e74f5-b879-1926-1e11-51998f05ea68' // 必填字段，技能ID。填写本字段后SDK会在初始化阶段调用BotApp.requireShipping(小度有屏音箱环境)方法。
});

正式上线时上述随机字符串和签名需要开发者通过后端接口生成。在开发调试阶段可采用如下方式快速生成MD5：
md5 -s "string"
签名Key不能明文暴露，以免造成不必要的风险。签名Key在DBP平台(https:/dueros.baidu.com/dbp)技能的基础信息页面签名必须填写正确，否则技能会在与用户交互时被强制退出

isInApp() 1.4+

判断当前H5运行环境是否是在小度APP或者小度音箱APP中，以此区分有屏音箱端和手机App端。开发者需以此来判断并使用相应的SDK方法。

requireLinkAccount([,callback])

接入度秘的H5应用，如有登录需要，必须和百度的账号体系进行绑定，此接口用来发起账号绑定流程。

1.4+版本以后在小度App/小度音箱App运行环境中支持传入一个回调函数接收授权结果。小度有屏音箱端需要调用getRegisterResult()来获取授权结果。

目前支持2种方案：

沿用百度账号体系oauth的授权流程，开发者需在http://developer.baidu.com/wiki/index.php?title=docs/oauth申请一个新的应用，并将oauth应用的相关信息提供给度秘。绑定成功后，会回调给开发者提供的callback H5地址。后续度秘请求的所有H5和接口回调，都会带上accessToken参数。开发者可以通过accessToken参数请求百度oauth的接口，再换取用户的具体信息。
开发者自己实现标准的oauth协议，并将oauth协议相关接口信息在度秘dbp平台上进行配置。授权成功后可在onLinkAccountSucceeded(callback)的回调函数中获取到accessToken。

建议第三方开发者使用方案1，产品交互相对简单，用户只需要在设备上确认授权，即可自动登录

本方法在小度APP/小度音箱App和小度有屏音箱上都能调起授权。在小度APP/小度音箱App上，开发者需要传入一个回调函数来获取授权结果。小度有屏音箱上，开发者需要使用getRegisterResult()来获取结果。

参数	说明	类型	必填	默认值
callback	只会在小度App/小度音箱App上被调用，参数为授权结果	Function(data: Object)	仅小度/小度音箱 App 中必填	无

callback参数

参数	说明	类型
data	授权结果	Object
data.type	授权结果状态码	enum {"authorized_success", "authorized_fail"}
data.data.accessToken	oauth accessToken	string

示例1(在App中)

botApp.requireLinkAccount(function (data) {
     console.log(data);
     // 注意，本函数仅会在App环境下触发。小度有屏音箱上运行的应用请使用`getRegisterResult()`获取注册结果
     // 打印如下：
    {
        "type":"authorized_success", // 授权被拒绝时的值：authorized_fail
        "data":{
            "accessToken":"28.10b09eb18b9dcc3806vda3920199a6fd.2592000.1575546362.4114435386-16962311"
        }
    }
});

示例2(在SHOW中)

botApp.requireLinkAccount();

onLinkAccountSuccess(callback) `SHOW ONLY`

获取oauth授权结果。此方法会监听oauth授权成功后的结果。

注意：仅当开发者选中上方的第二种授权方案且在有屏音箱上使用时才会触发本函数中的回调

参数	说明	类型	必填	默认值
callback	SDK收到授权成功的通知后会调用此函数	Function(payload: Object)	是	无

callback参数

参数	说明	类型
payload	授权结果	Object
payload.token	标识本次返回，一般没用	string
payload.app.accessToken	第三方平台的授权accessToken（非DuerOS使用的百度access token）	string

示例

botApp.onLinkAccountSuccess(function (payload) {
    console.log(payload);
    // 结果如下：
    {
        app:{
            "accessToken": "{{string}}",
                "apiAccessToken":"{{string}}",
                "syncLocalStorage":"{{boolean}}",
                "userId": "{{string}}",
                "deviceId": "{{string}}",
                "deepUrl":"{{string}}"
        }
    }
})

getRegisterResult(callback)

BotApp SDK初始化之后，SDK内部会进行身份校验、注册等操作，开发者可使用本方法来获取注册结果，如果已经绑定过百度账号，则能获取到授权后的 oauth access token。

参数	说明	类型	必填	默认值
callback	SDK获取到注册结果之后调用此函数	Function({accessToken: string})	是	无

示例

botApp.getRegisterResult(function (data) {
     console.log(data);
    // 打印结果如下：
    {
        "accessToken": "{{string}}",
        "apiAccessToken":"{{string}}",
        "syncLocalStorage":"{{boolean}}",
        "userId": "{{string}}",
        "deviceId": "{{string}}",
        "deepUrl":"{{string}}"
    }
})

requireUserAgeInfo(callback) 1.5+ `SHOW ONLY`

本方法获取用户的实名认证信息，如果用户没有实名认证则会在小度在家上自动弹出实名认证的二维码。

参数	说明	类型	必填	默认值
callback	本回调会传入用户的实名认证结果	Function(err: Object, data: Object)	必填	是

err参数

参数	说明	类型
err	SDK内建错误信息，见附录	Object
err.code	错误码，详细对照见附表	number
err.msg	错误信息，详细对照见附表	string

data参数

参数	说明	类型
data	实名认证信息	Object
data.is_auth	用户是否完成实名认证，1：已完成，2：未完成	enum {"1", "2"}
data.age_group	用户年龄段，16岁-18岁为1，18岁以上为2，16岁以下为3	enum {"1", "2", "3"}

正常返回示例

botApp.requireUserAgeInfo(function (err, data) {
    console.log(err, data);
    // 打印如下：
    null
    {
        "is_auth": "1",
        "age_group": "2"
    }
});

设备版本过低返回：

botApp.requireUserAgeInfo(function (err, data) {
    console.log(err, data);
    // 打印如下：
    {
        code: 1001,
        msg: 'Device version too low'
    }
    null
});

requireCharge(data, [,callback(err, payload)])

本方法会发起收款，当用户支付成功后，如果是在 SHOW 端设备中，通过onChargeStatusChange(callback)接收付款结果通知，如果是在 App 中，会调用传入的callback函数。

对于用户支付成功的订单，会有服务端的订单通知接口，开发者应以该接口的订单支付成功通知为最终数据。

参数	说明	类型	必填	默认值
data	订单参数	Object	必填	无
data.token	本次事件的token，开发者自己提供	Object	否	无
data.chargeBaiduPay.authorizeAttributes.sellerAuthorizationNote	商家授权信息备注	string	是	无
data.chargeBaiduPay.authorizeAttributes.authorizationAmount.amount	价格，单位元	string	是	无
data.chargeBaiduPay.authorizeAttributes.authorizationAmount.currencyCode	币种，目前仅支持 CNY	enum {"CNY"}	是	无
data.chargeBaiduPay.sellerOrderAttributes.sellerOrderId	此笔交易在商家这边的订单ID。当用户付款成功后，会带有此ID通知技能	string	是	无
data.chargeBaiduPay.sellerOrderAttributes.productName	商品名称	string	是	无
data.chargeBaiduPay.sellerOrderAttributes.productId	商品ID	string	是	无
data.chargeBaiduPay.sellerOrderAttributes.description	商品描述信息。对商品的简单介绍	string	是	无
data.chargeBaiduPay.sellerOrderAttributes.sellerNote	商品的备注信息	string	是	无
callback	本函数只会在 App 中被调用，SHOW设备请使用`onChargeStatusChange`接收购买结果。	Function	否(App环境下必填)	无

callback只会在小度App/小度音箱App中被回调，传入的参数见下表。小度有屏音箱设备请使用onChargeStatusChange接收购买结果

参数	说明	类型
err	错误信息	Error\|string
payload	本次交易的扣款信息	Object
payload.authorizationDetails.authorizationAmount.amount	扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.authorizationAmount.currencyCode	目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.capturedAmount.amount	实际百度扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.capturedAmount.currencyCode	枚举类型。目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.creationTimestamp	订单创建时间。时间戳，单位毫秒	string
payload.baiduOrderReferenceId	此次交易百度生成的订单ID	string
payload.sellerOrderId	对应支付的订单ID	string
payload.purchaseResult	此次支付结果。选值范围： - SUCCESS 支付成功 - ERROR 支付发生错误	enum {"SUCCESS", "ERROR"}
payload.message	支付状态对应的消息	string

示例

const data = {
    token: 'fjaksvmakfjiefj23fdsnfs',
    chargeBaiduPay: {
        authorizeAttributes: {
            authorizationAmount: {
                amount: '1.09',
                currencyCode: 'CNY'
            },
            sellerAuthorizationNote: '双11大促'
        },
        sellerOrderAttributes: {
            sellerOrderId: 'hfuawffu2jkjk12e23',
            productName: 'Mac Book Pro 2019',
            productId: 'fjaksdfkvjsznvj',
            description: '笔记本电脑',
            sellerNote: '大促销'
        }
    }
}
botApp.requireCharge(data, function (err, data) {
    if (!err) {
        console.log(data);
        // 结果如下
        {
            authorizationDetails: {
                authorizationAmount: {
                    amount: "1.99",
                    currencyCode: 'CNY'
                },
                capturedAmount: {
                    amount: '1.09',
                    currencyCode: 'CNY'
                },
                creationTimestamp: '1546272000000'
            },
            baiduOrderReferenceId: 'fjkasdfekfjsnvks',
            sellerOrderId: 'fskdfjmvckadfl',
            purchaseResult: 'SUCCESS',
            message: '支付成功'
        }
    }
});

requireBuy(data, callback) 1.4+ `App ONLY`

本方法不同于requireCharge，需要事先在度秘的商品库里注册productId。callback函数会在返回游戏页面后调用，调用可能会有明显延迟。

参数	说明	类型	必填	默认值
data	商品信息	Object	是	无
data.productId	商品ID	string	是	无
data.sellerOrderId	接入方自己的订单ID	string	是	无
callback	获取购买结果，传入的参数见下表	Function	是	无

callback传入的参数

参数	说明	类型
err	错误信息	Any
payload	本次交易的扣款信息	Object
payload.authorizationDetails.authorizationAmount.amount	扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.authorizationAmount.currencyCode	目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.capturedAmount.amount	实际百度扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.capturedAmount.currencyCode	枚举类型。目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.creationTimestamp	订单创建时间。时间戳，单位毫秒	string
payload.baiduOrderReferenceId	此次交易百度生成的订单ID	string
payload.sellerOrderId	对应支付的订单ID	string
payload.purchaseResult	此次支付结果。选值范围： - SUCCESS 支付成功 - ERROR 支付发生错误	enum {"SUCCESS", "ERROR"}
payload.message	支付状态对应的消息	string

示例

botApp.requireBuy({
    productId: '191022111415582172',
    sellerOrderId: 'xxxxxx112121xxxx'
}, function (err, data) {
    if (!err) {
        console.log(data);
        // 打印结果如下
        {
            authorizationDetails: {
                authorizationAmount: {
                    amount: "1.99",
                    currencyCode: 'CNY'
                },
                capturedAmount: {
                    amount: '1.09',
                    currencyCode: 'CNY'
                },
                creationTimestamp: '1546272000000'
            },
            baiduOrderReferenceId: 'fjkasdfekfjsnvks',
            sellerOrderId: 'fskdfjmvckadfl',
            purchaseResult: 'SUCCESS',
            message: '支付成功'
        }
    }
});

BotApp.onChargeStatusChange(callback) `SHOW ONLY`

通知支付结果。该指令只是一个前端的通知，第三方开发者可以用此回调做页面的刷新。

仅当在小度有屏音箱上使用requireCharge()发起支付动作时本方法中的回调才会被调用

callback传入的参数

参数	说明	类型
payload	本次交易的扣款信息	Object
payload.authorizationDetails.authorizationAmount.amount	扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.authorizationAmount.currencyCode	目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.capturedAmount.amount	实际百度扣款金额。比如：1.09，数字字符串。系统取小数点后两位，单位：元	string
payload.authorizationDetails.capturedAmount.currencyCode	枚举类型。目前只能为CNY	enum {"CNY"}
payload.authorizationDetails.creationTimestamp	订单创建时间。时间戳，单位毫秒	string
payload.baiduOrderReferenceId	此次交易百度生成的订单ID	string
payload.sellerOrderId	对应支付的订单ID	string
payload.purchaseResult	此次支付结果。选值范围： - SUCCESS 支付成功 - ERROR 支付发生错误	enum {"SUCCESS", "ERROR"}
payload.message	支付状态对应的消息	string
payload.token	标识本次返回，可能没有	string

示例

botApp.onChargeStatusChange(function (payload) {
    console.log(payload);
    // 打印结果如下：
    {
        token: 'faskdfkasdfsnvcknawjkenfjkwa', // 标识本次返回
        authorizationDetails: {
            authorizationAmount: {
                amount: "1.99",
                currencyCode: 'CNY'
            },
            capturedAmount: {
                amount: '1.09',
                currencyCode: 'CNY'
            },
            creationTimestamp: '1546272000000'
        },
        baiduOrderReferenceId: 'fjkasdfekfjsnvks',
        sellerOrderId: 'fskdfjmvckadfl',
        purchaseResult: 'SUCCESS',
        message: '支付成功'
    }
})

onHandleIntent(callback) `SHOW ONLY`

意图下发。开发者在DBP平台上面开发的意图，在匹配到用户对话之后会封装对应意图成为Intent下发下来。

DBP开放平台：https://dueros.baidu.com/dbp 本方法仅支持在小度有屏音箱上调用

callback传入的参数

参数	说明	类型
payload	意图解析结果	Object
payload.intent.name	DuerOS解析出来的意图名称	string
payload.intent.slots[].name	槽位名	string
payload.intent.slots[].value	槽位值	string
payload.intent.customData.jsonData	额外的信息，JSON规范的字符串，一般用不上	string

示例：

botApp.onHandleIntent(function (payload) {
    console.log(payload);
    // 结果如下：
    {
        "app": {
            "packageName": "com.baidu.duershow.h5container"
        },
        "customData": "",
        "intent": {
            "name": "test_city",
            "slots": [{
                "name": "sys.city",
                "value": "{\"city\":\"南京\",\"origin\":\"南京\"}"
            }]
        }
    }
});

listen() `SHOW ONLY`

开启聆听。设备会进入语音交互状态。

本方法仅支持在小度有屏音箱上调用

示例
```
botApp.listen();
```

speak(data) `SHOW ONLY`

将文字转换为语音播报出来，播报进度可通过onDialogStateChanged获取

本方法仅支持在小度有屏音箱上调用

参数	说明	类型	必填	默认值
data	要语音播报的文字	string	是	无

示例

/**
data: 要播报的TTS的文字内容
*/
botApp.speak('欢迎使用');

requestClose() 1.1+ `SHOW ONLY`

本方法仅支持在小度有屏音箱上调用

请求退出。调用此方法后，小度有屏音箱上正在运行的H5会退出。

示例
```
botApp.requestClose();
```

updateUiContext(data) `SHOW ONLY`

本接口定义通用的自定义用户交互能力，设备端可以自主实现所希望的交互过程。

正常情况下交互都是由服务端决定的，比如问“西藏天气怎么样”则小度反问“西藏哪个城市的？不同城市的天气差别还是挺大的。”，但存在一些场景服务端因为信息缺乏，不能完全确定交互过程，需要由设备端配合来驱动用户交互过程。例如，在抽奖游戏中，H5页面上展示了2个宝箱，用户说“我选左边的”，服务端无法可能无法确定“我选左边的”或者“我选右边的”分别对应哪个宝箱，因此需要调用本方法来定义。

使用案例：选水果
H5：展示两个个水果在界面上：苹果、香蕉
H5：调用updateUiContext([(utterances="苹果", url="https://www.apple.com"), (utterances="香蕉", url="https://www.banana.com")])
H5：调用speak('你要哪个水果呢')
H5：调用listen()进入聆听态
用户：“苹果”
服务端：下发ClickLink
H5：在onClickLink(callback)中接收ClickLink携带的结果
H5：判断ClickLink回调函数中传入的URL是https://www.apple.com还是https://www.banana.com
H5：进入后续自定义处理逻辑

本方法仅支持在小度有屏音箱上调用

参数	说明	类型	必填	默认值
data	要上传的端状态数据	Object	是	无
data.enableGeneralUtterances	是否由系统自动处理未匹配上updateUIContext中设置的用户对话	boolean	是	无
data.hyperUtterances[].utterances	需要处理的用户话术集合	Array	是	无
data.hyperUtterances[].url	用于确定用户query的url	boolean	是	无
data.hyperUtterances[].type	自定义类型为link,系统还提供内建类型 input,select等等，具体见下方附表	enum	是	无
data.hyperUtterances[].params	携带的参数，参数根据type的不同而不同，具体参加下方附表	Any	是	无

示例

const data = {
    enableGeneralUtterances: true, // 如果为false,当用户的表达与下方注册的常用表达都不匹配时设备不会有任何处理
    hyperUtterances: [
        {
            url: 'https://www.apple.com', // 当用户的语音对话内容与utterances匹配时，SDK会调用onClickLink中的回调函数，并将本URL当做参数。
            utterances: ['苹果'],
            type: 'link',
            params: {}
        },
        {
            url: 'https://www.banana.com',
            utterances: ['香蕉'],
            type: 'link',
            params: {}
        },
        {
            url: 'https://www.strawberry.com',
            utterances: ['草莓'],
            type: 'link',
            params: {}
        }
    ]
};
botApp.updateUiContext(data);

onClickLink(callback) `SHOW ONLY`

ClickLink事件下发。ClickLink是一种Directive，用户新增自定义交互(updateUiContext())之后，云端会解析用户定义的交互，通过此方法下发上面定义的url。

如果用户引用系统内建自定义类型，用户query中可以包含参数，例如"输入北京"，这个query中北京可以被解析成参数，放到后面params中下发。

系统内建类型参考：见下方附表本方法仅支持在小度有屏音箱上调用

参数	说明	类型	必填	默认值
callback	云端下发ClickLinke指令后本函数会被调用	Function	是	无

callback参数

参数	说明	类型
payload	云端下发的指令内容，一般是`updateUiContext()`中传入的`hyperUtterances`中的内容	Object
payload.url	用户对话内容与`updateUiContext()`中`hyperUtterances`定义的对话内容匹配时相对应的url	string
payload.params	同`updateUiContext()`	Object

示例

如果使用updateUiContext的示例数据来自定义交互能力，则表现如下
用户：小度小度，草莓

botApp.onClickLink(function (payload) {
    console.log(payload);
    // 打印如下
    {
        url: 'https://www.straberry.com',
        params: {}
    }
});

onHandleUnknowUtterance(callback) 1.6+ `SHOW ONLY`

当用户的对话内容不在updateUiContext设置的用户表达范围时，开发者可使用本能力获取用户对话的语音识别(ASR)文字结果。

必须先调用updateUiContext()，同时将enableGeneralUtterances设置为false。

参数	说明	类型	必填	默认值
callback	语音识别结果会通过本函数传入	Function(err: Any, {query: string})	是	无

示例

botApp.updateUiContext({
    enableGeneralUtterances: false,
    hyperUtterances: [
        {
            url: 'https://www.banana.com',
            utterances: ['香蕉'],
            type: 'link',
            params: {}
        }
    ]
});

botApp.onHandleUnknowUtterance(function (err, data) {
    console.log(data);
    // 当用户对话：小度小度，哈密瓜
    // 打印结果如下：
    {
        query: "哈密瓜"
    }
});

uploadLinkClicked(data) 1.2+ `SHOW ONLY`

LinkClick是DuerOS系统中定义的事件上报的一种。DuerOS根据其携带的参数下发不同的指令，也可能什么指令也不下发。

本方法仅支持在小度有屏音箱上调用

参数	说明	类型	必填	默认值
data	要上报的事件内容	Object	是	无
data.url	要上报的LinkUrl	string	是	无

示例

botApp.uploadLinkClicked({
    url: 'dueros://d7a12baa-47d5-437f-7af6-05bc9c4e5c28/?openbot=true&oss_channel=ls_m'
});

onHandleScreenNavigatorEvent(callback) `SHOW ONLY`

屏幕导航事件。当用户发起语音请求，要求滚动屏幕时，本事件会被调用。

本方法仅支持在小度有屏音箱上调用

参数	说明	类型	必填	默认值
callback	获取屏幕导航参数	Function({data: number})	是	无

滚动方向说明

滚动方向	值	类型
向左滚动	1	number
向右滚动	2	number
向上滚动	3	number
向下滚动	4	number
下一页	5	number
上一页	6	number
history go back	7	number
回到Home页	8	number

示例

对小度音箱说：『向左滚动』

botApp.onHandleScreenNavigatorEvent(function (payload) {
    console.log(payload);
    //打印：
    {
        data: 1
    }
})

requireShipping() 1.3+ `SHOW ONLY`

请求发货信息。要调用本方法则必须在BotApp初始化时填写skillID，并同时使用onHandleIntent()来获取发货信息。本方法会在初始化阶段自动调用一次，开发者也可手动调用本方法。

本方法仅支持在小度有屏音箱上调用

示例
```
botApp.requireShipping();
```

onDialogStateChanged(callback) 1.6+ `SHOW ONLY`

用户对话状态变化通知，用户唤醒设备，发起语音指令，TTS播报，进入空闲状态都会收到回调通知。

参数	说明	类型	必填	默认值
callback	用户对话状态变化通知	Function(err: Object, status: string)	是	无

callback参数

参数	说明	类型
err	内建错误类型，见附表	Object
status	用户对话状态，具体见下方表格	string

用户对话状态

状态名称	状态值
空闲状态	IDLE
正在语音输入	LISTENING
语音输入完成，等待后端返回	THINKING
正在进行TTS播报	SPEAKING
开始TTS播报	TTS_START
TTS播报正常结束	TTS_FINISH
TTS播报中途被打断	TTS_INTERRUPT

示例

botApp.onDialogStateChanged(function (err, status) {
    console.log(status);
    //唤醒设备后，打印如下：
    LISTENING
})

canGoBack(callback) 1.6+ `SHOW ONLY`

获取设备浏览器历史记记录是否还能后退

参数	说明	类型	必填	默认值
callback	获取设备浏览器历史记记录是否还能后退	Function(err: Object, canGoBack: boolean)	是	无

callback参数

参数	说明	类型
err	内建错误类型，见附表	Object
canGoBack	浏览器历史记录是否还能回退	boolean

示例

 botApp.canGoBack(function(err, status) {
     console.log(status);
     // 打印如下
     true // 也有可能是false
});

initAd(config) 1.7+ `SHOW ONLY`

初始化广告。

参数	说明	类型	必填	默认值
config	广告相关参数配置	Object	是	无
config.placeId	广告位ID，联系DuerOS接口人申请	string	是	无
config.screenOrientation	游戏的屏幕类型，portrait => 竖屏游戏，landscape => 横屏（全屏）游戏，SDK根据不同屏幕类型展示不同形式的广告	enum {"portrait", "landscape"}	否	portrait
config.zIndex	广告浮层的层级	number	否	9999
config.displayStrategy	广告展示策略，once => 用户关闭后不再填充广告， twice => 用户关闭60s后再填充一次	enum {"once", "twice"}	否	twice
config.firstDisplayTime	广告第一次展示在本方法调用多久后，单位秒	number	否	10
config.bannerPosition	配置banner广告（横屏游戏中的广告）在游戏页面中的位置，值为CSS中的left、top、right、bottom	Object	否	{right: "30px", bottom: "30px"}
config.clickCallback	广告被点击时的回调	Function	否	无
config.closeCallback	广告关闭回调	Function	否	无
config.displayCallback	广告展示回调	Function	否	无
config.switchCallback	广告切换回调	Function	否	无

示例

botApp.initAd({
   placeId: '5bnTSA3%2Bk%2FlCppVdt9bzxe%2B7gnZMFYgnMQLXt3dB%2FWFKf4lyam1he4m8ubUrZ0dj2d5T49v1ld1b9JHT%2B6ZhWIp9T6niQuPFPWCZ%2BpOIZhg%3D',
   screenOrientation: 'portrait',
   zIndex: 9999,
   displayStrategy: 'twice',
   firstDisplayTime: 10,
   bannerPosition: {
       right: '30px',
       bottom: '30px'
   },
   clickCallback: function() {
      console.log('用户点击了广告');
   },
   closeCallback: function() {
     console.log('用户关闭了广告');
   },
   displayCallback: function() {
      console.log('广告展示成功');
   },
   switchCallback: function() {
       console.log('广告切换成功');
   }
})

registerGesture(config, callback) 1.8+ `SHOW ONLY`

注册手势识别。注册后可在回调函数中接收到手势识别的结果。

目前已经支持的手势类型

手势名称	值
OK	GESTURE_OK
五指张开的手掌	GESTURE_PALM
握拳，拇指竖起，拳头横向使拇指朝向右边	GESTURE_RIGHT
握拳，拇指竖起，拳头横向使拇指朝向左边	GESTURE_LEFT

参数	说明	类型	必填	默认值
config	需要注册的手势列表	Array	是	无
callback	接收手势识别的回调函数	Function	是	无

callback参数

参数	说明	类型
err	内建错误类型，见附表	Object
getture	手势识别结果	string

示例

 botApp.registerGesture(['GESTURE_OK', 'GESTURE_PALM', 'GESTURE_LEFT', 'GESTURE_RIGHT'], (err, gesture) => {
     if (!err) {
         console.log(gesture);
         // 如果是OK手势，则打印结果如下
         // GESTURE_OK
     }
 });

interruptTTS() 1.8+ `SHOW ONLY`

打断正在播报的TTS

示例
```
 botApp.interruptTTS();
```

getCameraState(callback) 1.8+ `SHOW ONLY`

获取设备摄像头状态

参数	说明	类型	必填	默认值
callback	接收摄像头状态的回调	Function	是	无

callback参数

参数	说明	类型
err	内建错误类型，见附表	Object
state	摄像头状态	enum {'ENABLED','DISABLED'}

sendEvent(data) 1.8+ `SHOW ONLY`

上报事件。第三方开发者一般用不到。

参数	说明	类型	必填	默认值
data	事件相关参数	Object	是	无
data.namespace	事件命名空间	string	是	无
data.name	事件名	string	是	无
data.needDialogRequestId	是否需要dialogRequestId，由设备生成	boolean	是	无
data.payload	事件携带的相关参数	Object\|null	是	无

示例

 const data = {
     namespace: 'ai.dueros.device_interface.bot_app_sdk',
     name: 'TouchedDown',
      needDialogRequestId: false,
      payload: {
          position : {
               left: '20px',
               top: '40px',
          }
      }
 };
 log(data);
 botApp.sendEvent(data);

onBuyStatusChange(callback) 1.9+ `SHOW ONLY`

第三方开发者可以用此回调做页面的刷新。支付模块和第三方会有个服务端的通知通路，第三方开发者以服务端的通知订单数据为准。 注意和onChargeStatusChange作区分，这个通知是Buy购买行为的通知。onChargeStatusChange是支付行为的通知

参数	说明	类型	必填	默认值
callback	接收购买结果的回调	Function	是	无

示例

 botApp.sendEvent(function (err, data) {
    if (!err) {
        console.log(data);
        // 打印结果如下：
        {
            "productId": "{{STRING}}",
            "baiduOrderReferenceId": "{{STRING}}",
            "sellerOrderId":"{{STRING}}",
            "purchaseResult":"{{ENUM}}",
            "message":"{{STRING}}" //  - SUCCESS 支付成功,- ERROR 支付发生错误
        }
    }
});

uploadBase64Image(base64Image, callback) 1.9+ `SHOW ONLY`

上传base64编码过的图片到云端。

参数	说明	类型	必填	默认值
base64Image	base64编码的图片	String	是	无
callback	接收上传结果的回调	Function	是	无

示例

const base64Image = 'data:image/png;base64,iVBORw0KGgoAAAANSUhE';
 botApp.uploadBase64Image(base64Image, function (err, data) {
    if (!err) {
        console.log(data);
        // 打印结果如下：
        'SUCCESS' // 上传成功
        'FAILED' // 上传失败
    }
});

getUserInfo（callback）1.13+ `SHOW ONLY`

本方法获取用户信息。

参数	说明	类型	必填	默认值
callback	接收使用者信息的回调	Function	是	无

示例

botApp.getUserInfo(function (data) {
    console.log(data);
    // 打印结果如下 ：

    "userId": "2506829803",
    "userName": "186*****505",
    "avatar": "http://nemoapi.zaijia.com/profile/picture2?k=18946961-f237c568-5cf7-4d7b-995c-fc83b276ab21-1583379570809"

});

submitRankScore（socre, callback）1.13+ `SHOW ONLY`

本方法用于提交关卡分数

参数	说明	类型	必填	默认值
score	接收使用者关卡的分数，score 属于[0,1000000)单个分值不超过100w	String	是	无
callback	接收提交关卡分数的回调	Function	是	无

status参数

返回状态码(status)	返回信息(msg)	说明
0	success	查询成功
1001	failed:Nonstandard parameters	url中输入的参数不规范，参数名称错误或参数值格式不规范
1002	failed: Parameters out of range	参数值超过范围
1003	failed: Internal Error	服务端错误，多次返回请联系相关负责人
1004	failed: Internal Error	服务端错误，多次返回请联系相关负责人
1005	failed: The queried data does not exist	查询的数据不存在，例如当前技能没有排行榜或该用户没有提交过分数信息等
1006	failed: Internal Error	服务端错误，多次返回请联系相关负责人

示例

botApp.submitRankScore(score, function (data) {
    console.log(data);
    // 打印结果如下 ：
    "status": 0,   
    "msg": "success",
    "data": {
        "score": 20,   // 提交之后当前用户分值
        "rank": 100    // 提交之后当前用户排名， -1为未进入排行榜（排行榜只统计前500名）
    }
});

getRankList（list, callback）1.13+ `SHOW ONLY`

本方法用于获取排行榜排名列表

参数	说明	类型	必填	默认值
list	接收使用者页面请求，pageSize属于[1,100]单页显示最大数量100, page属于[0,500)最大页数500页	Object	是	无
callback	接收排行榜排名列表的回调	Function	是	无

status状态码同方法submitRankScore

示例

list = {
  page : '0',
  pageSize : '20',

}
botApp.getRankList(list, function (data) {
    console.log(data);
    // 打印结果如下 ：
    "status": 0,
        "msg": "success",
        "data": {
            "currentPage": 0, // 当前页码，从0开始
            "totalPage": 50, // 总页数
            "hasNext": true, // 是否还有下一页
            "ranklist": [{
                    "userId": 1234567, // 用户id                
                    "userName": '昵称', // 用户昵称
                    "userAvatar": "", // 用户头像
                    "rank": 1, // 当前的排名 -1为未进入排行榜（排行榜只统计前500名）
                    "score": 100 // 当前用户的分数
                },
                ...
            ]
        }
    });

getMyRanking (callback) 1.13+ `SHOW ONLY`

本方法用于获取当前用户的排名

参数	说明	类型	必填	默认值
callback	接收当前用户排名信息的回调	Function	是	无

status状态码同方法submitRankScore

示例

botApp.getMyRanking(function (data) {
    console.log(data);
    // 打印结果如下 ：
     "status": 0,
    "msg": "success",
    "data": {
        "userId": 1234567, // 用户编号
        "userName": '用户昵称', // 用户昵称
        "rank": 1, // 当前的排名 -1为未进入排行榜（排行榜只统计前500名）
        "score": 100   //当前用户分值
    }
});

getSetProgress (levelNum, callback) 1.13+ `SHOW ONLY`

本方法用于设置游戏关卡进度

参数	说明	类型	必填	默认值
levelNum	标记上传关卡值，levelNum属于[0,10000] 最大关卡数10000	String	是	无
callback	接收推荐游戏列表的回调	Function	是	无

status状态码同方法submitRankScore

示例

botApp.getSetProgress('3', function (data) {
    console.log(data);
    // 打印结果如下 ：
    "status": 0,
    "msg": "success",
    "data": {
        "recommendList": [
            {
                "botId": "",   //技能id/游戏id
                "icon": "",    // 展示icon
                "showName": "",  // 游戏名称
                "linkUrl": ""    // 点击地址
            },
            ...
        ]
    }
});

附表

内建错误信息

错误名称	code	msg	描述
LowVersionErrorMsg	1001	Device version too low	设备版本过低错误
ServiceError	1002	Service error, {{msg}}	接口请求报错

打包方式

打包名称	描述
npm run test	单测
npm run buildSingleFile	单测并打包生成非trial类型的js文件
npm run buildSingleFileTril	单测并打包生成trial类型的js文件
npm run buildModule	单测并转义src的js放入lib中
npm run buildAll	单测并打包生成trial类型和非trial类型的js文件

Name		Name	Last commit message	Last commit date
Latest commit History 160 Commits
__test__		__test__
dist		dist
example		example
src		src
.babelrc		.babelrc
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
build_ci.sh		build_ci.sh
ci.yml		ci.yml
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
webpack.sdk.js		webpack.sdk.js

License

dueros/h5-bot-sdk

Folders and files

Latest commit

History

Repository files navigation

H5-BOT-SDK (v1.9.0)

本文档规范

名词解释

GUID

一个H5应用接入到度秘需要哪些步骤？

H5游戏想要运行在小度App/小度音箱App上？需要如下工作(本渠道已暂停开放)

BotApp的引入

接入益智乐园的H5游戏

普通接入（非益智乐园和游戏中心场景）

开始使用

isInApp() 1.4+

requireLinkAccount([,callback])

onLinkAccountSuccess(callback) SHOW ONLY

getRegisterResult(callback)

requireUserAgeInfo(callback) 1.5+ SHOW ONLY

requireCharge(data, [,callback(err, payload)])

requireBuy(data, callback) 1.4+ App ONLY

BotApp.onChargeStatusChange(callback) SHOW ONLY

onHandleIntent(callback) SHOW ONLY

listen() SHOW ONLY

speak(data) SHOW ONLY

requestClose() 1.1+ SHOW ONLY

updateUiContext(data) SHOW ONLY

onClickLink(callback) SHOW ONLY

onHandleUnknowUtterance(callback) 1.6+ SHOW ONLY

uploadLinkClicked(data) 1.2+ SHOW ONLY

onHandleScreenNavigatorEvent(callback) SHOW ONLY

requireShipping() 1.3+ SHOW ONLY

onDialogStateChanged(callback) 1.6+ SHOW ONLY

canGoBack(callback) 1.6+ SHOW ONLY

initAd(config) 1.7+ SHOW ONLY

registerGesture(config, callback) 1.8+ SHOW ONLY

interruptTTS() 1.8+ SHOW ONLY

getCameraState(callback) 1.8+ SHOW ONLY

sendEvent(data) 1.8+ SHOW ONLY

onBuyStatusChange(callback) 1.9+ SHOW ONLY

uploadBase64Image(base64Image, callback) 1.9+ SHOW ONLY

getUserInfo（callback）1.13+ SHOW ONLY

submitRankScore（socre, callback）1.13+ SHOW ONLY

status参数

getRankList（list, callback）1.13+ SHOW ONLY

status状态码同方法submitRankScore

getMyRanking (callback) 1.13+ SHOW ONLY

status状态码同方法submitRankScore

getSetProgress (levelNum, callback) 1.13+ SHOW ONLY

status状态码同方法submitRankScore

附表

内建错误信息

打包方式

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

onLinkAccountSuccess(callback) `SHOW ONLY`

requireUserAgeInfo(callback) 1.5+ `SHOW ONLY`

requireBuy(data, callback) 1.4+ `App ONLY`

BotApp.onChargeStatusChange(callback) `SHOW ONLY`

onHandleIntent(callback) `SHOW ONLY`

listen() `SHOW ONLY`

speak(data) `SHOW ONLY`

requestClose() 1.1+ `SHOW ONLY`

updateUiContext(data) `SHOW ONLY`

onClickLink(callback) `SHOW ONLY`

onHandleUnknowUtterance(callback) 1.6+ `SHOW ONLY`

uploadLinkClicked(data) 1.2+ `SHOW ONLY`

onHandleScreenNavigatorEvent(callback) `SHOW ONLY`

requireShipping() 1.3+ `SHOW ONLY`

onDialogStateChanged(callback) 1.6+ `SHOW ONLY`

canGoBack(callback) 1.6+ `SHOW ONLY`

initAd(config) 1.7+ `SHOW ONLY`

registerGesture(config, callback) 1.8+ `SHOW ONLY`

interruptTTS() 1.8+ `SHOW ONLY`

getCameraState(callback) 1.8+ `SHOW ONLY`

sendEvent(data) 1.8+ `SHOW ONLY`

onBuyStatusChange(callback) 1.9+ `SHOW ONLY`

uploadBase64Image(base64Image, callback) 1.9+ `SHOW ONLY`

getUserInfo（callback）1.13+ `SHOW ONLY`

submitRankScore（socre, callback）1.13+ `SHOW ONLY`

getRankList（list, callback）1.13+ `SHOW ONLY`

getMyRanking (callback) 1.13+ `SHOW ONLY`

getSetProgress (levelNum, callback) 1.13+ `SHOW ONLY`

Packages