# 1 文档说明
本文档适用于高德具身智能机器狗接入支付宝支付，包括输出产物、API接口说明和交互流程。
## 1.1 支付宝输出产物
| **平台** | **产物** | **功能与说明** |
| --- | --- | --- |
| Android | 支付宝PhoneSDK | 支付宝智能体业务和支付、核身逻辑处理 |
| IOS | 支付宝PhoneSDK | 同安卓 |
| Linux | 扫码SDK | 支付宝扫码算法封装，支持一二维码扫描 |
## 1.2 功能列表
+ 看一下支付：机器狗扫码，用户语音支付；
+ 一方智能体业务：充话费、点咖啡等;
+ GPaas业务：城市导览、轻社交、阿福等，详询大安全BD同学；
## 1.3 系统框图
# 2 接口说明
主要接口类：**AlipayGlassV2Sdk**
#### 2.1 initSDK初始化
```java
AlipayGlassV2Sdk.initSDK(extParams, new GlassSDKCallback() {
//开启录音，发起绑定后回调，开启后需要在receiveDenoiseAudio传入降噪音频
@Override
public void onStartRecording(String token) {
//startRecordAudio(true);
}
@Override
public void onStopRecording() {
//startRecordAudio(false);
}
//播放支付过程提示文案
@Override
public String onStartPlayback(String ttsData) {
return null;
}
//佩戴状态检测
@Override
public boolean onWearDetection() {
return true;
}
@Override
public void onErrorEvent(String code, String message) {
//错误回调
//○ Q1010/1011:sdk调用initCloudEnv失败，或者wss建联失败；收到此错误码仅需播音提示用户。
//○ Q9990:glassSDK已释放退出
}
@Override
public void onViIntentResult(String bizType, String dataJson, Map extInfo) {
//核身和意图回调：厂商按需处理
}
});
```
初始化SDK，在手机App和耳机建立连接时调用，支持重复调用；
入参：（入参key详见GlasspayConfig.java中定义）
| **参数key** | **类型** | **含义** | **是否必填** | **备注** |
| :--- | :--- | :--- | :--- | --- |
| isvName | String | 厂商名称 | 是 | |
| deviceModel | String | 设备机型 | 是 | |
| deviceSN | String | 设备SN | 是 | |
| productType | String | 产品类型 | 否 | 耳机或无摄像头眼镜时，传"earphones" |
:::warning
支付过程中部分音频数据需要录制成音频，部分语音需要在线合成TTS，需要注意语音播报需要互斥，新的语音指令需要打断前序的播报，以避免在线TTS慢导致的语音排队问题
:::
#### 2.2 getBindStatus
获取设备的绑定状态；在手机端展示绑定状态 或者每次发起支付前调用；若未绑定，提示用户去厂商App中进行绑定；
+ needCloudStatus=true, 查询云端状态，一般填true;
+ needCloudStatus=false, 查询本地缓存状态；
| **字段** | **类型** | **说明** | **示例** |
| --- | --- | --- | --- |
| isBinded | boolean | 账号绑定状态；（基本废弃，厂商根据featureStatusList判断服务是否开通） | true/false |
| extInfo | Map | 扩展信息 | |
| -featureStatusList | String | 服务开通状态,若已开通则同时返回对应的manageUrl。各服务编码说明：
("PAYMENT", "支付")(含充话费、点咖啡等)
("CAR_PARKING", "停车缴费"),
("CAR_PARKING_MESSAGE", "停车缴费消息"),
("CITY_SIGHTSEEING", "城市导览"),
| featureStatusList":["{\"featureId\":\"CAR_PARKING\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"QUICK_MODE\",\"status\":\"STATUS_UNBIND\"}","
{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\", \"manageUrl\":\"http:xxx\"}","{\"featureId\":\"PAY_DEMO\",\"status\":\"STATUS_BIND\"}"]}
注：若服务从未开通过，则列表不展示 |
| |-verifyMethodStatus | 核身方式录入状态 | VERIFY_VOICE | OPEN，表示已录入 |
#### 2.3 startBinding
```java
AlipayGlassV2Sdk.startBinding(map, new BindingCallBack() {
@Override
public void onGetBindingSchemeSuccess(String bindingScheme, String token) {
//收到支付宝绑定页面，跳转scheme
}
@Override
public void onBindingSuccess() {
//绑定完成
}
@Override
public void onBindingFailed(String errorCode) {
//绑定失败
}
});
```
开始绑定，用户点击手机上的【开始绑定】按钮时调用；
入参：(详见GlasspayConfig.java中定义）
| **参数key** | **类型** | **含义** | **是否必填** | **备注** |
| :--- | :--- | :--- | :--- | :--- |
| returnUrl | String | 绑定完成后的回跳地址 | 否 | 优先级高于callback中的getReturnUrl |
| sourceFrom | String | 发起开通的服务入口 | 是 | ("PAYMENT", "支付")(含充话费、点咖啡等支付业务)，
("CAR_PARKING", "停车缴费"),
("CITY_SIGHTSEEING", "城市导览"), |
#### 2.4 receiveDenoiseAudio
接受降噪音频传入，格式要求：pcm，单声道，16000采样率，16位深(AV_SAMPLE_FMT_S16)；
+ 绑定阶段：当进入支付宝小程序读文案界面时，会回调onStartRecord，此时打开麦克风，上传音频；
+ 支付阶段：识别智能体或支付意图时，调用startAlipayService接口，同时将用户这句唤醒语也调用receiveDenoiseAudio传入；
##### 唤起语上传
唤起语料厂商先做缓存，当识别到支付意愿调用scanpay接口时，同时把唤起语音进行上传；在扩展字段中填写
extParams.put("flowNode", "AROUSE");
:::warning
注意：唤起语音频上传要在startAlipayService/scanpay之后才有效
:::
#### 2.5 unbind
解绑支付宝账号，仅清除设备本地缓存uid tid信息；
厂商手机App端解绑按钮建议跳转到支付宝小程序设备页面，进行解绑。
#### 2.6 command
发送指令，比如用户点击耳机或眼镜的返回按键、摘下耳机/眼镜等时机调用；
入参：(详见GlasspayConfig.java中定义）
| **参数key** | **类型** | **含义** | **是否必填** | **备注** |
| :--- | :--- | :--- | :--- | :--- |
| commandCode | int | 指令编码 | 是 | 0:表示退出
1：表示按键命令 |
| keyCode | int | 具体按键值 | 否 | |
| source | String | 命令来源 | 否 | 摘下、双击退出键等 |
当摘掉耳机或眼镜时，退出支付流程
```java
params.put(GlasspayConfig.KEY_COMMAND_CODE, GlasspayConfig.CommandCode.EXIT);
params.put("source", "wearOff");
AlipayGlassV2Sdk.command(params);
```
#### 2.7 getCustomInfoV2
```java
void getCustomInfoV2(final Map params, CustomInfoCallback callback)
```
获取客制化的自定义信息；
入参：1)params:表示要获取信息的key, value按需填写; 2)customInfoCallback:返回指定keys的查询信息；
出参：CustomInfoCallback的onCustomInfo中返回要查询的信息；
keys取值如下：
| **参数key** | **参数Val** | **含义** | **备注** |
| :--- | :--- | :--- | :--- |
| AlipayAppDownloadUrl | "" | 支付宝App下载地址 | 绑定时，若用户手机未安装支付宝，则提示其下载安装 |
| AlipayManageGlassPage | 填写对应来源,如
sourceFrom=PAYMENT/CAR_PARKING.... | 支付宝App对应的服务管理的小程序页面 | 若未安装支付宝则跳转到下载链接页面；
sourceFrom的服务与getBIndStatus返回的featureStatusList中的服务相同； |
| currentTradeUrl | "" | 当前交易订单的url地址 | 可跳转到支付宝订单详情页 |
| currentAlipayUid | "" | 内部用，获取uid | |
| glassDeviceSn | "" | 内部用，获取眼镜sn | |
| glassOnBinding | true | 眼镜是否在绑定中 | |
| glassOnPaying | false | 眼镜是否在支付中 | |
```plain
String customKeys = new HashMap();
customKeys.put("AlipayAppDownloadUrl", "");
customKeys.put("AlipayManageGlassPage", "sourceFrom=CAR_PARKING");
AlipayGlassV2Sdk.getCustomInfo(customKeys, new CustomInfoCallback() {
@Override
public void onCustomInfo(String data, Map extInfo) {
//data暂未使用； extInfo中为各个key对应的信息
}
});
```
#### 2.8 setWearingState
接口定义：public void setWearingState(boolean wearing)
入参：wearing=true表示设备戴上，false表示设备摘下；
调用时机：当设备佩戴状态发生变化时调用；
#### 2.9 startAlipayService
```java
String startAlipayService(final String appId, final String serviceCode, final Map params, final GAlipayCallback callback);
void stopAlipayService(final String appId, final String serviceCode, final Map params,
final String sessionId, final GAlipayCallback callback)
```
启动/停止支付宝服务，serviceCode为具体的服务编码；厂商侧调用 startAlipayService 同时需要开启回传音频,通过 receiveDenoise 回传，在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传;
入参：(详见GlasspayConfig.java中定义）
| **参数key** | **类型** | **含义** | **是否必填** | **备注** |
| --- | :--- | :--- | :--- | --- |
| PAY_INIT_ASR | String | 唤起语文本传入 | 是 | |
| orderStr | String | 外部订单号，需码路由 | 否 | 预下单后调用支付 |
| scene | String | 场景码 | 否(智能体场景需填写) | Coffee, //点咖啡
TopUp, //充话费
MovieTicket, //电影票 |
| locationLat | String | 地理位置-维度 | 否（咖啡必填） | 31.564343 |
| locationLnt | String | 地理位置-经度 | 否（咖啡必填） | 120.533231 |
| coordType | String | 经纬度对应坐标系 | 否（咖啡必填） | 高德：GCJ-02
百度：BD-09 |
| codeResultString | String | 外部码值 | 否 | 外部扫码得到支付宝码值
高德机器狗接入此项必传：
扫码sdk返回的加密二进制数据转成base64字符串后传入 |
| codeResultNeedDecrypt
| String | 码值是否需要解密 | 否 | 高德机器狗接入时此项需传"true" |
#### **2.10 日志重定向**
**接口：setLogger**
**功能：用于将支付SDK的日志重定向到厂商日志中，便于后续客户端问题排查；Log等级跟随厂商设置，一般release包设置为Info，debug包设置为Verbose;**
```json
public class AlipayLogger extends Logger {
@Override
public int verbose(String tag, String msg) {
//重定向输出到厂商log文件
return 0;
}
//。。。其他日志接口实现
}
com.alipay.glass.log.Log.setLogger(new AlipayLogger());
```
# 3 交互流程
## 3.1 用户动线
## 3.2 绑定流程
+ 绑定支付宝账号、录入声纹、开通支付
```puml
@startuml
skinparam separatorStyle thick
skinparam separatorColor #000000
autonumber
participant "厂商手机App" as ISVPhone #Technology
participant "支付SDK" as PAYSDK #Application
participant "手机支付宝App" as ZFBApp #Application
note right of 蓝牙通道
----
end note
'participant "眼镜小米App" as ISVGlass #Technology
participant "厂商耳机" as LauncherApp #Technology
participant "支付宝服务端" as OPENAPI
'participant "核身服务端" as HeShenServer #Application
'participant "厂商服务端" as ISVServer #Application
activate ISVPhone
ISVPhone->PAYSDK:initSDK初始化
ISVPhone->PAYSDK:查询绑定状态getBindStatus
PAYSDK->OPENAPI:queryBindStatus
OPENAPI->PAYSDK:绑定状态应答
PAYSDK->ISVPhone:返回绑定状态
alt
else 已绑定
ISVPhone -> ISVPhone: 显示"去支付宝管理"
else 未绑定
ISVPhone->PAYSDK:点击去绑定startBinding
PAYSDK->PAYSDK:initCloudEnv初始化\nstartBindingProcess串联核身
PAYSDK->OPENAPI:请求bindCode
OPENAPI->PAYSDK:返回bindCode
PAYSDK->ISVPhone:onGetBindingSchemeSuccess返回schema
ISVPhone -> ZFBApp:打开绑定小程序
ZFBApp->ZFBApp:用户绑定操作
PAYSDK->ISVPhone:onStartRecording开麦通知
ISVPhone->LauncherApp:打开麦克风
ISVPhone->PAYSDK:receiveDenoiseAudio送入音频
PAYSDK->OPENAPI:wss上传音频
loop
PAYSDK->OPENAPI:loop:轮询绑定状态
OPENAPI->PAYSDK:返回绑定状态
end loop
PAYSDK->ISVPhone:返回绑定结果
ISVPhone->LauncherApp:关闭麦克风
end alt
@enduml
```
**注：实际用户使用时，可能有两种形式**：
+ 用户佩戴耳机进行语音交互，全程不用掏手机；
+ 用户拿着手机，对语音助手摁住录音键说话并发送；
## 3.3 唤起支付和智能体业务
+ 通过厂商语音助手唤醒词，唤起智能体业务，如充话费、点咖啡、电影购票等；
### 3.3.1 机器狗领取咖啡
交互设计：[https://dmore.antgroup-inc.cn/preview/41400003/86500208?selectPage=29DD5C13-67E9-45EA-8060-CE830EAB7FEF&selectArtboard=E213E315-C97E-40F6-BA74-E0FF685B2CAE&display=all&canvasBg=DARK](https://dmore.antgroup-inc.cn/preview/41400003/86500208?selectPage=29DD5C13-67E9-45EA-8060-CE830EAB7FEF&selectArtboard=E213E315-C97E-40F6-BA74-E0FF685B2CAE&display=all&canvasBg=DARK)
+ 发起点咖啡服务调用
```plain
params.put("PAY_INIT_ASR", "帮我点一杯咖啡");
params.put(GlasspayConfig.KEY_SCENE, "Coffee");
params.put(GlasspayConfig.KEY_LOCATION_LONGITUDE, "120.104739");
params.put(GlasspayConfig.KEY_LOCATION_LATITUDE, "30.261124000000017");
AlipayGlassV2Sdk.startAlipayService("appId", selectedScene, params, new GAlipayCallback() {
@Override
public void onResponse(GAlipayResponse response) {
Log.i(TAG, "onResponseresponse=" + response);
}
@Override
public void onEvent(String eventId, String data, Map extra) {
Log.i(TAG, "onEvent, eventId=" + eventId + ",data=" + data + ",extra=" + extra);
}
});
```
+ 返回下单结果(地址、门店、取单号)
- onResponse返回结果信息：
```json
07-28 11:45:36.559 5665 5943 I TestPhoneCmdActivity: onResponseresponse=GAlipayResponse{code=1000, subCode='Q100000', subMsg='OK_SUCCESS', mResult='{eventData={"notificationUrl":"https://ur.alipay.com/_7qlgugFbslIgI7pFz7Imcq","notificationTitle":"瑞幸下单成功，取餐号：468","code":"468","address":"北京市西城区西单北大街131号","notificationMessage":"下单成功","shopName":"瑞幸咖啡（丰潭路站店）"}, resultCode=9000, memo=订单支付完成, eventType=onPayResult}', extInfo={}}
```
- initSDK#onEvent接口返回信息：
+ 示例：
[main5.log.zip](https://yuque.antfin.com/attachments/lark/0/2026/zip/198428/1783935640466-eb168504-33b2-4375-a4bb-7e80bfa34218.zip)
[main5 2.log.zip](https://yuque.antfin.com/attachments/lark/0/2026/zip/198428/1784102280114-cb0e37c8-7fd7-4aa8-b97e-77ee01acd660.zip)
[main5-onResponse返回门店.log.zip](https://yuque.antfin.com/attachments/lark/0/2026/zip/198428/1785209839785-895b6caa-e2ca-44e0-a9b3-111958937f91.zip)
# 4 接入前需要准备好的资源
:::warning
1. **需要收集厂商手机端集成SDK的应用签名md5和包名，做签名校验**
1. **Android拿到蓝盾签名图片后，放到对应的工程中的app主模块下的assets根目录下即可**
2. **iOS需要放在mainBundle里，图片名称需要为nearx_bs.jpg**
2. **搜集isvName和设备型号（model），服务端做对应配置，否则绑定阶段小程序无法跳转**
1. **若同时接入GPass业务，则对应服务端也需做对应配置；**
3. **支付宝网关侧对接入厂商需要配置appId，接入前需要做好配置**
:::
**信息提供模板：**
| **类别** | **厂商提供值** | **含义** | **备注** |
| --- | --- | --- | --- |
| isvName | amap_robotdog | 厂商名称 | |
| deviceModel | Abot-GD1、Abot-GD2 | 设备型号 | |
| 语音唤醒词 | 你好途途 | 语音助手唤醒词 | |
| 安卓apk包名 | com.amapbot.studio | | |
| 安卓apk签名 | MD5 digest: febb430940394bd81483965957409ac3 | | apksigner verify -verbose --print-certs |
| IOS包名 | | | |
| 鸿蒙包名 | | | |
# 5、结果回调示例
## 码支付结果互调
```json
07-28 15:25:16.159 13295 13295 I TestPhoneCmdActivity: onResponseresponse=GAlipayResponse{code=1000, subCode='Q100000', subMsg='OK_SUCCESS', mResult='{eventData={"amount":"0.01","currentTradeUrl":"alipays://platformapi/startApp?appId=20000090&actionType=toBillDetails&tradeNO=20260728020070011551440051138845","tradeNo":"20260728020070011551440051138845","success":true,"orderStatus":"PAY_STATUS_SUCCESS","currencyTypeName":"人民币","currency":"CNY","extInfo":{"wssPay":"false","flashPay":"false"},"payToken":"6588f32a84ca41f281b0209d5c1778f1","quickVerify":false}, resultCode=9000, memo=支付成功, eventType=onPayResult}', extInfo={}}
```
## 点咖啡结果回调
```json
07-28 11:45:36.559 5665 5943 I TestPhoneCmdActivity: onResponseresponse=GAlipayResponse{code=1000, subCode='Q100000', subMsg='OK_SUCCESS', mResult='{eventData={"notificationUrl":"https://ur.alipay.com/_7qlgugFbslIgI7pFz7Imcq","notificationTitle":"瑞幸下单成功，取餐号：468","code":"468","address":"北京市西城区西单北大街131号","notificationMessage":"下单成功","shopName":"瑞幸咖啡（丰潭路站店）"}, resultCode=9000, memo=订单支付完成, eventType=onPayResult}', extInfo={}}
```