小程序 API

精灵小程序是在支付宝小程序的基础上，增加了语音、视觉等能力。小程序基础的API，请参考：支付宝小程序的API

以下是天猫精灵扩展的 API：

playTTS

• API： my.tg.playTTS
• 功能：播放 TTS
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | content | String | 是 | tts 播报的内容, string 类型 | | openMic | Boolean | 否 | 是否在播报结束后开麦，默认 false |

• 使用示例：

  my.tg.playTTS({
  content: '请问你要选第几个', 
  openMic: true
  });

nlpRequest

• API： my.tg.nlpRequest
• 功能：模拟语音请求
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | text | String | 是 | 模拟语音请求的内容 |

• 使用示例：

  my.tg.nlpRequest({
  text: "今天天气",
  });

getGenieUserInfo

• API： my.call(“getGenieUserInfo”)
• 功能：获取精灵账号信息
• 使用示例：

my.call('getGenieUserInfo', function(result) {
      my.alert({
        content: JSON.stringify(result)   // nickName和userOpenId
      })
  })

getGenieSerialNo

• API： my.call(“getGenieSerialNo”)
• 功能：获取精灵的设备序列号
• 使用示例：

my.call('getGenieSerialNo', function(result) {
      my.alert({
        content: JSON.stringify(result)   //serialNo
      })
  })
result:
 code: "0" 成功， "-1" 取消授权
{"code":"0", "serialNo":"GIYPQ8KFTOHUAEPN"}

注：414版本开始支持，421版本有机器获取此接口异常，升级到423功能正常。

keepScreenOn

• API: my.call(“keepScreenOn”)
• 功能：设置小程序屏幕是否保持常亮
• 参数

使用示例：

my.call('keepScreenOn', {
      "enable": "false"  // 默认小程序应用会保持屏幕常亮，"true"为保持屏幕常亮，"false"为关闭屏幕常亮
    },function(result) {
      my.alert({
        content: JSON.stringify(result)
      })
    })

返回值示例:

{
  "code":"0", // code:0 成功
  "msg":"success"
}

hideNavigationBar

• API：my.call(‘hideNavigationBar’)
• 功能：隐藏顶部导航栏

showNavigationBar

• API: my.call(‘showNavigationBar’)
• 功能：显示顶部导航栏

sendKeyEvent

• API: my.call(“sendKeyEvent”)
• 功能：模拟物理按键
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | keyCode | String | 是 | 键值，当前仅支持 BACK、HOME 两种键值 | | | | | |

• 使用示例：

  my.call("sendKeyEvent", {"keyCode": "BACK"})

useSystemSkill

• API: my.call(“useSystemSkill”)
• 功能：使用系统自带技能
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | skillName | String | 是 | 系统内置技能的名字，目前可选值有：chat |

当前系统内置的技能说明：

• 使用示例

1. 在 Page的onShow 方法中，设置技能配置 ```javascript Page({

   onShow() { my.call(‘useSystemSkill’, { skillName: ‘chat’ }) },

});

2. 在 page 的 onVoiceEvent 中语音操作的指令：
```javascript
Page({
  onShow() {
    my.call('useSystemSkill', {
      skillName: 'chat',
    })
  },
  //默认的语音指令回调
  onVoiceEvent(event){
    my.alert({content: "onVoiceEvent = " + JSON.stringify(event)}); 
  },
});

1. 假设此时用户说 “天猫精灵，风和日丽” , onVoiceEvent 回调中的 event 的数据格式如下，其中的 query 就是原生的 ASR

   {
   "command":"NluResult",
   "domain":"AliGenie.Text",
   "param":{
    "domain":"小程序技能chat",
    "intent":"sys.fallback",
    "query":"风和日丽",
    "slots":[]
   }
   }

useCustomSkill

• API: my.call(“useCustomSkill”)
• 功能：使用自定义技能
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | skillName | String | 否 | 技能的名字，默认值为小程序的 appid | | secretKey | String | 是 | 技能的 secretKey，从技能开放平台创建的技能中获取 | | pageId | String | 否 | 指定页面 id，和技能开放平台中的页面意图配置相匹配，会优先使用页面绑定的意图 |

• 使用示例

