快速开始（不含 UIKIT）
即时通讯将各地人们连接在一起，实现实时通信。利用即时通讯 IM SDK，你可以在任何地方的任何设备上的任何应用中嵌入实时通讯。
本文介绍如何集成即时通讯 IM SDK，在你的 iOS app 中实现发送和接收单聊文本消息。
技术原理
下图展示在客户端发送和接收单聊文本消息的工作流程。
如上图所示，实现单聊消息的步骤如下：
- 客户端向你的应用服务器请求 Token，你的应用服务器返回 Token。
- 客户端 A 和客户端 B 使用获得的 Token 登录声网即时通讯系统。
- 客户端 A 发送消息到声网即时通讯服务器。
- 声网即时通讯服务器将消息发送到客户端 B，客户端 B 接收消息。
App 客户端登录声网即时通讯系统需要以下信息：
- AppKey：声网随机生成的字符串，用于识别你的 app，可从声网控制台获取。
- 用户 ID：用户的唯一标识。你需要自行设置用户 ID，并确保它在项目内是唯一的。
- Token：在测试或生产环境中，你的 app 客户端会从你的应用服务器中获取 Token。
前提条件
开始前，请确保你的开发环境满足以下条件：
- 有效的声网账号。
- 带有开启了即时通讯 IM 服务的 App Key 的声网项目。
- Xcode。本文以 Xcode 13.0 为例进行介绍。
- 一台运行 iOS 10 或以上版本的设备。
生成 Token
为了保证通信安全，声网推荐使用 Token 对登录即时通讯 IM 的用户进行认证。
出于测试目的，声网控制台支持为即时通讯 IM 生成临时 Token，而在生产环境中，Token 需由你的 App Server 生成。
在测试环境中，用户权限 Token 基于用户 ID 生成。若尚未创建用户，需要首先注册即时通讯 IM 用户。
注册用户
参考以下步骤注册用户：
登录声网控制台，点击左侧导航栏项目管理。
选择需要开通即时通讯服务的项目，点击配置。
- 在服务配置页面，点击即时通讯中的配置。
- 在左侧导航栏，选择运营管理 > 用户，点击创建IM用户。
- 在创建IM用户对话框中，填写用户信息并点击保存，创建用户。
生成 Token
参考以下步骤生成用户 Token：
- 在项目管理页面，点击你要使用的项目的操作一栏中的配置。
- 在服务配置页面，点击即时通讯中的配置。
- 在应用信息页面的数据中心区域，在 Chat User Temp Token 框中输入用户 ID，点击生成生成一个具有用户权限的 Token。
项目设置
在本节中，我们准备了将即时通讯 IM 集成到你的 app 中所需的开发环境。
创建 iOS 项目
在 Xcode 中，参考以下步骤创建一个 iOS 应用项目。
- 打开 Xcode，单击 Create a new Xcode project。
- 平台类型选择 iOS，项目类型选择 App，然后单击 Next。
- 在本例中设置 Storyboard 和 Swift，创建项目。
集成即时通讯 IM SDK
- 选择 File > Swift Packages > Add Package Dependencies...，填入以下 URL：
https://github.com/AgoraIO/AgoraChat_iOS.git- 在 Choose Package Options 中，设置你要使用的即时通讯 IM SDK 版本。
实现单聊客户端
创建 UI
你需要实现 ViewController，创建所需的 UI 控件。
在 ViewController.swift 中，用以下代码替换文件中的内容：
class ViewController: UIViewController {
// 定义 UI 视图。
var userIdField, tokenField, remoteUserIdField, textField: UITextField!
var loginButton, logoutButton, sendButton: UIButton!
var logView: UITextView!
func createField(placeholder: String?) -> UITextField {
let field = UITextField()
field.layer.borderWidth = 0.5
field.placeholder = placeholder
return field
}
func createButton(title: String?, action: Selector) -> UIButton {
let button = UIButton(type: .system)
button.setTitle(title, for: .normal)
button.addTarget(self, action: action, for: .touchUpInside)
return button
}
func createLogView() -> UITextView {
let logTextView = UITextView()
logTextView.isEditable = false
return logTextView
}
func initViews() {
// 创建 UI 控件。
userIdField = createField(placeholder: "User Id")
self.view.addSubview(userIdField)
tokenField = createField(placeholder: "Token")
self.view.addSubview(tokenField)
remoteUserIdField = createField(placeholder: "Remote User Id")
self.view.addSubview(remoteUserIdField)
textField = createField(placeholder: "Input text message")
self.view.addSubview(textField)
loginButton = createButton(title: "Login", action: #selector(loginAction))
self.view.addSubview(loginButton)
logoutButton = createButton(title: "Logout", action: #selector(logoutAction))
self.view.addSubview(logoutButton)
sendButton = createButton(title: "Send", action: #selector(sendAction) )
self.view.addSubview(sendButton)
logView = createLogView()
self.view.addSubview(logView)
// 将 <#Input Your UserId#> 和 <#Input Your Token#> 替换为你自己的用户 ID 和在声网控制台上生成的 Token。
self.userIdField.text = <#Input Your UserId#>
self.tokenField.text = <#Input Your Token#>
}
override func viewDidLayoutSubviews() {
super.viewDidLayoutSubviews()
// 定义 UI 布局控件。
let fullWidth = self.view.frame.width
userIdField.frame = CGRect(x: 30, y: 50, width: fullWidth - 60, height: 30)
tokenField.frame = CGRect(x: 30, y: 100, width: fullWidth - 60, height: 30)
loginButton.frame = CGRect(x: 30, y: 150, width: 80, height: 30)
logoutButton.frame = CGRect(x: 230, y: 150, width: 80, height: 30)
remoteUserIdField.frame = CGRect(x: 30, y: 200, width: fullWidth - 60, height: 30)
textField.frame = CGRect(x: 30, y: 250, width: fullWidth - 60, height: 30)
sendButton.frame = CGRect(x: 30, y: 300, width: 80, height: 30)
logView.frame = CGRect(x: 30, y: 350, width: fullWidth - 60, height: self.view.frame.height - 350 - 50)
}
override func viewDidLoad() {
super.viewDidLoad()
initViews()
}
// 输出运行日志。
func printLog(_ log: Any...) {
DispatchQueue.main.async {
self.logView.text.append(
DateFormatter.localizedString(from: Date.now, dateStyle: .none, timeStyle: .medium)
+ ": " + String(reflecting: log) + "\r\n"
)
self.logView.scrollRangeToVisible(NSRange(location: self.logView.text.count, length: 1))
}
}
}实现聊天逻辑
本节介绍如何初始化即时通讯 IM、创建用户、登录即时通讯 IM 以及发送和接收单聊文本消息。
导入和初始化即时通讯 IM SDK
对 ViewController.swift 文件进行如下修改：
import UIKit
// 导入即时通讯 IM SDK。
import AgoraChat
class ViewController: UIViewController {
...
func initChatSDK() {
// 将 <#Agora App Key#> 替换为自己的 App Key。
// 初始化即时通讯 IM SDK。如果进行多次初始化操作，只有第一次初始化以及相关的参数生效。
let options = AgoraChatOptions(appkey: "<#Agora App Key#>")
options.isAutoLogin = false // 关闭自动登录。
options.enableConsoleLog = true
AgoraChatClient.shared.initializeSDK(with: options)
// 添加代理用于接收消息。
AgoraChatClient.shared.chatManager?.add(self, delegateQueue: nil)
}
override func viewDidLoad() {
...
// 调用初始化方法。
initChatSDK()
}
}利用 Token 登录
extension ViewController {
// 利用 Token 登录即时通讯 IM。
@objc func loginAction() {
guard let userId = self.userIdField.text,
let token = self.tokenField.text else {
self.printLog("userId or token is empty")
return;
}
let err = AgoraChatClient.shared.login(withUsername: userId, agoraToken: token)
if err == nil {
self.printLog("login success")
} else {
self.printLog("login failed:\(err?.errorDescription ?? "")")
}
}
// 登出即时通讯 IM。
@objc func logoutAction() {
AgoraChatClient.shared.logout(false) { err in
if err == nil {
self.printLog("logout success")
}
}
}
}发送和接收消息
extension ViewController: AgoraChatManagerDelegate {
// 发送文本消息
@objc func sendAction() {
guard let remoteUser = remoteUserIdField.text,
let text = textField.text,
let currentUserName = AgoraChatClient.shared.currentUsername else {
self.printLog("Not login or remoteUser/text is empty")
return
}
let msg = AgoraChatMessage(
conversationId: remoteUser, from: currentUserName,
to: remoteUser, body: .text(content: text), ext: nil
)
AgoraChatClient.shared.chatManager?.send(msg, progress: nil) { msg, err in
if let err = err {
self.printLog("send msg error.\(err.errorDescription)")
} else {
self.printLog("send msg success")
}
}
}
func messagesDidReceive(_ aMessages: [AgoraChatMessage]) {
for msg in aMessages {
switch msg.swiftBody {
case let .text(content: content):
self.printLog("receive text msg,content: \(content)")
default:
break
}
}
}
}运行并测试项目
使用 Xcode 在 iOS 真机或模拟机上编译和运行项目。你可以看到以下界面：
ViewController.swift 文件中的字段登录 app。参考以下步骤对你通过即时通讯 IM 在 app 中集成的单聊功能：
登录即时通讯 IM。
在模拟器或物理设备上，在 User Id 和 Token 文本框中输入发送方的用户 ID（lxm）和 Agora Token，然后点击 Login。发送消息。
在 Remote User Id 文本框中输入接收方的用户 ID（lxm2），在 Input text message 框中输入消息内容（"Hello"），然后点击 Send。
登出即时通讯 IM。
点击 Logout 登出即时通讯 IM。接收消息。
登出后，以接收方的用户 ID（lxm2）接收步骤 2 中发送的 "Hello" 消息。
后续步骤
出于演示目的，即时通讯 IM 提供一个 App Server，可使你利用本文中提供的 App Key 快速获得 Token。在生产环境中，最好自行部署 Token 服务器，使用自己的 App Key 生成 Token，并在客户端获取 Token 登录即时通讯 IM。要了解如何实现服务器按需生成和提供 Token，请参阅生成用户权限 Token。
集成 SDK 的其他方式
方法 1：通过 CocoaPods
安装 CocoaPods。详见 CocoaPods 安装指南。
在 Terminal 中进入项目根目录，并运行
pod init命令。项目文件夹下会生成一个Podfile文本文件。打开 Podfile 文件，添加即时通讯 IM SDK。将
Your project target替换为你的项目名称。platform :ios, '11.0' target 'Your project target' do pod 'Agora_Chat_iOS' end在项目根目录，运行以下命令集成即时通讯 IM SDK。成功安装后，Terminal 中会显示
Pod installation complete!，此时项目文件夹下会生成一个workspace文件。pod install在 Xcode 中打开
xcworkspace文件。
方法 2：手动导入即时通讯 IM SDK
下载最新版的 即时通讯 IM iOS SDK 并解压。
将 SDK 包内的
AgoraChat.framework复制到项目文件夹中。AgoraChat.framework包含 arm64、armv7 和 x86_64 指令集。打开 Xcode，进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content。
点击 + > Add Other… > Add Files 添加
AgoraChat.framework并将 Embed 属性设置为 Embed & Sign。添加完成后，项目会自动链接所需系统库。
参考
有关如何快速开始使用即时通讯 IM，详见 示例代码。
