# 客户端实现(全功能版本) (/zh-CN/solutions/iot-apaas/build/implement-core-features/client-call/ios)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文介绍如何使用声网灵隼**全功能版本**的客户端示例项目在 iOS 客户端实现设备管理、呼叫、通话、告警等功能。
:::info[信息]
**全功能版本的客户端示例项目** 提供用户注册/登录、绑定/解绑设备、Wi-Fi 二维码配网、呼叫、实时音视频等功能。
如果你没有自研的设备管理等模块,声网建议你使用全功能版本示例项目。
:::
## 前提条件 [#前提条件-1]
开始前,请确保你的开发环境满足以下条件:
- Xcode(推荐最新版本)。
- iOS 12.0 或以上版本的 Apple 设备。
- 参考[开通并配置声网灵隼物联网服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)开通灵隼服务
## 跑通示例项目 [#跑通示例项目-1]
1. 从 [GitHub](https://github.com/AgoraIO-Community/ag-iot-ios-app) 上下载最新版本的 iOS 客户端示例项目。
2. 在项目的 `ag-iot-ios-app\AgoraIoT` 目录运行 `pod install` 安装依赖。
3. 连接上 iOS 设备后,点击 `.xcworkspace` 文件打开项目,并在 iOS Device 选项中勾选上你的 iOS 设备。
4. 使用 Xcode 打开项目。修改配置文件 `Config.swift`,将以下配置项修改为你在灵隼控制台的**应用配置>>开发者选项**页面中获取的相关参数。详见[开通并配置声网灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)。
```swift
// 声网灵隼控制台的应用配置>>开发者选项中的 App ID
public static let appId = "4b31f**********************3037" //appid
// 声网灵隼控制台的应用配置>>开发者选项中的 Project ID
public static let projectId:String = "a******_C" // 项目id"
// Easemob App Key。在开通声网灵隼服务之后,可以在应用配置页面中的开发者选项选项卡中获取
public static let ntfAppKey: String = "52****88#3****2" //离线推送的appkey
// APNS 证书名。在开通声网灵隼服务之后,可以在应用配置页面中的开发者选项选项卡中获取
public static let ntfApnsCertName:String = "xxx.xxx.xxx"//离线推送的AnpsCertName
// 声网灵隼控制台的应用配置>>开发者选项中的 Master Server URL
public static let masterServerUrl:String = "https://un2nfllop5.execute-api.cn-north-1.amazonaws.com.cn/Prod"
// 声网灵隼控制台的应用配置>>开发者选项中的 Slave Server URL
public static let slaveServerUrl:String = "https://api.sd-rtn.com/agoralink/cn/api"
```
5. 在项目 TARGETS 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**,配置你的苹果开发者账号和 Bundle Identifier。
6. 连接上 Apple 设备后,编译并运行项目。
7. 在登录页面选择注册新账户或者登录已有账户,目前国内只支持手机号注册。
8. 在登录成功后的页面,可以点击 **+** 号添加新设备(设备产品码请参考参考[开通灵隼服务](/zh-CN/solutions/iot-apaas/build/setup-and-access/enable-service)文档获取产品二维码章节),或者选择已经添加设备实时预览对应设备的画面(设备端示例项目请参考[实现设备端功能](/zh-CN/solutions/iot-apaas/build/implement-core-features/device-call)文档)。
## 客户端实现 [#客户端实现-1]
iOS 客户端的核心逻辑如下。
### 初始化 [#初始化-1]
参考以下步骤调用 `initialize` 方法进行初始化。
```swift
let param:InitParam = InitParam()
// 声网 App ID。在开通声网灵隼服务之后,可以在应用配置页面中的开发者选项选项卡中获取。
param.rtcAppId = Config.appId
param.logFilePath = FileCenter.logFilePath()
param.subscribeVideo = true
param.subscribeAudio = true
param.publishVideo = false
param.publishAudio = false
// APNS 证书名。在开通声网灵隼服务之后,可以在应用配置页面中的开发者选项选项卡中获取。
param.ntfApnsCertName = Config.ntfApnsCertName
// APNS 证书秘钥。在开通声网灵隼服务之后,可以在应用配置页面中的开发者选项选项卡中获取。
param.ntfAppKey = Config.ntfAppKey
// 开发者选项>>呼叫服务>>Master Server URL 获取
param.masterServerUrl = "http://iot-api-gateway.sh.agoralab.co/api"
// 开发者选项>>呼叫服务>>Slave Server URL 获取
param.slaveServerUrl = "https://un2nfllop5.execute-api.cn-north-1.amazonaws.com.cn/Prod"
// 开发者选项>>呼叫服务>>Project ID 获取
param.projectId = "Your Project ID"
let ret = AgoraIotSdk.iotsdk.initialize(initParam: param, netStatus: {status,msg in}, callBackFilter: { ec, msg in return (ec,msg)})
```
### 注册用户账号 [#注册用户账号-1]
可以通过邮箱和手机号码两种方式来注册用户账号。账号注册分为两个步骤:
1. 通过手机号码或者邮箱账号获取注册验证码。
```swift
//
// 获取验证码,这里 使用getCode来获取邮箱验证码,getSms来获取手机验证码,type固定为""REGISTER""
// 获取手机验证码时,lang表示所在国家语言
// 相应的验证码,过几分钟后会发送到手机短信或者邮箱邮件
// 接口通过 result 异步返回
AgoraIotSdk.iotsdk.accountMgr.getCode(email: email, type: "REGISTER", result: {errCode,errMsg in})
AgoraIotSdk.iotsdk.accountMgr.getSms(phone: phone, type: "REGISTER",lang:"ZH_CN", result: {errCode,errMsg in})
```
2. 使用手机号或邮箱、验证码和密码进行账号注册。
`accountName` 可以填入手机号码或者邮箱作为账户名,你也可以使用其他账户名。
```swift
if(registerWithPhoneNumber){
//使用手机注册
AgoraIotSdk.iotsdk.accountMgr.register(account: acc, password: pwd,code:code,email: nil,phone:phone, result: result: {errCode, errMsg in})
}
else{
//使用邮箱注册
AgoraIotSdk.iotsdk.accountMgr.register(account: acc, password: pwd,code:code,email: email,phone:nil, result: result: {errCode, errMsg in})
}
```
### 登录用户账号 [#登录用户账号-1]
参考以下步骤登录用户账号:
```swift
//
// 使用(账号名+密码)方式进行登录
// 登录成功/失败后,触发 result 回调登录结果
//
AgoraIotSdk.iotsdk.accountMgr.login(account: acc, password: pwd,result: {errCode, errMsg in})
```
当用户账号成功登录后,可以开始进行正式的操作,包括设备管理、告警信息查询、系统信息查询、用户信息更新等。
### 添加设备 [#添加设备-1]
当前版本中,只支持设备端扫描二维码进行添加,需要客户端生成二维码:
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,可以通过 `AgoraIotSdk.iotsdk.accountMgr.getUserId()` 获取。
- `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"
}
```
然后使用二维码生成库(例如 `CoreImage.CIFilterBuiltins`),根据 JSON 内容生成二维码 Bitmap,并提供给设备端摄像头来扫描。具体生成方式可以参考 SDK 自带的示例项目中的 `/View/Home/SetDevice/SDStep3View.swift` 文件。
2. 设备摄像头扫描二维码图进行主动绑定。
3. 绑定设备列表查询。你可以通过设备列表查询方法来获取当前所有绑定设备列表。
```swift
// 查询当前账号下绑定设备列表,通过回调 result 方法返回设备列表
AgoraIotSdk.iotsdk.deviceMgr.queryAllDevices(result: {errCode,errMsg,devs in})
```
4. 设备改名。设备绑定成功后,会使用默认的设备名。用户也可以根据需要,将设备名更改成方便记忆的名字。
```swift
// 设备进行改名操作,通过 result 方法返回改名是否成功
AgoraIotSdk.iotsdk.deviceMgr.renameDevice(device: dev, newName: newName, result: {errCode,errMsg in})
```
### 客户端呼叫设备端 [#客户端呼叫设备端-1]
1. 客户端发出呼叫请求。
```swift
// 呼叫设备端,可以同时附带一些呼叫消息
AgoraIotSdk.iotsdk.callkitMgr.callDial(device:dev,attachMsg: "",result:{
(ec,msg) in
cb(ec == ErrCode.XOK ? true : false , msg)
},peerAction: {s in
log.i("peer \(s)")
})
```
2. 客户端发出呼叫请求成功后,设备端会有三种状态回应:
- 如果设备端正常接听,`peerAction` 返回 `.Answer`,开始音视频通话。
- 如果设备端拒绝接听,`peerAction` 返回 `.Hangup`,结束本次通话。
- 如果设备端接听超时,`peerAction` 返回 `.Timeout`,结束本次通话。
3. 正常通话过程中,客户端可以发送音视频,对端也发送音视频。当设备接听后挂断电话,`peerAction` 返回 `.Hangup`。
4. 如果客户端想要结束通话,调用 `AgoraIotSdk.iotsdk.callkitMgr.callHangup()` 方法主动挂断电话。
```swift
AgoraIotSdk.iotsdk.callkitMgr.callHangup(result: {errCode,errMsg in})
```
### 设备端呼叫客户端 [#设备端呼叫客户端-1]
1. 接收到来电呼叫事件需要在初始化完成后注册来电回调接口
```swift
AgoraIotSdk.iotsdk.callkitMgr.register(incoming: {peerId,msg,action in})
```
2. 客户端处于空闲状态时,如果有设备端呼叫,会接收到来电呼叫事件 `AgoraIotSdk.iotsdk.ICallkitMgrCallback.onPeerIncoming`,你可以根据自己的业务逻辑显示来电界面。
3. 客户端根据实际的业务逻辑进行处理。
- 如果客户端拒绝,则调用 `AgoraIotSdk.iotsdk.callkitMgr.callHangup()` 方法挂断 ,结束本次通话。
- 如果客户端接听,则调用 `AgoraIotSdk.iotsdk.callkitMgr.callAnswer()` 方法,进入双方通话状态。客户端可以使用 `AgoraIotSdk.iotsdk.callkitMgr.callHangup()` 主动挂断通话。如果设备端挂断通话,客户端会收到 `AgoraIotSdk.iotsdk.ICallkitMgrCallback.onPeerHangup()` 回调。
### 告警信息查询 [#告警信息查询-1]
当有人员经过监控设备时,设备端会将 入侵检测、移动侦测相应的事件上报给服务器。
客户端可以通过相应的接口进行查询,设置不同的查询参数字段,可以进行相应的过滤。
```swift
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);
```
### 系统告警查询 [#系统告警查询-1]
设备的绑定、解绑、上线、下线等系统事件,也会同步上报给服务器。
客户端可以通过相应的接口进行查询,设置不同的查询参数字段,可以进行相应的查询过滤。
```swift
var query = IAlarmMgr.QueryParam(dateBegin: nil)
query.status = status
query.messageType = type
query.createdDateBegin = nil
query.createdDateEnd = date
query.pageSize = 10
query.currentPage = 1
AgoraIotSdk.iotsdk.alarmMgr.queryByParam(queryParam: query, result: {errCode,errMsg,alarms in})
```
### 发送和接收云信令 RTM 消息 [#发送和接收云信令-rtm-消息-1]
你可以通过 `sendMessage`和 `messageReceived` 发送和接收云信令 RTM 消息。
```swift
// 连接 RTM 云信令
AgoraIotLink.iotsdk.deviceMgr.sendMessageBegin(device: device!) { ec, msg in
log.level(ec == ErrCode.XOK ? .info : .error, "demo sendMessageBegin() \(msg)(\(ec))")
if(ec != ErrCode.XOK){
AGToolHUD.showFaild(info: msg)
}
} statusUpdated: { status,msg,data in
if(status == .DataArrived){
log.i("demo sendMessage status updated:\(status),\(msg)")
AGToolHUD.showSuccess(info: "rtm info :\(msg)")
}
else if(data != nil){
log.i("demo 收到设备数据长度:" + String(data!.count))
AGToolHUD.showSuccess(info: "rtm info :\(msg)")
}
}
// 发送 RTM 云信令消息
AgoraIotLink.iotsdk.deviceMgr.sendMessage(data: data, description: "this is description") { ec, msg in
log.i("demo send message \(msg)(\(ec))")
if(ec != ErrCode.XOK){
AGToolHUD.showFaild(info: msg)
}
}
// 与 RTM 云信令断开连接
AgoraIotLink.iotsdk.deviceMgr.sendMessageEnd()
```
### 登出用户账号 [#登出用户账号-1]
你可以通过以下方法登出用户账号。
```swift
AgoraIotSdk.iotsdk.accountMgr.logout(result: {errCode,errMsg in})
```
### 注销用户账号 [#注销用户账号-1]
你可以通过以下方法注销用户账号。
```swift
AgoraIotSdk.iotsdk.accountMgr.unregister(result: {errCode,errMsg in})
```
## 参考信息 [#参考信息-1]
- [客户端全功能 API 参考](/zh-CN/api-reference/iot-apaas/client-api/full)