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

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

Aristore
  2024-09-21 14:30 2024-09-21 14:30 创建      2.4k 字  10 分钟  

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

手环小程序开放接口文档

1.4版本更新日志

兼容Android R

1.3版本更新日志

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

1.2版本更新日志：

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

1.1版本更新日志：

  1. 修改状态订阅和状态查询相关接口返回值，详情请查看文档3.2和3.3部分

  2. 增加消息通知api，详情请看文档第 5 部分

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 获取 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权限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// 获取 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申请权限

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 获取 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权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
// 获取 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权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
// 获取 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权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// 模拟数据，应用可以自定义发送数据
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权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// 获取 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.管理服务连接状态（不需要权限）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//获取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);
  • 标题: 小米穿戴第三方APP能力开放接口文档_v1.4
  • 作者: Aristore
  • 创建于 : 2024-09-21 14:30:00
  • 更新于 : 2025-11-03 19:46:03
  • 链接: https://www.aristore.top/posts/mi_band_app_dev/
  • 版权声明: 版权所有 © Aristore，禁止转载。
评论
目录
小米穿戴第三方APP能力开放接口文档_v1.4
  1. 1.查询已连接的可穿戴设备（不需要权限）
  2. 2.权限查询与申请
    1. 2.1查询授权状态
    2. 2.2申请权限
  3. 3.设备管理与状态订阅
    1. 3.1支持查询与订阅的设备状态
    2. 3.2状态查询（需要申请Permission.DEVICE_MANAGER权限）
    3. 3.3状态订阅（需要申请Permission.DEVICE_MANAGER权限）
  4. 4.应用间消息通信（需要申请Permission.DEVICE_MANAGER权限）
  5. 5.消息通知（需要Permission.NOTIFY权限）
  6. 6.管理服务连接状态（不需要权限）