小米穿戴第三方 APP 能力开放接口文档_v1.4

Aristore2024-09-212024-09-21

整理自小米穿戴第三方 APP 能力开放接口文档

手环小程序开放接口文档

1.4 版本更新日志

兼容 Android R

1.3 版本更新日志

兼容未来小米穿戴和小米健康合并项目，api 无变化，直接替换 sdk 即可

1.2 版本更新日志：

兼容 jdk1.7 版本，api 没有变化

1.1 版本更新日志：

修改状态订阅和状态查询相关接口返回值，详情请查看文档 3.2 和 3.3 部分
增加消息通知 api，详情请看文档第 5 部分

1. 查询已连接的可穿戴设备（不需要权限）

// 获取 NodeApi 对象
NodeApi api = Wearable.getNodeApi(context);

// 调用 getConnectedNodes 方法来获取所有已连接的设备
api.getConnectedNodes()
    .addOnSuccessListener(new OnSuccessListener<List<Node>>() {
        @Override
        public void onSuccess(List<Node> nodes) {
            // 处理已连接设备列表，注意：目前一次只能连接一个设备
            // 可以在这里添加逻辑处理，例如遍历 nodes 列表
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 处理获取已连接设备失败的情况
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

2. 权限查询与申请

2.1 查询授权状态

第一次调用授权会默认授予 Permission.DEVICE_MANAGER 和 Permission.Notify 权限

// 获取 AuthApi 对象
AuthApi authApi = Wearable.getAuthApi(context);

// 调用 checkPermission 方法获取某个权限的授权状态
authApi.checkPermission("nodeId", Permission.DEVICE_MANAGER)
    .addOnSuccessListener(new OnSuccessListener<Boolean>() {
        @Override
        public void onSuccess(Boolean result) {
            // 如果已授权，result 为 true；未授权，result 为 false
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 获取授权状态失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 定义一组权限
Permission[] permissions = new Permission[]{
    Permission.DEVICE_MANAGER,
    Permission.NOTIFY
};

// 调用 checkPermissions 接口查询一组权限的授权状态
authApi.checkPermissions("nodeId", permissions)
    .addOnSuccessListener(new OnSuccessListener<Boolean[]>() {
        @Override
        public void onSuccess(Boolean[] results) {
            // 如果已授权，results 中对应位置的值为 true；未授权，为 false
            // 按照请求顺序返回结果
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 获取授权状态失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

2.2 申请权限

// 获取 AuthApi 对象
AuthApi authApi = Wearable.getAuthApi(context);

// 发起授权申请
authApi.requestPermission("nodeId", Permission.DEVICE_MANAGER, Permission.NOTIFY)
    .addOnSuccessListener(new OnSuccessListener<Permission[]>() {
        @Override
        public void onSuccess(Permission[] permissions) {
            // 申请权限成功，返回授权成功的权限
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 申请权限失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

3. 设备管理与状态订阅

3.1 支持查询与订阅的设备状态

设备管理与状态订阅	查询结果	订阅事件触发条件	订阅结果
连接状态	1. 连接 2. 未连接	1. 手机与设备连接成功 2. 手机与设备断开连接	1. 连接成功 2. 连接断开 3. 连接失败 4. 设备被删除
电量状态	电量值（0~100，比如 98 ）	N/A	N/A
充电状态	1. 正在充电 2. 非充电状态	1. 给设备充电 2. 充满电 3. 停止充电	1. 开始充电 2. 充电完成 3. 停止充电
佩戴状态	1. 佩戴中 2. 未佩戴	1. 手表戴在手腕上 2. 摘下手表	1. 佩戴 2. 未佩戴
睡眠状态	1. 睡眠中 2. 清醒	1. 佩戴手表入睡 2. 从入睡状态清醒过来	1. 入睡 2. 出睡

3.2 状态查询（需要申请 Permission.DEVICE_MANAGER 权限）

// 获取 NodeApi 对象
NodeApi api = Wearable.getNodeApi(context);

// 调用 query 方法，查询不同状态，nodeId 通过查询已连接设备得到的设备 ID
// 目前支持查询（连接状态，电量状态，充电状态，佩戴状态，睡眠状态）
api.query("nodeId", DataItem.ITEM_CONNECTION)
    .addOnSuccessListener(new OnSuccessListener<DataQueryResult>() {
        @Override
        public void onSuccess(DataQueryResult result) {
            // 查询成功
            boolean connectionStatus = result.isConnected(); // DataQueryResult 定义了各种状态的状态值，和 DataItem 一一对应
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 查询失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 查询对应的穿戴设备端应用是否安装
api.isWearAppInstalled("nodeId")
    .addOnSuccessListener(new OnSuccessListener<Boolean>() {
        @Override
        public void onSuccess(Boolean result) {
            // 查询成功，应用已安装返回 true，未安装返回 false
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 查询失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 打开设备端应用
// uri 由各个应用自定义，用于打开手表端 app 的指定页面
api.launchWearApp("nodeId", "uri")
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            // 打开穿戴设备端应用成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 打开穿戴设备端应用失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

3.3 状态订阅（需要申请 Permission.DEVICE_MANAGER 权限）

// 获取 NodeApi 对象
NodeApi api = Wearable.getNodeApi(context);

// 创建监听器
OnDataChangedListener onDataChangedListener = new OnDataChangedListener() {
    @Override
    public void onDataChanged(@NonNull String nodeId, @NonNull DataItem dataItem, @NonNull DataSubscribeResult data) {
        // 收到订阅状态变更通知
        // 不同的 DataItem 对应 DataSubscribeResult 中不同的 status，一一对应
        if (dataItem.getType() == DataItem.ITEM_CONNECTION.getType()) {
            int connectionStatus = data.getConnectedStatus();
            if (connectionStatus == DataSubscribeResult.RESULT_CONNECTION_CONNECTED) {
                // 设备连接状态变更为已连接状态
                // 可以在这里添加相应的逻辑处理
            }
        }
    }
};

// 调用 subscribe 方法，订阅不同状态，nodeId 是通过查询已连接设备得到的设备 ID
// 目前支持订阅（连接状态变化，充电状态变化，佩戴状态变化，睡眠状态变化）
api.subscribe("nodeId", DataItem.ITEM_CONNECTION, onDataChangedListener)
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            // 添加订阅成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 添加订阅失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 调用 unsubscribe 方法取消监听
api.unsubscribe("nodeId", DataItem.ITEM_CONNECTION)
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            // 删除订阅成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 删除订阅失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

4. 应用间消息通信（需要申请 Permission.DEVICE_MANAGER 权限）

// 模拟数据，应用可以自定义发送数据
byte[] messageBytes = new byte[1024];

// 获取 MessageApi 对象
MessageApi messageApi = Wearable.getMessageApi(context);

// 调用 sendMessage 方法用来发送数据给穿戴设备端应用
messageApi.sendMessage("nodeId", messageBytes)
    .addOnSuccessListener(new OnSuccessListener<Integer>() {
        @Override
        public void onSuccess(Integer result) {
            // 发送数据成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 发送数据失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 创建监听器用于监听穿戴设备端发送来的消息
OnMessageReceivedListener onMessageReceivedListener = new OnMessageReceivedListener() {
    @Override
    public void onMessageReceived(@NotNull String nodeId, @NotNull byte[] message) {
        // 收到手表端应用发来的消息
        // 可以在这里添加相应的逻辑处理
    }
};

// 监听穿戴设备端应用发来的消息
messageApi.addListener("nodeId", onMessageReceivedListener)
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            // 添加消息监听成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 添加消息监听失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

// 取消监听
messageApi.removeListener("nodeId", onMessageReceivedListener)
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            // 取消消息监听成功
            // 可以在这里添加相应的逻辑处理
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 取消消息监听失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

5. 消息通知（需要 Permission.NOTIFY 权限）

// 获取 NotifyApi 对象
NotifyApi notifyApi = Wearable.getNotifyApi(context);

// 发送消息通知，需要提前判断是否有 Permission.NOTIFY 权限
notifyApi.sendNotify("nodeId", "title", "message")
    .addOnSuccessListener(new OnSuccessListener<Status>() {
        @Override
        public void onSuccess(Status status) {
            if (status.isSuccess()) {
                // 发送通知成功，手表上会看到消息通知内容，表端应用无感知
                // 可以在这里添加相应的逻辑处理
            }
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            // 发送通知失败
            // 通常这里可以记录错误日志或向用户提示错误信息
        }
    });

6. 管理服务连接状态（不需要权限）

//获取ServiceApi
ServiceApi serviceApi = Wearable.getServiceApi(context);
//第三方应用与小米穿戴App连接状态可以通过这个监听器来监听
OnServiceConnectionListener onServiceConnectionListener = new
OnServiceConnectionListener() {
@Override
public void onServiceConnected() {
//服务连接成功
}
@Override
public void onServiceDisconnected() {
//服务断开
}
};
//注册监听器
serviceApi.registerServiceConnectionListener(onServiceConnectionListener);
//取消监听器
serviceApi.unregisterServiceConnectionListener(onServiceConnectionListener);