# 客户端实现(全功能版本) (/zh-CN/solutions/iot-apaas/build/implement-core-features/client-call/android) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何使用声网灵隼**全功能版本**的客户端示例项目在 Android 客户端实现设备管理、呼叫、通话、告警等功能。 :::info[信息] **全功能版本的客户端示例项目**提供用户注册/登录、绑定/解绑设备、Wi-Fi 二维码配网、呼叫、实时音视频等功能。 如果你没有自研的设备管理等模块,声网建议你使用全功能版本示例项目。 ::: ## 前提条件 [#前提条件] 开始前,请确保你的开发环境满足以下条件: - Android Studio 4.1.2 或以上版本。 - Android API level 16 或以上。 - 运行 Android 4.1 或以上版本的移动设备。 - 参考[开通并配置声网灵隼物联网服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)开通灵隼服务 ## 跑通示例项目 [#跑通示例项目] ### 跑通步骤 [#跑通步骤] 1. 从 [GitHub](https://github.com/AgoraIO-Community/ag-iot-android-app) 上下载最新版本的 Android 客户端示例项目。 2. 使用 Android Studio 加载工程后,在 **app>>res>>values>>config.xml** 文件中,将以下配置项修改为你在灵隼控制台的**应用配置>>开发者选项**页面中获取的相关参数。详见[开通声网灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 ```xml your_app_id your_project_id your_master_server your_slave_serveri ``` 3. 连接上 Android 设备后,用 Android Studio 编译并运行示例项目。 4. 在登录页面选择注册新账户或者登录已有账户,目前国内只支持手机号注册。 5. 在登录成功后的页面,可以点击 **+** 号添加新设备(设备产品码请参考[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)文档获取产品二维码章节),或者选择已经添加设备实时预览对应设备的画面(设备端示例项目请参考[实现设备端功能](/zh-CN/solutions/iot-apaas/build/implement-core-features/device-call)文档)。 ### (可选)开通离线呼叫 [#可选开通离线呼叫] 当 Android 端应用不再运行时(包括不在后台运行时或应用进程不存在时),离线呼叫可以实现在有设备端呼叫客户端时,客户端能收到后台服务,并启动应用来接听设备端呼叫。你可以参考以下步骤开通离线呼叫: 1. 在 `app\src\main\res\values\config.xml` 文件中配置离线呼叫的相应参数。 ```xml your_easemob_appkey false 0 appid=106736987 ``` 2. 恢复 `\app\src\main\AndroidManifest.xml` 文件中关于离线推送注释的代码。主要包括离线推送权限配置、离线推送账号配置和离线推送服务配置。 ```xml ``` 3. 恢复 `app\build.gradle` 中标注为 `各手机厂商离线推送 SDK` 的代码 ,以集成各家手机厂商的离线推送 SDK。 ```gradle // // 各手机厂商离线推送SDK // //implementation(name: 'oppo_push_v2.1.0', ext: 'aar') // implementation 'com.huawei.hms:push:4.0.2.300' // implementation files('libs/mi_push_v3.6.12.jar') // implementation files('libs/vivo_push_v2.3.1.jar') // implementation 'io.hyphenate:hyphenate-push:0.1.0' // 环信 // // // Google firebase 离线推送 // implementation 'com.google.android.gms:play-services-base:18.1.0' // implementation 'com.google.firebase:firebase-messaging:23.0.6' ``` 4. `\app\src\main\io\agora\iotlinkdemo\base\PushApplication.java` 文件的 `PushApplication.onCreate()` 方法中,恢复 import 语句和标注为 `初始化环信的离线推送` 的代码。 ```java //import io.agora.iotlinkdemo.huanxin.EmAgent; // // 初始化环信的离线推送 // // if (mMetaData != null) // { // EmAgent.EmPushParam pushParam = new EmAgent.EmPushParam(); // pushParam.mFcmSenderId = mMetaData.getString("com.fcm.push.senderid", ""); // pushParam.mMiAppId = mMetaData.getString("com.mi.push.app_id", ""); // pushParam.mMiAppKey = mMetaData.getString("com.mi.push.api_key", ""); // pushParam.mOppoAppKey = mMetaData.getString("com.oppo.push.api_key", ""); // pushParam.mOppoAppSecret = mMetaData.getString("com.oppo.push.app_secret", "");; // pushParam.mVivoAppId = String.valueOf(mMetaData.getInt("com.vivo.push.app_id", 0)); // pushParam.mVivoAppKey = mMetaData.getString("com.vivo.push.api_key", ""); // pushParam.mHuaweiAppId = mMetaData.getString("com.huawei.hms.client.appid", ""); // EmAgent.getInstance().initialize(this, pushParam); // } } ``` 5. 在 `\app\src\main\io\agora\iotlinkdemo\base\PushApplication.java` 文件的 `PushApplication.initializeEngine()` 方法中,恢复以下代码: ```java initParam.mPusherId = EmAgent.getInstance().getEid(); ``` 6.在 `\app\src\main\io\agora\iotlinkdemo\huanxin\EmAgent.java` 文件,恢复全部代码。 对于**华为推送**,你还要进行以下额外步骤: 1. 恢复以下文件中的全部代码: - `\app\src\main\io\agora\iotlinkdemo\huanxin\HMSPushHelper.java` - `\app\src\main\io\agora\iotlinkdemo\huanxin\HMSPushService.java` 2. 从 [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/android-config-agc-0000001050170137) 下载 `agconnect-services.json` 文件,覆盖 `\app\agconnect-services.json` 文件。 3. 将证书文件 `iot.jks` 的 SHA256 指纹,填写到 [AppGallery Connect](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/android-config-agc-0000001050170137) 中。 ## 客户端实现 [#客户端实现] Android 客户端的核心逻辑如下。 ### 配置离线推送账号信息 [#配置离线推送账号信息] 在你的 Android 项目中,修改 `AndroidManifest.xml` 文件配置离线推送账号信息。参考[开通声网灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)获取账号信息。 ```xml ``` ### 初始化 [#初始化] 参考以下步骤调用 `initialize()` 方法来初始化。参考[开通声网灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)获取相关参数。 ```java // //初始化IotAppSdk2.0 引擎 // IAgoraIotAppSdk.InitParam initParam = new IAgoraIotAppSdk.InitParam(); initParam.mContext = this; initParam.mRtcAppId = appId; // 声网 App ID String storageRootPath = Environment.getExternalStorageDirectory().getAbsolutePath(); initParam.mLogFilePath = storageRootPath + "/callkit.log"; // 设置日志路径 initParam.mPublishVideo = false; // 客户端默认不推送视频流 initParam.mPublishAudio = false; // 客户端默认不推送音频流 initParam.mSubscribeAudio = true; // 客户端默认订阅视频流 initParam.mSubscribeVideo = true; // 客户端默认订阅视频流 // 开发者选项>>呼叫服务>>Master Server URL 获取 initParam.mMasterServerUrl = "http://iot-api-gateway.sh.agoralab.co/api"; // 开发者选项>>呼叫服务>>Slave Server URL 获取 initParam.mSlaveServerUrl = "https://un2nfllop5.execute-api.cn-north-1.amazonaws.com.cn/Prod"; // 开发者选项>>呼叫服务>>Project ID 获取 initParam.mProjectID = "Your Project ID"; // 调用 SDK 初始化接口,返回错误码为 0,表示初始化成功 int ret = AIotAppSdkFactory.getInstance().initialize(initParam); ``` ### 注册用户账号 [#注册用户账号] 可以通过邮箱和手机号码两种方式来注册用户账号。账号注册分为两个步骤: 1. 通过手机号码或者邮箱账号获取注册验证码。 ```java // 获取验证码,这里 accountName 可以是手机号码或者邮箱,type 固定为 "REGISTER" int ret = AIotAppSdkFactory.getInstance().getAccountMgr().getCode(accountName, type); // 获取验证码完成后,会触发 IAccountMgr.ICallback.onGetCodeDone() 事件 // 相应的验证码,过几分钟后会发送到手机短信或者邮箱邮件 @Override public void onGetCodeDone(int errCode, String account) { } ``` 2. 使用手机号或邮箱、验证码和密码进行账号注册。 `accountName` 可以填入手机号码或者邮箱作为账户名,你也可以使用其他账户名。 ```java if (registerWithPhoneNumber) { // 手机注册账号 ret = AIotAppSdkFactory.getInstance().getAccountMgr().register(accountName, password, verifyCode, phoneNumber, null); } else { // 邮箱注册账号 ret = AIotAppSdkFactory.getInstance().getAccountMgr().register(accountName, password, verifyCode, null, email); } // 注册完成后触发 IAccountMgr.ICallback.onRegisterDone() 回调 @Override public void onRegisterDone(int errCode, String account) { } ``` ### 登录用户账号 [#登录用户账号] 参考以下步骤登录用户账号: ```java // 使用(账号名+密码)方式进行登录 int ret = AIotAppSdkFactory.getInstance().getAccountMgr().login(accountName, password); // 登录成功/失败后,触发 IAccoungMgr.ICallback.onLoginDone() 回调 @Override public void onLoginDone(int errCode, String account) { } ``` 当用户账号成功登录后,可以开始进行正式的操作,包括设备管理、告警信息查询、系统信息查询、用户信息更新等。 ### 添加设备 [#添加设备] 当前版本中,只支持设备端扫描二维码进行添加,需要客户端生成二维码: 1. 生成设备二维码图。在客户端需要使用 JSON 字符串生成相应的二维码图,其中 JSON 字符串格式为: ```json { "s": "wifi_ssid", "p": "wifi_password", "u": "code_user_id", "k": "productkey" } ``` 其中: - `wifi_ssid`: 配置给设备的 WIFI SSID。 - `wifi_password`: 配置给设备的 WIFI 网络访问密码。 - `code_user_id`: 用于配置的特定用户 ID,可以通过 `AIotAppSdkFactory.getInstance().getAccountMgr().getQRCodeUserId()` 获取。 - `product_key`: 配置的产品 ID。获取方式详见[开通并配置灵隼物联网服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。 JSON 内容示例: ```json { "s":"TP-LINK_AGORA08", "p":"Agora123456", "u":"690191659910586368", "k":"EJImm64m65ECOl5" } ``` 然后使用第三方二维码生成库(例如 [zxing](https://github.com/journeyapps/zxing-android-embedded)),根据 JSON 内容生成二维码 Bitmap,并提供给设备端摄像头来扫描。具体生成方式可以参考 SDK 自带的示例项目中的 `ZXingUtils.class` 文件。 2. 设备摄像头扫描二维码图进行主动绑定。 3. 绑定设备列表查询。你可以通过设备列表查询方法来获取当前所有绑定设备列表。 ```java // 查询当前账号下绑定设备列表 int ret = AIotAppSdkFactory.getInstance().getDeviceMgr().queryAllDevices(); // 查询完成后,触发 IDeviceMgr.ICallback.onAllDevicesQueryDone() 回调事件 @Override public void onAllDevicesQueryDone(int errCode, List deviceList) { } ``` 4. 设备改名。设备绑定成功后,会使用默认的设备名。用户也可以根据需要,将设备名更改成方便记忆的名字。 ```java // 设备进行改名操作, int errCode = AIotAppSdkFactory.getInstance().getDeviceMgr().renameDevice(iotDevice, newName); // 改名完成触发 IDeviceMgr.ICallback.onDeviceRenameDone() 回调事件 @Override public void onDeviceRenameDone(int errCode, IotDevice iotDevice, String newName) { } ``` ### 客户端呼叫设备端 [#客户端呼叫设备端] 1. 客户端发出呼叫请求。 ```java // 呼叫设备端,可以同时附带一些呼叫消息 int ret = AIotAppSdkFactory.getInstance().getCallkitMgr().callDial(iotDevice, attachMsg); // 呼叫完成后,触发 ICallkitMgr.ICallback.onDialDone()回调事件 // 可以根据 errCode 错误码判断呼叫是否成功,或者对端是否忙 @Override public void onDialDone(int errCode, IotDevice iotDevice) { } ``` 2. 客户端发出呼叫请求成功后,设备端会有三种状态回应: - 设备端正常接听,客户端接收到 `ICallkitMgr.ICallback.onPeerAnswer(IotDevice iotDev)` 回调事件,进入双方通话状态。 - 设备端拒绝接听,客户端接收到 `ICallkitMgr.ICallback.onPeerHangup(IotDevice iotDev)` 回调事件,结束本次通话。 - 设备端超时不回应,客户端接收到 `ICallkitMgr.ICallback.onPeerTimer(IotDevice iotDev)` 回调事件,结束本次通话。 3. 正常接通时,客户端会接收到 `ICallkitMgr.ICallback.onPeerFirstVideo(IotDevice iotDevice, int videoWidth, int videoHeight)` 事件,表示接收到设备端首帧视频帧,应用层可以根据自己实际的显示业务逻辑进行处理。正常通话过程中,客户端可以发送音视频,对端也可以发送音视频。客户端可以调用 `AIotAppSdkFactory.getInstance().getCallkitMgr().setAudioEffect();` 来设置各种变声效果。客户端也可以设置设备端是否推送音视频流等达到静音等效果,详见 `ICallkitMgr` 接口提供的方法。 4. 如果客户端想要结束通话,调用 `AIotAppSdkFactory.getInstance().getCallkitMgr().callHangup();` 方法主动挂断电话。在通话过程中接收到 `ICallkitMgr.ICallback.onPeerHangup(IotDevice iotDev)` 事件,说明对端设备主动挂断,结束通话。 ### 设备端呼叫客户端 [#设备端呼叫客户端] 1. 客户端处于空闲状态时,如果有设备端呼叫,会接收到来电呼叫事件 `ICallkitMgr.ICallback.onPeerIncoming()`,你可以根据自己的业务逻辑显示来电界面。 ```java // 来自于设备端的呼叫,附带消息 @Override public void onPeerIncoming(IotDevice iotDevice, String attachMsg) ``` 2. 客户端根据实际的业务逻辑进行处理。 - 如果客户端正常接听,则调用 `ICallkitMgr.getCallkitMgr. callAnswer(IotDevice iotDev)` 方法,进入双方通话状态。 - 如果客户端拒绝接听,则调用 `ICallkitMgr.getCallkitMgr.callHangup(IotDevice iotDev)` 方法挂断 ,结束本次通话、 - 如果客户端不回应,设备端会超时主动挂断,客户端接收到 `ICallkitMgr.ICallback. onPeerHangup(IotDevice iotDev)` 回调事件,结束本次通话。 3. 正常接通时,客户端会接收到 `ICallkitMgr.ICallback.onPeerFirstVideo(IotDevice iotDevice, int videoWidth, int videoHeight)` 事件,表示接收到设备端首帧视频帧,应用层可以根据自己实际的显示业务逻辑进行处理。正常通话过程中,客户端可以发送音视频,对端也可以发送音视频。客户端可以调用 `AIotAppSdkFactory.getInstance().getCallkitMgr().setAudioEffect();` 来设置各种变声效果。客户端也可以设置设备端是否推送音视频流等达到静音等效果,详见 `ICallkitMgr` 接口提供的方法。 4. 如果客户端想要结束通话,调用 `AIotAppSdkFactory.getInstance().getCallkitMgr().callHangup();` 方法主动挂断电话。在通话过程中接收到 `ICallkitMgr.ICallback.onPeerHangup(IotDevice iotDev)` 事件,说明对端设备主动挂断,结束通话。 ### 告警信息查询 [#告警信息查询] 当有人员经过监控设备时,设备端会将 入侵检测、移动侦测相应的事件上报给服务器。 客户端可以通过相应的接口进行查询,设置不同的查询参数字段,可以进行相应的过滤。 ```java IAlarmMgr.QueryParam queryParam = new IAlarmMgr.QueryParam(); queryParam.mPageIndex = 1; queryParam.mPageSize = 512; queryParam.mMsgType = -1; queryParam.mMsgStatus = -1; int ret = AIotAppSdkFactory.getInstance().getAlarmMgr().queryByPage(queryParam); ``` ### 系统告警查询 [#系统告警查询] 设备的绑定、解绑、上线、下线等系统事件,也会同步上报给服务器。 客户端可以通过相应的接口进行查询,设置不同的查询参数字段,可以进行相应的查询过滤。 ```java IDevMessageMgr.QueryParam queryParam = new IDevMessageMgr.QueryParam(); queryParam.mDevIDList.addAll(mDeviceIDList); queryParam.mPageIndex = 1; queryParam.mPageSize = 256; queryParam.mMsgType = -1; queryParam.mMsgStatus = -1; int ret = AIotAppSdkFactory.getInstance().getDevMessageMgr().queryByPage(queryParam); ``` ### 发送和接收云信令 RTM 消息 [#发送和接收云信令-rtm-消息] 你可以通过 `sendMessage` 和 `onMessageReceived` 发送和接收云信令 RTM 消息。 ```java // 获取 IRtmMgr 对象 IRtmMgr rtmMgr = AIotAppSdkFactory.getInstance().getRtmMgr(); // 链接 RTM 云信令 int errCode = rtmMgr.connect(mLivingDevice); // 发送 RTM 云信令消息 rtmMgr.sendMessage(messageData, new IRtmMgr.ISendCallback() { @Override public void onSendDone(int errCode) { Log.d(TAG, " errCode=" + errCode); getISingleCallback().onSingleCallback(Constant.CALLBACK_TYPE_RTM_SEND_DONE, errCode); } }); // 通过 onMessageReceived 回调接收云信令 RTM 消息 @Override public void onMessageReceived(byte[] messageData) { Log.d(TAG, " messageData.length=" + messageData.length); getISingleCallback().onSingleCallback(Constant.CALLBACK_TYPE_RTM_RECVED, messageData); } // 与 RTM 云信令断开连接 int errCode = rtmMgr.disconnect(); ``` ### 登出用户账号 [#登出用户账号] 你可以通过以下方法登出用户账号。 ```java // 登出操作,触发 IAccountMgr.ICallback.onLogoutDone()事件 int ret = AIotAppSdkFactory.getInstance().getAccountMgr().logout(); // 登出完成事件, @Override public void onLogoutDone(int errCode, String account) { } ``` ### 注销用户账号 [#注销用户账号] 你可以通过以下方法注销用户账号。 ```java // 注销操作,触发 IAccountMgr.ICallback.onUnregisterDone() 回调事件 int ret = AIotAppSdkFactory.getInstance().getAccountMgr().unregister(); // 注销完成事件 @Override public void onUnregisterDone(int errCode, String account) { } ``` ## 参考信息 [#参考信息] - [客户端全功能 API 参考](/zh-CN/api-reference/iot-apaas/client-api/full)