基本参数
H5 SDK 提供产品信息、设备数据、用户信息与家庭信息等基本参数供 H5 面板使用,可通过
sdk.属性名
取得。属性名 | 类型 | 描述 |
deviceId | string | 设备 ID,由 {productId}/{deviceName} 组成。 |
productId | string | 产品 ID。 |
deviceName | string | 设备名称。 |
deviceInfo | ||
roomList | RoomList[] | 当前家庭的房间列表。 |
roomName | string | 当前设备的房间名称。 |
dataTemplate | string | 设备所在产品的物模型,与数据模板 > 查看JSON 中展示的物模型定义一致。 |
deviceStatus | number | 设备在线状态。在线:1,非在线:0。 |
deviceDisplayName | string | 设备展示名称,会依次取:AliasName > productInfo;name > deviceName 来展示。 |
isShareDevice | boolean | 是否是分享设备。 |
familyId | string | 设备所在家庭 ID,如果是分享设备则无此值。 |
roomId | string | 设备所在房间 ID,如果是分享设备则无此值。 |
familyInfo | 设备所在家庭详情,如果是分享设备则无此值。 | |
isFamilyOwner | boolean | 用户是否是当前家庭的所有者。 |
userInfo | object | 用户信息。 Avatar:string;头像 URL。 CountryCode:string;国家代码。 Email:string;邮箱地址。 NickName:string;昵称。 PhoneNumber:string;手机号码。 UserID:string;用户 ID。 |
设备管理
获取产品信息
接口定义
sdk.getProductInfo({ productId?: string }) => Promise<{ProductId: string,Name: string,Description: string,DataTemplate: string,NetType: string,CategoryId: number,ProductType: number,UpdateTime: number,}>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
productId | 可选,不传则使用当前设备的产品 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数如下。
参数名 | 参数描述 | 类型 |
ProductId | 产品 ID。 | string |
Name | 产品名称。 | string |
Description | 产品描述。 | string |
DataTemplate | 产品数据模板。 | string |
NetType | 通信方式(子设备为接入网关协议)。 | string |
CategoryId | 产品分类 ID。 | number |
ProductType | 产品类型(0:普通产品;5:网关产品)。 | number |
UpdateTime | 最后更新的 Unix 时间戳(秒级)。 | number |
获取设备信息
接口定义
sdk.getDeviceInfo({ deviceId?: string }) => Promise<{ProductId: string,DeviceName: string,DeviceId: string,IconUrl: string,AliasName: string,UserId: string,RoomId: string,CreateTime: number,UpdateTime: number} | {ProductId: string,DeviceName: string,DeviceId: string,IconUrl: string,AliasName: string,CreateTime: string}>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数请参见 DeviceList(非分享设备)和 ShareDevices(分享设备)。
控制设备属性
接口定义
sdk.controlDeviceData(data, deviceId?: string) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
data | 要控制的设备属性数据。 | object | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数请参见 用户控制设备。
调用设备行为(action)
接口定义
sdk.callDeviceAction(actionPayload: ActionPayload, actionId: string, deviceId?: string) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
actionPayload | 物模型中定义的行为调用入参。 | object | 是 |
actionId | 在物模型中定义的该行为的标志符。 | string | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数请参见 同步调用设备行为。
获取设备物模型数据
接口定义
sdk.getDeviceData({ deviceId?: string }) => Promise<object>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数为设备的物模型数据。
获取设备物模型历史数据
接口定义
sdk.getDeviceDataHistory({FieldName: string,MaxTime: number,MinTime: number,Context?: string,Limit: number}) => Promise<{RequestId: string,Context: string,FieldName: string,Listover: boolean,Results: DataHistoryItem[]}>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
FieldName | 查询的属性名称。 | string | 是 |
MaxTime | 结束时间,毫秒时间戳。 | number | 是 |
MinTime | 开始时间,毫秒时间戳。 | number | 是 |
Context | 翻页游标,首次查询时可不传。 | string | 否 |
Limit | 单页数据量。 | number | 是 |
返回值
返回一个 Promise,输出参数请参见 获取设备物模型历史数据。
获取设备当前状态
接口定义
sdk.getDeviceStatus({ deviceId?: string }) => Promise<0 | 1>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个 Promise,输出参数取值如下:
0:设备离线
1:设备在线
删除设备
接口定义
sdk.deleteDevice({ deviceId?: string }) => Promise<void>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID | string | 否 |
返回值
返回一个 Promise。
获取自定义分享参数
若该设备是分享设备,且分享方设置了自定义分享参数,则被分享方在接受分享后可通过该接口获取自定义分享参数。
接口定义
sdk.getShareParams({ deviceId?: string }) => Promise<any>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID | string | 否 |
返回值
返回一个 Promise,输出参数为自定义分享参数。
检查设备是否有可升级固件
检查指定设备是否有可升级固件,若有可升级固件,且设备在线,则弹出固件升级提示。
接口定义
sdk.checkFirmwareUpgrade({deviceId?: string,silent?: boolean}) => Promise<{CurrentVersion: string,DstVersion: string,}>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
silent | 可选,默认为 false。 true:只检查固件升级,不弹出固件升级提示。 false:检查固件升级,若有可升级固件,且设备在线,则弹固件升级提示。 | boolean | 否 |
返回值
返回一个 Promise,输出参数请参见 查询设备固件是否升级。
进行固件升级
跳转到小程序的固件升级页面,进行固件升级。
接口定义
sdk.goFirmwareUpgradePage({ deviceId?: string }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
用户管理
获取用户信息
接口定义
sdk.getUserInfo() => Promise<{Avatar: string,CountryCode: string,Email: string,NickName: string,PhoneNumber: string,UserID: string}>
返回值
返回一个 Promise,输出参数如下。
参数名 | 参数描述 | 类型 |
Avatar | 头像 URL。 | string |
CountryCode | 国家代码。 | string |
Email | 邮箱地址。 | string |
NickName | 昵称。 | string |
PhoneNumber | 手机号码。 | string |
UserID | 用户 ID。 | string |
界面组件
tips 组件
tips 组件,样式和风格与连连小程序一致。
展示 tips
接口定义
sdk.tips.show(message, options) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
message | 提示文本。 | string | 是 |
options.type | tips 类型。 | 'info' | 'danger' | 'loading' | 'success' | 否 |
options.waitForHide | 若为 true,则 show 方法返回一个 Promise,并且当关闭后才会触发 resolve。 | boolean | 否 |
options.duration | 展示提示的时间,单位毫秒,默认1500。 | number | 否 |
options.delayDuration | 默认为0,单位毫秒,提示会在该延时后展示。 | number | 否 |
options.canClickClose | 默认为 true,点击 mask 是否能够关闭提示。 | boolean | 否 |
options.canBeReplace | 默认为 false,为 false 时上一个提示未关闭前,再次调用 tips.show 会被忽略。 | boolean | 否 |
关闭 tips
接口定义
sdk.tips.hide() => Promise
展示 loading tips
封装后的
tips.show
方法,等价于:sdk.tips.show(message, {type: 'loading',canBeReplace: true,duration: 0,delayDuration: 200,canClickClose: false,...options,});
接口定义
sdk.tips.showLoading(message, options) => Promise
参数说明
请参见 展示 tips 参数说明。
关闭 loading tips
展示 loading tips 后必须主动调用本接口,否则 tips 将会一直保留。
接口定义
sdk.tips.hideLoading() => Promise
展示成功 tips
封装后的
tips.show
方法,等价于:sdk.tips.show(message, { type: 'success', ...options });
接口定义
sdk.tips.showSuccess(message, options) => Promise
参数说明
请参见 展示 tips 参数说明。
展示提示 tips
封装后的
tips.show
方法,等价于:sdk.tips.show(message, { type: 'info', ...options });
接口定义
sdk.tips.showInfo(message, options) => Promise
参数说明
请参见 展示 tips 参数说明。
展示错误 tips
先标准化处理错误展示信息,然后展示错误 tips。等价于:
sdk.tips.show(getErrorMsg(error), { type: 'error', ...options });
接口定义
sdk.tips.showError(error, options) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
error | 错误对象或错误信息。 | Error | { code, msg } | string | 是 |
options | object | 否 |
展示模态对话框
展示一个弹窗,参数、功能、样式同小程序原生 showModal 基本一致。
接口定义
sdk.tips.showModal({title?: string,content?: string,showCancel?: boolean,cancelText?: string,cancelColor?: string,confirmText?: string,confirmColor?: string,}) => Promise<boolean>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
title | 弹窗标题。 | string | 否 |
content | 弹窗内容。 | string | 否 |
showCancel | 是否展示取消按钮,默认为 true。 | boolean | 否 |
cancelText | 取消按钮文案,默认为“取消”。 | string | 否 |
cancelColor | 取消按钮颜色,默认为“#6C7078”。 | string | 否 |
confirmText | 确认按钮文案,默认为“确定”。 | string | 否 |
confirmColor | 确认按钮颜色,默认为“#0066FF”。 | string | 否 |
返回值
返回一个
Promise<boolean>
:true :代表用户单击确认。
false :代表用户单击取消。
展示确认模态对话框
基于
sdk.tips.showModal
封装,用于向用户进行二次确认操作时使用。接口定义
sdk.tips.confirm(title, content, options) => Promise<boolean>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
title | 弹窗标题。 | string | 否 |
content | 弹窗内容。 | string | 否 |
options | object | 否 |
示例代码
用户确认示例代码如下:
const isConfirm = await sdk.tips.confirm('确认删除该设备吗?');if (isConfirm) {// 用户确认,执行后续流程}
展示提示模态对话框
基于
sdk.tips.showModal
封装,用于向用户进行消息提示操作时使用。接口定义
sdk.tips.alert(content, options) => Promise<boolean>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
content | 弹窗内容。 | string | 否 |
options | object | 否 |
示例代码
向用户进行消息提示的示例代码如下:
await sdk.tips.alert('该功能暂时无法使用,请稍后再试');
设备离线提示组件
设备离线提示组件,样式和风格与连连小程序一致。
展示设备离线提示
接口定义
sdk.offlineTip.show() => void// 或sdk.showOfflineTip() => void
关闭设备离线提示
接口定义
sdk.offlineTip.hide() => void// 或sdk.hideOfflineTip() => void
H5 自定义设备详情视图
展示 H5 自定义设备详情视图
在当前 H5 展示一个铺满全屏的设备详情视图,支持增加自定义菜单项及按钮。
接口定义
sdk.showDeviceDetail({deviceInfo?: object,labelWidth?: number,marginTop?: number,shareParams?: object,extendItems?: ExtendItemConfig[],extendButtons?: ExtendButtonConfig[],containerClassName?: string}) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceInfo | 展示详情的设备信息,不传则使用当前设备信息。 | object | 否 |
labelWidth | 设备详情的 label 宽度,默认110,单位 px。 | number | 否 |
marginTop | 设备详情的上间距,默认10,单位 px。 | number | 否 |
shareParams | 自定义分享参数。 | object | string | 否 |
extendItems | 自定义菜单配置。 | ExtendItemConfig[] | 否 |
extendItems[].labelIcon | 展示在 label 前的 icon 地址。 | string | 否 |
extendItems[].label | 自定义菜单项的标题。 | string | 是 |
extendItems[].content | 自定义菜单项的内容。 | string | 否 |
extendItems[].className | 自定义菜单项的样式类名。 | string | 否 |
extendItems[].onClick | 点击自定义菜单项后触发的回调。 | () => any | 否 |
extendButtons | 自定义按钮配置。 | ExtendButtonConfig[] | 否 |
extendButtons[].text | 自定义按钮文案。 | string | 是 |
extendButtons[].className | 自定义按钮的样式类名。 | string | 否 |
extendButtons[].type | 自定义按钮的风格。 | '' | 'danger' | 'primary' | 'warning' | 否 |
extendButtons[].onClick | 自定义按钮点击后触发的回调。。 | () => any | 是 |
containerClassName | 容器的样式类名 | string | 否 |
关闭 H5 自定义设备详情视图
接口定义
sdk.hideDeviceDetail() => void
调用小程序能力
跳转小程序的标准设备详情页面
接口定义
sdk.goDeviceDetailPage({reload?: boolean,deviceId?: string,isShareDevice?: string,shareParams?: object | string,}) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
reload | 如果为 true,则进入详情页后会重新拉取一次该设备的数据。 如果为 false,则进入详情页后会使用缓存的设备数据。 | boolean | 否 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
isShareDevice | 可选,设备是否为分享设备,不传则使用当前的 sdk.isShareDevice。 | boolean | 否 |
shareParams | 可选,设备自定义分享参数。 | object | string | 否 |
跳转小程序的反馈页面
接口定义
sdk.goFeedBackPage() => Promise
跳转小程序的设备信息页面
接口定义
sdk.goDeviceInfoPage({ deviceId?: string }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
跳转小程序的修改设备名称页面
接口定义
sdk.goEditDeviceNamePage: ({ deviceId?: string, name?: string }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
name | 可选,不传则使用当前设备的 aliasName。 | string | 否 |
跳转小程序的房间设置页面
接口定义
sdk.goRoomSettingPage({ deviceId?: string }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
跳转小程序的设备分享页面
接口定义
sdk.goShareDevicePage({ deviceId?: string }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
小程序刷新数据
要求小程序在当前 H5 面板关闭后进行一次数据刷新。
接口定义
sdk.reloadAfterUnmount() => Promise
返回小程序的上一级页面
可用于主动关闭 H5 面板。
接口定义
sdk.navBack() => Promise
设置当前页面的分享内容
接口定义
sdk.setShareConfig({ title: string, imgUrl: string? }) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
title | 分享的标题。 | string | 是 |
imgUrl | 分享图片的地址,默认会取当前页面截图。 | string | 否 |
应用端 API
H5 SDK 对应用端 API 的调用过程进行了封装,发送请求时会自动带上公共参数
AccessToken
与 RequestId
。调用应用端 API
接口定义
sdk.requestTokenApi(action, data, options) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
action | 具体应用端 API Action 名称,例如:AppGetDeviceStatuses。 | string | 是 |
data | 接口调用参数。 | object | 否 |
options | object | 否 |
返回值
请求成功(code=0):返回一个 resolved 的 Promise,其值为应用端 API 响应中的
Response
部分数据。请求失败:返回一个 rejected 的 Promise,其值的数据结构为:
{ code, msg, ...detail }
。事件监听
监听事件
接口定义
sdk.on(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要监听的事件。 | string | 是 |
listener | 事件触发时的回调函数。 | (...args) => void | 是 |
取消监听事件
接口定义
sdk.off(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要取消监听的事件。 | string | 是 |
listener | 要取消监听的事件的回调函数,不传则清除该事件的所有回调函数。 | (...args) => void | 否 |
WebSocket 事件
wsClose 事件:WebSocket 的
close
事件。参数名 | 参数描述 | 类型 |
code | 服务器发送的关闭码。 | number |
reason | 服务器关闭连接的原因。 | string |
wsError 事件:WebSocket 的错误事件。
wsControl 事件:当 WebSocket 收到
control
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
deviceData | 设备数据。 | object |
wsReport 事件:当 WebSocket 收到
report
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
deviceData | 设备数据。 | object |
wsStatusChange 事件:当 WebSocket 收到
wsStatusChange
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
deviceStatus | 设备在线状态。 | 0 | 1 |
wsEventReport 事件:当 WebSocket 收到
wsEventReport
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
Payload | 设备回复详情。 | object |
wsActionPush 事件:当 WebSocket 收到
wsActionPush
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
Payload | 下发的 Action 指定详情。 | object |
wsActionReport 事件:当 WebSocket 收到
wsActionReport
指令后触发。参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
Payload | 设备回复的 Action 响应详情。 | object |
前后台切换事件
appShow 事件:当小程序 App.onShow 执行后触发。
appHide 事件:当小程序 App.onHide 执行后触发。
pageShow 事件:当小程序 Page.onShow 执行后触发。
pageHide 事件:当小程序 Page.onHide 执行后触发。
蓝牙模块
名词解释
名词 | 解释 |
serviceId | 服务 id,蓝牙服务的 uuid,搜索设备时主要通过 serviceId 来过滤我们需要的设备。 |
deviceId | 小程序 API 搜索出来的设备的标识,连接设备时主要通过 deviceId 来标识需要连接的设备。 |
explorerDeviceId | 物联网开发平台侧定义的设备 ID,查询设备数据和上报设备数据时以设备 ID 作为设备标识。 |
BlueToothAdapter 蓝牙适配器 | 全局单例,实例上声明了蓝牙搜索、连接等方法。 |
DeviceAdapter 设备适配器 | 真正用来连接设备以及跟设备进行通信的模块,每一个设备连接对应一个设备适配器实例,设备适配器会在连接设备后实例化,并在设备断开连接后销毁。根据不同的 serviceId 来区别不同类型设备的适配器构造函数。 |
蓝牙适配器
添加设备适配器
添加一个设备适配器。使用蓝牙模块时需要根据具体设备情况创建一个设备适配器,并调用本接口将其构造函数添加到蓝牙适配器中。H5 SDK 默认添加了一个支持 LLSync 蓝牙协议的设备适配器。
接口定义
sdk.blueToothAdapter.addAdapter(deviceAdapter: DeviceAdapterConstructor) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceAdapter | 要添加的设备适配器的构造函数。 | DeviceAdapterConstructor | 是 |
示例代码
class DemoDeviceAdapter extends DeviceAdapter {static serviceId = '0000FFF0-0000-1000-8000-00805F9B34CC';static deviceFilter(deviceInfo) {if (deviceInfo.advertisServiceUUIDs) {const matchedServiceId = deviceInfo.advertisServiceUUIDs.find(id => id === DemoDeviceAdapter.serviceId);if (matchedServiceId && deviceInfo.advertisData) {try {const macArr = deviceInfo.advertisData.slice(2);const mac = macArr.join(':');return {...deviceInfo,deviceName: mac,serviceId: matchedServiceId,};} catch (err) {console.error('parse mac error', err);}}}}handleBLEMessage(hex) {return {type: 'unknown',data: hex,};}}sdk.blueToothAdapter.addAdapter(DemoDeviceAdapter);
初始化蓝牙模块
初始化蓝牙模块,包括初始化蓝牙模块、打通小程序间蓝牙通信以及注册全局回调等。本接口可重复调用,可在每次使用蓝牙模块前调用。
接口定义
sdk.blueToothAdapter.init() => Promise<void>
返回值
返回一个带缓存的 Promise,初始化成功后 resolve。若初始化未完成或已初始化成功,则多次调用后返回同一个 Promise。若初始化失败,则该缓存的 Promise 在 reject 之后会被释放,再次调用则将重新初始化。
示例代码
sdk.blueToothAdapter.init().then(() => {// 调用蓝牙模块能力});
开始搜索蓝牙设备
接口定义
sdk.blueToothAdapter.startSearch({serviceId?: string,serviceIds?: string[],ignoreDeviceIds?: string[],onSearch: (DeviceInfo[]) => void,onError: (Error) => void,timeout: number}) => Promise<void>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
serviceId | 指定需要搜索的 serviceId,不传的话会使用当前支持的所有 DeviceAdapter 的 serviceId 来匹配。 | string | 否 |
serviceIds | 参数描述同 serviceId。 | string[] | 否 |
ignoreDeviceIds | 可选,需要过滤掉的 deviceId 列表(例如刚添加完的设备),搜索结果中将不会出现这些设备。 | string[] | 否 |
onSearch | 当搜索结果更新后调用,返回搜索到的设备列表。 | (DeviceInfo[]) => void | 是 |
onError | 当搜索过程中发生错误后调用,触发后设备搜索将会中止。 | (Error) => void | 是 |
timeout | 可选,默认20000,单位毫秒,超过指定时长没有搜索到设备后将会触发超时错误。 | number | 是 |
返回值
返回一个 Promise。
停止搜索蓝牙设备
接口定义
sdk.blueToothAdapter.stopSearch() => void
搜索单个蓝牙设备
开始搜索蓝牙设备,并在搜索到第一个满足条件的设备后停止搜索。
接口定义
sdk.blueToothAdapter.searchDevice({deviceName: string,serviceId?: string,serviceIds?: string[],ignoreDeviceIds?: string[]}) => Promise<DeviceInfo>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceName | 指定需要搜索的设备 deviceName。 | string | 是 |
serviceId | 指定需要搜索的 serviceId,不传的话会使用当前支持的所有 DeviceAdapter 的 serviceId 来匹配。 | string | 否 |
serviceIds | 参数描述同 serviceId。 | string[] | 否 |
ignoreDeviceIds | 可选,需要过滤掉的 deviceId 列表(例如刚添加完的设备),搜索结果中将不会出现这些设备。 | string[] | 否 |
返回值
返回一个 Promise,在找到第一个满足条件的设备后 resolve。
连接蓝牙设备
连接指定蓝牙设备。
接口定义
blueToothAdapter.connectDevice(deviceInfo: DeviceInfo, options?: { autoNotify?: boolean }) => Promise<DeviceAdapter>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceInfo | DeviceInfo | 是 | |
options.autoNotify | 可选,默认为 true。指定为 true 时,在连接设备后,会自动去拉取服务列表,以及主服务下的特征值列表,并会自动订阅第一个 notifyId 或 indicateId 特征值的 notify。若设备含有多个服务或多个 notify 特征值,请传 false,并自行通过 getBLEDeviceServices、getBLEDeviceCharacteristics、notifyBLECharacteristicValueChange等方法获取及订阅特征值。 | boolean | 否 |
返回值
返回一个 Promise,连接成功后返回设备适配器。
获取设备适配器实例
根据
deviceId
查询对应的设备适配器实例。接口定义
sdk.blueToothAdapter.getDeviceAdapter({explorerDeviceId: string}) => DeviceAdapter
参数说明
参数名 | 参数描述 | 类型 | 必填 |
explorerDeviceId | 设备适配器实例的 explorerDeviceId,可以通过 sdk.deviceId 获得。 | string | 是 |
返回值
返回与传入
explorerDeviceId
相匹配的设备适配器实例,如果找不到,则返回 undefined
。上报设备信息
蓝牙设备不能通过 mqtt 直接上报设备的 mac 地址等信息,所以需要H5端进行上报,对应的是设备详情里面的设备信息。
注意:
图片里面厂家名称和产品型号是在设备量产时在控制台填写的,mac 地址,固件版本等由 H5 端进行上报。
接口定义
sdk.blueToothAdapter.reportDeviceInfo({ productId: string, deviceName: string, deviceInfo: any }) => Promise;
参数说明
参数名 | 参数描述 | 类型 |
productId | 产品 ID。 | string |
deviceName | 设备名称。 | string |
deviceInfo | 设备信息。 | any,详情见下面示例。 |
deviceInfo: {"module_hardinfo": "模组具体硬件型号 N10","module_softinfo": "模组软件版本","fw_ver": "mcu 固件版本","imei": "设备 imei 号,可选上报","mac": "设备 mac 地址,可选上报","device_label": {"append_info": "设备商自定义的产品附加信息"}}
监听事件
监听蓝牙适配器事件。
接口定义
sdk.blueToothAdapter.on(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要监听的事件。 | string | 是 |
listener | 事件触发时的回调函数。 | (...args) => void | 是 |
取消监听事件
取消监听蓝牙适配器事件。
接口定义
sdk.blueToothAdapter.off(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要取消监听的事件。 | string | 是 |
listener | 要取消监听的事件的回调函数,不传则清除该事件的所有回调函数。 | (...args) => void | 否 |
蓝牙适配器事件
adapterStateChange 事件:当适配器状态变化时触发。
参数名 | 参数描述 | 类型 |
available | 蓝牙适配器是否可用。 | boolean |
discovering | 蓝牙适配器是否处于搜索状态。 | boolean |
设备适配器
自定义设备适配器
自定义设备适配器类需要继承
DeviceAdapter
,并补充以下实现。serviceId:自定义设备适配器类需要设置该属性,代表该设备的主服务 ID。
deviceFilter:自定义设备适配器类需要实现该静态方法,在搜索蓝牙设备时会将每个搜出的设备信息传入该方法,如果判断是本产品的设备,则需在除入参 deviceInfo 之外返回设备唯一标识 deviceName 及 serviceId,否则返回空。
DeviceAdapter.deviceFilter: (deviceInfo: DeviceInfo) => {deviceName: string,serviceId: string,...deviceInfo}
handleBLEMessage:自定义设备适配器类需要实现该方法,用于处理收到
onBLECharacteristicValueChange
回调后的协议解析。DeviceAdapter.handleBLEMessage: (hexString, { serviceId, characteristicId }) => {reportData?: any,...any}
返回值中如果返回
reportData
,则会将该部分数据上报到云端(注意需与产品定义物模型匹配),其他字段则会透传到 message
事件的 payload 中。设备适配器属性
属性名 | 属性描述 | 类型 |
explorerDeviceId | 只读,设备的 explorerDeviceId。 | string |
isConnected | 只读,当前是否已连接设备。 | boolean |
deviceId | 只读,设备的 deviceId。 | string |
serviceId | 只读,设备的主服务 ID,与构造函数上的静态属性 DeviceAdapter.serviceId 一致。 | string |
originName | 只读,设备的原始名称,即小程序接口搜索出来时的 name 字段。 | string |
断开设备连接
接口定义
deviceAdapter.disconnectDevice() => void
获取设备服务列表
接口定义
deviceAdapter.getBLEDeviceServices() => Promise<ServiceList>
返回值
返回一个 Promise,
ServiceList
数据结构请参见 wx.getBLEDeviceServices。获取设备指定服务的特征值列表
获取设备指定服务中的特征值列表,并将特征值存放在
deviceAdapter
实例上。接口定义
deviceAdapter.getBLEDeviceCharacteristics({ serviceId: string }) => Promise<CharacteristicsList>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
serviceId | 可选,指定要获取特征值列表的服务 ID,默认为主服务 ID。 | string | 否 |
返回值
返回一个 Promise,
CharacteristicsList
数据结构请参见 wx.getBLEDeviceCharacteristics。说明
将获取到的特征值按照如下数据结构存放在
deviceAdapter
实例上。deviceAdapter.characteristicsMap[serviceId] = {notifyIds: string[],indicateIds: string[],writeIds: string[],readIds: string[]}
协商设置蓝牙最大传输单元
本接口仅支持在安卓系统下调用,iOS 因系统限制不支持。
接口定义
deviceAdapter.setBLEMTU({mtu: number}) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
mtu | 最大传输单元。设置范围为 (22,512) 区间内,单位为 bytes。 | number | 是 |
读取指定特征值的二进制数据
接口定义
deviceAdapter.readBLECharacteristicValue({serviceId?: string,characteristicId: string}) => Promise<void>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
serviceId | 可选,默认为主服务 ID。 | string | 否 |
characteristicId | 需要读取的特征值 ID,默认会取主服务下的第一个 read 特征值。 | string | 是 |
返回值
返回一个 Promise。接口读取到的信息需要在
onBLECharacteristicValueChange
方法注册的回调中获取,具体参见 wx.readBLECharacteristicValue。获取蓝牙设备信号强度
接口定义
deviceAdapter.getBLEDeviceRSSI() => Promise
返回值
返回一个 Promise,具体数据结构请参见 wx.getBLEDeviceRSSI。
启用特征值变化时的 notify 功能
接口定义
deviceAdapter.notifyBLECharacteristicValueChange({characteristicId?: string,serviceId?: string,state?: boolean}) => Promise<void>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
serviceId | 需要订阅的服务 ID,默认会取主服务 ID。 | string | 否 |
characteristicId | 需要订阅的特征值 ID,默认会取主服务下的第一个 notify 或 indicate 特征值。 | string | 否 |
state | 是否启用 notify,默认为 true。 | boolean | 否 |
返回值
返回一个 Promise。
写入二进制数据到指定特征值中
接口定义
deviceAdapter.write(hexString: string, options?: {writeId?: string,serviceId?: string}) => Promise
参数说明
监听
参数名 | 参数描述 | 类型 | 必填 |
hexString | 需要写给蓝牙设备的十六进制字符串。 | string | 是 |
options.writeId | 可选,需要写入的特征值 ID,默认会取主服务下的第一个 writeId。 | string | 否 |
options.serviceId | 可选,需要写入的服务 ID,默认会取主服务 ID。 | string | 否 |
监听事件
接口定义
deviceAdapter.on(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要监听的事件。 | string | 是 |
listener | 事件触发时的回调函数。 | (...args) => void | 是 |
取消监听事件
取消监听设备适配器事件。
接口定义
deviceAdapter.off(type: string, listener: (...args) => void) => void
参数说明
参数名 | 参数描述 | 类型 | 必填 |
type | 要取消监听的事件。 | string | 是 |
listener | 要取消监听的事件的回调函数,不传则清除该事件的所有回调函数。 | (...args) => void | 否 |
设备适配器事件
connect 事件:设备连接后触发。
disconnect 事件:设备断开后触发。
message 事件:当收到
onBLECharacteristicValueChange
回调,并经过 handleBLEMessage
处理后触发。参数名 | 参数描述 | 类型 |
timestamp | 收到设备消息的时间戳,单位毫秒。 | number |
dataReported | 收到设备的消息是否已上报云端。 | boolean |
(其他) | handleBLEMessage 函数返回的其他参数将会透传到 message 事件中。 | any |
bLEConnectionStateChange 事件:当
onBleConnectionStateChange
触发时触发,若 connected
为 true,则接下来会触发 connect
事件,否则会触发 disconnect
事件。参数名 | 参数描述 | 类型 |
connected | 设备是否连接。 | boolean |
标准蓝牙协议
LLSync 标准蓝牙协议设备的绑定流程在小程序中进行,开发者只需在自定义 H5 面板中关注设备的连接、控制操作与事件监听。自定义 H5 面板已默认添加 LLSync 标准蓝牙协议的设备适配器(StandardDeviceAdapter),支持通过 LLSync 标准蓝牙协议与设备通信。H5 面板 Demo 中提供了 标准蓝牙协议 demo 供开发者参考。
搜索并连接设备
与标准蓝牙协议设备建立连接的过程分为三个步骤:搜索设备、连接设备、连接鉴权。示例代码如下:
import { StandardDeviceAdapter } from 'qcloud-iotexplorer-h5-panel-sdk';// 初始化蓝牙适配器await sdk.blueToothAdapter.init();// 搜索设备const deviceInfo = await sdk.blueToothAdapter.searchDevice({deviceName: sdk.deviceName,serviceId: StandardDeviceAdapter.serviceId,productId: sdk.productId,disableCache: true,});if (!deviceInfo) {throw new Error('未搜索到设备');}// 连接设备const deviceAdapter = await sdk.blueToothAdapter.connectDevice({...device,productId: sdk.productId,});// 连接鉴权if (!deviceAdapter.authorized) {await deviceAdapter.authenticateConnection({deviceName: sdk.deviceName,});}
设备通信
通过上述流程与设备建立连接后,H5 面板即可控制设备,接收设备的属性、事件上报。
控制设备
接口定义请参见 控制设备属性,示例代码如下:
sdk.controlDeviceData({// 要控制的设备属性power_switch: 1});
监听设备事件
接口定义请参见 事件监听,示例代码如下:
// 监听设备属性上报sdk.on('wsReport', ({ deviceId, deviceData }) => {console.log('device', deviceId, 'report_property', deviceData);});// 监听设备事件上报sdk.on('wsEventReport', ({ deviceId, Payload }) => {console.log('device', deviceId, 'report_event', Payload);});
设备适配器属性
属性名 | 属性描述 | 类型 |
explorerDeviceId | 只读,设备在物联网开发平台的 DeviceId。 | string |
isConnected | 只读,当前是否已连接设备。 | boolean |
deviceId | 只读,小程序蓝牙接口提供的 deviceId。 | string |
serviceId | 只读,设备的主服务 ID,与构造函数上的静态属性 DeviceAdapter.serviceId 一致。 | string |
originName | 只读,设备的原始名称,即小程序接口搜索出来时的 name 字段。 | string |
bleVersion | 只读,LLSync 协议版本号。 | number |
mtu | 只读,设备要求设置的最大传输单元 (MTU) 大小。 | number |
otaVersion | 只读,设备固件版本号。 | string |
extendInfo.macStr | 只读,设备的 mac 地址。 | string |
authorized | 只读,是否与设备完成鉴权。 | boolean |
BLE + WIFI 双路通信
针对 Wi-Fi + BLE Combo 模组,提供设备端 SDK 和 H5 SDK,支持设备 Wi- Fi 离线状态下,小程序通过 LLSync 标准蓝牙协议与设备通信,为用户提供 Wi-Fi 断网下的更佳体验。设备端 SDK 请参考 开发指引。
对于自定义 H5 面板,配网流程无需开发者关注,开发者需要在面板中关注:
1. 监听设备在线状态,wifi 连接是否正常;
2. 当设备离线时启用蓝牙进行通信。下面分开说明。
监听设备在线状态
sdk.on('wsStatusChange', ({deviceId, deviceStatus}) => {if (deviceStatus === 0) {// 设备已离线,开始启用蓝牙连接进行通信,见第二步}})
启用蓝牙通信
STEP1: 添加 BleComboDualModeDeviceAdapter4H5
import { BleComboDualModeDeviceAdapter4H5 } from 'qcloud-iotexplorer-appdev-plugin-wificonf-blecombo/lib/protocols/BleComboDualMode';const sdk = window.h5PanelSdk;BleComboDualModeDeviceAdapter4H5.injectOptions({ appDevSdk: sdk.appDevSdk });sdk.blueToothAdapter.addAdapter(BleComboDualModeDeviceAdapter4H5, true);
STEP2: 搜索设备
await blueToothAdapter.init();console.log('开始搜索设备', sdk.deviceName);const deviceInfo = await blueToothAdapter.searchDevice({deviceName: sdk.deviceName,serviceId: BleComboDualModeDeviceAdapter4H5.serviceId,productId: sdk.productId,disableCache: true,});
STEP3: 连接设备
const deviceAdapter = await blueToothAdapter.connectDevice({...device,productId: sdk.productId,});console.log('deviceAdapter:', deviceAdapter);// authorized之后,才能向设备发送控制数据if (!deviceAdapter.authorized) {await deviceAdapter.authenticateConnection({deviceName: sdk.deviceName,});}
当小程序和设备间的蓝牙连接成功后,面板就可以对设备进行控制了,sdk会将控制数据通过蓝牙发送到设备。比如进行开关的控制:
sdk.controlDeviceData({ power_switch: 1 });
ASR 语音识别
语音识别
目前支持两种场景,分别为“录音文件”与“一句话识别”,两种场景下入参会有所不同。
由于识别过程是异步,因此接口“voiceRecognition”并不会立即返回识别结果,可以理解为该接口是创建了一个“异步任务”,当这个成功被创建的“异步任务”执行完后,会通过 websocket 将结果推送到所有订阅该 deviceId 的终端上,下文为您详细介绍 ASR 语音识别。
voiceRecognition
接口定义
sdk.voiceRecognition({...}) => Promise<{...}>
参数说明
关于“录音文件”场景支持的音频类型、大小限制以及相关字段的详细介绍,详情请参见 录音文件识别。
关于“一句话识别”场景支持的音频类型、大小限制以及相关字段的详细介绍,详情请参见 一句话识别。
公共参数
参数名 | 参数描述 | 类型 | 必填 |
DeviceId | 默认使用当前设备的设备 ID。 | string | 否 |
AudioType | 识别场景。 “录音文件”取值“file”。 “一句话识别”取值“sentence”。 | string | 是 |
Data | 音频文件。 | Blob | File | 是 |
ResourceName | 文件名称,如果 Data 类型是 File,则取其“name”作为默认值。 | string | 否 |
EngineType | 引擎模型类型,默认值为“16k_zh”。 | string | 否 |
FilterDirty | 是否过滤脏词。 | number | 否 |
FilterModal | 是否过滤语气词。 | number | 否 |
FilterPunc | 是否过滤标点符号。 | number | 否 |
ConvertNumMode | 是否进行阿拉伯数字智能转换。 | number | 否 |
录音文件额外参数
参数名 | 参数描述 | 类型 | 必填 |
ChannelNum | 语音声道数,默认为1。 | number | 否 |
SpeakerDiarization | 是否开启话者分离。 | number | 否 |
SpeakerNumber | 话者分离人数。 | number | 否 |
返回值说明
参数名 | 参数描述 | 类型 |
ResourceToken | 某个设备下,音频文件的唯一标示。 | string |
监听识别结果 - asrResponse
对于“录音文件”场景,如果音频文件过大,后台可能会对音频文件进行分片识别,每个分片识别完成后,都将推送一条 websocket 消息,但推送的消息不保证顺序(例如有可能分片2的结果先到达)。
对于“asrResponse”事件,实际是基于“wsControl”事件进行二次封装;当然,您也可以通过监听“wsControl”事件获取识别结果。
接口定义
sdk.on('asrResponse', ({ deviceId, data }) => void)
返回值说明
参数名 | 参数描述 | 类型 |
deviceId | 设备 ID。 | string |
data | 识别结果数据。 | object |
data.resource_token | 某个设备下,音频文件的唯一标示。 | string |
data.result_code | 状态码,0代表成功。 | number |
data.total_num | 分片总数。 | number |
data.seq | 当前分片序号。 | number |
data.res_text | 当前分片识别结果,对于“录音文件”场景,识别结果会包含分段时间戳。 | string |
获取语音文件下载链接(仅限“录音文件”场景)
接口定义
sdk.getAsrDownloadUrl({...}) => Promise<{...}>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
DeviceId | 设备 ID。 | string | 是 |
ResourceToken | 调用 voiceRecognition 返回的 ResourceToken。 | string | 是 |
返回值说明
参数名 | 参数描述 | 类型 |
ResourceURL | cos 访问链接。 | string |
TRTC音视频
腾讯云物联网开发平台实时音视频服务,调用该接口从 h5 跳转至腾讯连连小程序 TRTC 页面。
接口定义
sdk.TRTCManager.goTRTCPage()
参数说明
参数名 | 参数描述 | 类型 | 必填 |
callType | 呼叫类型: video | audio | string | 是 |
音乐服务
公共说明
获取实例
const tmeSdk = await sdk.getTMESdk();
接口通用返回
接口统一返回值
TMESDK接口调用的返回值统一为
Promise<TMEResponse>
类型interface TMEResponse {error_code: number,error_msg: string,data?: any;}
调用成功:返回一个 resolved 的 Promise,其值为 TMEResponse 类型,error_code=0,data 为返回结果。
调用失败:返回一个 rejected 的 Promise,包含错误码(error_code)及提示信息(error_msg)。
属性名 | 描述 | 类型 |
error_code | 错误码。 | number |
error_msg | 错误信息。 | string |
data | 响应数据。 | object |
错误码列表
错误码 | 说明 |
200001 | 参数错误。 |
200002 | 系统繁忙,如幂等接口并发调用等,通常由于用户并发操作造成。 |
200003 | 认证信息过期或错误,请重新登录。 |
200004 | 设备未激活。 |
200005 | 当前 sp 暂未支持此接口。。 |
200006 | 系统错误,如内部调用超时等,由于服务内部异常导致 |
200200 | 可直充剩余次数为0。 |
400000 | 登录授权失败。 |
400001 | 设备端超时无响应。 |
400002 | 调用 SDK 参数错误。 |
登录授权部分
用户设备登录授权
跳转酷狗音乐小程序授权,当再次返回h5时,Promise状态改变。
接口定义
tmeSdk.login(deviceId?: string) => Promise
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
。用户设备登出
原 token 将登出。
接口定义
tmeSdk.logout(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
校验设备授权
接口定义
tmeSdk.checkDeviceAuth(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
获取用户信息
接口定义
tmeSdk.getUserInfo(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
,其中 data 如下:属性名 | 描述 | 类型 |
userid | 用户id | string |
nick_name | 用户昵称 | string |
img | 用户头像 | string |
is_vip | 是否vip 0:否 1:是 | enum: 0 1 |
vip_end_time | vip有效期终止时间 | string |
car_vip_end_time | 车机会员有效期终止时间 | string |
svip_end_time | 豪V有效期终止时间 | string |
播控部分
接口描述
调用播控SDK,会下发物模型属性+control_seq,需要设备上报相同的control_seq。
若在超时范围内收到上报,视为下发播控成功,返回resolved状态的
Promise<TMEResponse>
若超时未收到上报,返回rejected状态的
Promise<TMEResponse>
超时设置可以通过
tmeSdk.config.timeout
来配置,默认值为10000,单位:毫秒(ms)。通用播控接口
接口定义
tmeSdk.controlKugouDeviceData(deviceData, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceData | 设备物模型数据。 | object | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
播放
接口定义
tmeSdk.play(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
暂停
接口定义
tmeSdk.pause(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
上一首
接口定义
tmeSdk.preSong(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
下一首
接口定义
tmeSdk.nextSong(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
设置播放模式
接口定义
tmeSdk.setPlayMode(playMode: number, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
playMode | 播放模式:0:顺序播放。 1:单曲循环。 2:随机播放。 | enum: 0 1 2 | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
设置音量
接口定义
tmeSdk.setVolume(volume: number, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
volume | 音量:0-100之间。 | number | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
设置播放进度
接口定义
tmeSdk.setPlayPosition(playPosition: number, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
playPosition | 播放进度:单位:秒(s)。 | number | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
设置播放质量
接口定义
tmeSdk.setPlayQuality(recommendQuality: number, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
recommendQuality | 播放质量:0:标准 1:高清 2:无损 | enum: 0 1 2 | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID | string | 否 |
返回值
返回一个
Promise<TMEResponse>
设置当前播放歌曲
接口定义
tmeSdk.playSong(songId: string, songIndex: string, newQueueType: string, newQueueId: string | number, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 参数描述 | 类型 | 必填 |
songId | 歌曲 ID。 | string | 是 |
songIndex | 歌曲所在播放列表的位置,从0开始。 | number | 是 |
newQueueType | 播放列表的类型: playlist newSongs recommendDailty | string | 是 |
newQueueId | 播放列表ID(当类型为"每日推荐"时,不存在id,传 undefined ) | string | number | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
播放列表目前支持三种类型:歌单(playlist)、新歌首发(newSongs)、每日推荐(recommendDaily)
返回值
返回一个
Promise<TMEResponse>
内容部分
拉取内容通用接口
请求酷狗API拉取内容通用接口。
接口定义
tmeSdk.requestTMEApi(action: string, params, deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 描述 | 类型 | 必填 |
action | 接口 action。 | string | 是 |
params | 请求参数。 | object | 否 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
获取设备当前播放歌曲
接口定义
tmeSdk.getCurrentPlaySong(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
,data 为歌曲信息。获取设备当前播放列表
根据目前支持的播放类型(playType),拉取对应的歌单列表,并查出歌曲的详细信息。
接口定义
tmeSdk.getCurrentPlayQueue(deviceId?: string) => Promise<TMEResponse>
参数说明
参数名 | 描述 | 类型 | 必填 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
TMEResponse 中 data 如下:
属性名 | 描述 | 类型 |
playType | 播放列表类型。 | enum: playlist newSongs recommendDaily |
queueId | 当前播放列表 id,根据 playType 对应 playlist_id、album_id、top_id。 | string | number |
total | 列表中歌曲总数。 | number |
songs | 歌曲数组,具体歌曲属性参考 TME 文档中 Song 属性。 | Array[] |
获取歌曲详细信息
接口定义
tmeSdk.getSongDetail(songId: string, deviceId?: string) => Promise<TMEResponse>
通过调用 requestTMEApi,请求歌曲播放链接与歌曲信息,返回歌曲的详细信息。
参数说明
参数名 | 描述 | 类型 | 必填 |
songId | 歌曲 ID。 | string | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
,data 为歌曲信息。获取歌单详细信息
接口定义
tmeSdk.getPlaylistDetail(action: string, params, deviceId?: string) => Promise<TMEResponse>
通过调用 requestTMEApi,请求歌单列表与歌曲信息,丰富列表中的歌曲信息,返回歌单列表。
参数说明
参数名 | 描述 | 类型 | 必填 |
action | 新歌首发(awesome_newsong)、每日推荐(awesome_everyday)、歌单歌曲(playlist_song)。 | string | 是 |
params | 参考应用端 API=>音乐服务中对应 API 的 KugouParams。 | object | 是 |
deviceId | 可选,不传则使用当前设备的设备 ID。 | string | 否 |
返回值
返回一个
Promise<TMEResponse>
,data 为歌单列表。蓝牙设备调用微信背景音乐
说明:
蓝牙设备可在自定义 H5 面板中,调用微信背景音乐接口。
应用场景:开发者可通过 BT+BLE 的蓝牙设备对接到连连小程序,在 H5 页面中,BLE 作为播控的通道,通过小程序到手机端的 BT 链路进行音乐播放。
获取实例
const bam = await h5PanelSdk.wxapi.getBackgroundAudioManager();
获取属性
获取 BackgroundAudioManager 实例的属性。
接口定义
bam.getBackgroundAudioAttribute(keys: Array<string>) => Promise<any>
参数说明
参数名 | 描述 | 类型 | 必填 |
keys | 属性名数组。 | Array<string> | 是 |
设置属性
设置 BackgroundAudioManager 实例的属性。
接口定义
bam.setBackgroundAudioAttribute(parmas: Object) => Promise<any>
参数说明
参数名 | 描述 | 类型 | 必填 |
params | key 为属性名称,value 为属性值。 | Object | 是 |
其他方法
所有 api 使用方法与微信官方文档相同。
使用示例
// 播放音乐bam.setBackgroundAudioAttribute({title: '歌曲名称',singer: '歌手',epname: '专辑名',src: 'https://***.mp3',coverImgUrl: 'https://***.png',});// 事件监听bam.onTimeUpdate((currentTime) => {// 更新播放进度setCurrentTime(currentTime);});
底层 SDK 能力
应用开发 SDK
接口定义
sdk.appDevSdk
微信 JSSDK
接口定义
sdk.wx
初始化 JSSDK
接口定义
sdk.wxSdkReady() => Promise
返回值
返回一个带缓存的 Promise,初始化成功后 resolve。若初始化未完成或已初始化成功,则多次调用后返回同一个 Promise。若初始化失败,则该缓存的 Promise 在 reject 之后会被释放,再次调用则将重新初始化。
示例代码
sdk.wxSdkReady().then(() => wx.miniProgram.navigateBack());