1. 在 Page 的 onShow 方法中，设置技能配置 ```javascript Page({

   onShow() { my.call(‘useCustomSkill’, {

    secretKey: 'your secretKey',
    pageId: 'pages/index/index'

   }) },

});

<a name="startNativeApp"></a>
## startNativeApp
- API： my.call('startNativeApp')
- 功能：启动 Native 应用
- 参数
| 属性 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uri | String | 否 |  |
| 启动 Activity 的 Uri |  |  |  |
| action | String | 否 | 启动 Activity 时，设置的 action 参数，默认为"android.intent.action.VIEW" |
| param | String | 否 | 传给要启动的Activity的Intent extra参数. 子参数将通过 putExtra 方式添加进 Intent 中，可通过 getStringExtra()方法获取，(注意: 所有子参数类型必须都是 String 类型) |
- 使用示例:
```javascript
my.call('startNativeApp', {
  // 通过URI的方式 start Activity: 启动通讯录
  uri: 'genie://com.alibaba.ailabs.genie.contacts/page/home',
  param: {// 可选，传入intent中的extra中的参数，注意必须为String类型
    "extra1": "value1",
    "interger": "1",
    "extra2": "Hello native app",
  }
},
function(result) {
  my.alert({
    content: JSON.stringify(result)
  })
})

getGenieDeviceInfo

• API: my.call(“getGenieDeviceInfo”)
• 功能：获取设备信息
• 使用示例:

  my.call('getGenieDeviceInfo', function(result) {
  my.alert({
    content: JSON.stringify(result)
  })
  })

{
  "code":"0",
  "data":{
      "uuid":"real uuid" // 设备uuid
  },
  "msg":"Success"
}

commitHit

• API: my.call(“commitHit”)
• 功能：埋点
• 参数

• 使用示例:

如埋点需求为：
1）事件类型：点击
2）埋点参数：接口已埋无需填入的字段无需业务方埋入

my.call('commitHit', {
      type:"controlClickEvent",
      param: {
        "tab_id": "testStr1",
        "tab_name": "testStr2",
      }
    },
      function(result) {
        my.alert({
          content: JSON.stringify(result)
        })
      });

返回值示例:

{
  "code":"0",
  "msg":"Success"
}

showAdvertise

• 使用此接口前请先邮件申请：tmjlcc_genie@service.alibaba.com

邮件标题：开发者名称+应用名称
邮件正文：
1、应用名称和简介
2、开发者简介和联系方式（钉钉）
3、申请广告接口的使用方式

• API： my.call(“showAdvertise”)
• 功能：展示广告（可展示两种类型广告，视频广告及banner广告，业务方咨询达萌按需接入）
• 入参： | 属性 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | type | String | 是 | 广告类型，目前有两种（全屏视频广告【投放横屏或竖屏】、banner广告）见广告样式 | | position | String | 否 | banner位置，目前有top、bottom两种，默认bottom（仅在type为banner时生效） | | backgroundColor | String | 否 | banner背景色，目前有black、white两种，默认black（仅在type为banner时生效） | | style | String | 否 | banner样式，目前有3图（three）、大图（big）、小图（small）三种，默认大图（仅在type为banner时生效） | | frequency | String | 否 | banner类型广告刷新频率，目前有三种刷新时长short、middle、long（10s、15s、20s），默认short（仅在type为banner时生效） |

• response： | 回调方法 | 类型 | 必填 | 说明 | | —- | —- | —- | —- | | success | String | 是 | 播放视频广告完成时返回 | | fail | String | 是 | 播放视频广告未完成时返回 |

• 广告样式：

视频广告（横屏）全屏

banner小图（small、black、bottom）【488*108】

banner大图（big、black、bottom）【556*108】

banner三图（ three、top、white）【428*144】

• 使用示例：

banner广告位

my.call('showAdvertise', {
      type: 'banner',
      position:'bottom',
      backgroundColor:'black',
          style:'three',
          frequency:'long',
    },
      function(result) {
        my.alert({
          content: JSON.stringify(result)
        })
   });

视频广告位

my.call('showAdvertise', {
      type: 'video',
    },
      function(result) {
        my.alert({
          content: JSON.stringify(result)
        })
    });