# 实现收发消息 (/zh-CN/realtime-media/rtm/get-started/quick-start)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
本文将指导你如何利用 RTM Java SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。
同时,我们也提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
## 准备工作 [#准备工作]
开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的开发环境是否满足[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)中的最低版本要求。
## 构建项目 [#构建项目]
### 1. 项目配置 [#1-项目配置]
根据以下步骤配置你的项目:
1. 在 Android Studio 里,创建一个 **Empty Activity** 类型的项目并打开。
2. 通过以下任意一种方式获取最新的 RTM Java SDK 并导入你的项目。
使用 CDN
使用 Maven
1. [点击此处](https://download.shengwang.cn/rtm2/release/RTM_JAVA_SDK_for_Android_v2.3.1.zip)下载最新版本的 Java SDK。
2. 将 SDK 包内 `sdk` 文件夹中的所有文件拷贝到项目的 `/app/libs` 路径下。
3. 添加 SDK 引用。在 **Project** 窗口找到 `/Gradle Scripts/build.gradle(Module: .app)` 文件并添加如下代码:
1. 在 `defaultConfig` 节点添加 `ndk` 节点,指定支持的架构。
```groovy
Config {
// ...
ndk{
abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
}
}
```
:::info[信息]
支持的架构越多,App 的体积会越大,声网建议你根据实际情况添加需要支持的架构。一般在发布 Android App 时只需保留 armeabi-v7a 和 arm64-v8a 架构。
:::
2. 在 `android` 节点添加 `sourceSets` 节点,指定 `libs` 所在目录。
```groovy
android {
// ...
sourceSets {
main {
jniLibs.srcDirs = ['libs']
}
}
}
```
3. 在 `dependencies` 节点引入 `libs` 路径下所有的 jar 库。
```groovy
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
// ...
}
```
1. 自 v2.3.1 起,通过 Maven 集成 RTM SDK 时,需要添加声网 Maven 仓库。在项目根目录的 `settings.gradle` 文件中,向 `dependencyResolutionManagement.repositories` 添加如下配置,并保留项目已有的仓库:
```groovy
dependencyResolutionManagement {
repositories {
maven { url = 'https://download.shengwang.cn/maven/' }
google()
mavenCentral()
}
}
```
如果项目未使用 `dependencyResolutionManagement`,则在项目根目录的 `build.gradle` 文件中,向 `allprojects.repositories` 添加声网 Maven 仓库:
```groovy
allprojects {
repositories {
maven { url = 'https://download.shengwang.cn/maven/' }
google()
mavenCentral()
}
}
```
2. 在 `/Gradle Scripts/build.gradle(Module: .app)` 文件中添加如下代码,将 SDK 集成到你的 Android 项目中:
```groovy
dependencies {
// 将下方版本号替换为需要的 SDK 版本号,如 2.3.1
// 对于 2.2.7 及之后版本:
implementation 'cn.shengwang.rtm:android-java:2.3.1'
// 如需 Lite SDK,将上一行替换为(需确保已通过其他声网 SDK 引入对应的 aosl 依赖):
// implementation 'cn.shengwang.rtm:android-java-lite:2.3.1'
// 对于 2.2.6 及之前版本:
// implementation 'io.agora:agora-rtm:x.y.z'
}
```
:::info[信息]
如果你同时集成了 2.2.0 及以上版本的 RTM SDK 和 4.3.0 及以上版本的 RTC SDK,请参考 [FAQ](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue) 处理集成问题。
:::
3. 添加网络权限。打开 `app/src/main/AndroidManifest.xml` 文件,在 `` 的下一行添加如下代码:
```xml
```
4. 在 `/Gradle Scripts/proguard-rules.pro` 文件中添加如下代码,以防止声网 SDK 的代码被混淆:
```java
-keep class io.agora.**{*;}
```
### 2. 初始化 RTM [#2-初始化-rtm]
调用 RTM SDK 的任何 API 之前,需要先初始化一个 `RtmClient` 对象实例。参考如下步骤创建用户界面、初始化一个 `RtmClient` 对象实例。
1. 创建用户界面。实时消息 App 一般会有如下输入框和按钮:
- 用户名、频道名、消息输入框
- 登录、登出按钮
- 订阅、取消订阅频道按钮
- 发送消息按钮
本节提供简易的 UI 界面设计以便于验证功能特性,你可以根据实际项目需求进行修改。
1. 打开 `/app/res/layout/activity_main.xml` 文件,将文件内容替换为如下代码:
```xml
```
2. 打开 `app/res/values/strings.xml` 文件,将文件内容替换为如下代码:
```xml
RtmQuickstart
Login
Logout
Sub
Unsub
Publish MSG
User ID
Message content
Channel name
your_appid
your_token
```
:::info[信息]
你需要将示例中的 `your_appid` 和 `your_token` 字段替换成你项目的 App ID 和 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后将示例中的 `your_appid` 和 `your_token` 字段都替换成你项目的 App ID。
:::
2. 打开 `app/src/main/java/com/example/rtm/MainActivity.java` 文件,将文件内容替换为如下代码。你会发现此程序并不完整,不用紧张,我们在后续步骤中将一步步指导你补充完善代码。
:::info[信息]
`com.example.rtm` 为示例项目的路径,你需要根据实际项目路径查找文件并填写代码。
:::
```java
// Replace the package path with the path of your real project.
package com.example.rtm;
import android.content.pm.ActivityInfo;
import android.os.Bundle;
import android.view.View;
import android.widget.EditText;
import android.widget.TextView;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;
import io.agora.rtm.ErrorInfo;
import io.agora.rtm.LinkStateEvent;
import io.agora.rtm.LockEvent;
import io.agora.rtm.MessageEvent;
import io.agora.rtm.PresenceEvent;
import io.agora.rtm.PublishOptions;
import io.agora.rtm.ResultCallback;
import io.agora.rtm.RtmClient;
import io.agora.rtm.RtmConfig;
import io.agora.rtm.RtmConstants;
import io.agora.rtm.RtmEventListener;
import io.agora.rtm.RtmMessage;
import io.agora.rtm.StorageEvent;
import io.agora.rtm.SubscribeOptions;
import io.agora.rtm.TopicEvent;
public class MainActivity extends AppCompatActivity {
private EditText etUserId;
private EditText etChannelName;
private EditText etMessageContent;
// The user ID of the publisher
private String mUserId;
// The channel name of the message channel
private String mChannelName;
// The RTM client instance
private RtmClient mRtmClient;
// The TextView to show the messages that you send
private TextView mMessageHistory;
// Add the event listener
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);
}
@Override
protected void onResume() {
super.onResume();
}
@Override
protected void onDestroy() {
super.onDestroy();
}
public void onClickLogin(View v)
{
try {
etUserId = (EditText) findViewById(R.id.uid);
mUserId = etUserId.getText().toString();
if (mUserId == null || mUserId.isEmpty()) {
showToast("invalid userId");
return;
}
RtmConfig config = new RtmConfig.Builder(getBaseContext().getString(R.string.app_id), mUserId)
.eventListener(eventListener)
.build();
mRtmClient = RtmClient.create(config);
} catch (Exception e) {
showToast("create rtm client is null");
}
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Log in the RTM server
}
public void onClickSubscribe(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Subscribe to a channel
}
public void onClickLogout(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
}
// Log out from the RTM server
}
public void onClickUnsubscribe(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Unsubscribe from a channel
}
public void onClickSendChannelMsg(View v)
{
// Publish a message
}
// Write message history to TextView
public void writeToMessageHistory(String record)
{
mMessageHistory = findViewById(R.id.message_history);
mMessageHistory.append(record);
}
private void showToast(String text) {
Toast.makeText(this, text, Toast.LENGTH_SHORT).show();
}
}
```
如需了解更多初始化的信息,查看[初始配置](/zh-CN/api-reference/rtm/android/configuration)。
### 3. 添加事件监听 [#3-添加事件监听]
事件监听程序帮助你实现频道中消息、事件到达后的处理逻辑,添加以下代码到你的程序中以显示收到的消息或事件通知:
```java showLineNumbers
// Paste the following code snippet below "Add the event listener" comment
private RtmEventListener eventListener = new RtmEventListener() {
@Override
public void onMessageEvent(MessageEvent event) {
String text = "Message received from " + event.getPublisherId() + " Message: " + event.getMessage().getData() + "\n";
writeToMessageHistory(text);
}
@Override
public void onPresenceEvent(PresenceEvent event) {
String text = "receive presence event, user: " + event.getPublisherId() + " event: " + event.getEventType() + "\n";
writeToMessageHistory(text);
}
@Override
public void onLinkStateEvent(LinkStateEvent event) {
String text = "Link state event: " + event + "\n";
writeToMessageHistory(text);
}
};
```
### 4. 登录服务 [#4-登录服务]
你需要执行登录操作才能建立与 RTM 服务器的连接,然后才能调用 SDK 的其他 API。将以下代码添加到程序中:
```java showLineNumbers
// Paste the following code snippet below "Log in the RTM server" comment
String token =getBaseContext().getString(R.string.token);
mRtmClient.login(token, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully log in the RTM server!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
CharSequence text = "User: " + mUserId + " Fail to log in to the RTM system!" + errorInfo.toString();
int duration = Toast.LENGTH_SHORT;
runOnUiThread(new Runnable() {
public void run() {
Toast toast = Toast.makeText(getApplicationContext(), text, duration);
toast.show();
}
});
}
});
```
### 5. 收发消息 [#5-收发消息]
调用 `publish` 方法向 Message Channel 发送消息后,RTM 会把该消息分发给该频道的所有订阅者,以下代码演示如何发送字符串类型的消息,将此代码片段添加到程序中:
:::info[信息]
你需要先对消息负载进行字符串序列化,才能调用 `publish` 方法发送消息。
:::
```java showLineNumbers
// Paste the following code snippet below "Publish a message" comment
etMessageContent = findViewById(R.id.msg_box);
String message = etMessageContent.getText().toString();
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
PublishOptions options = new PublishOptions();
options.setCustomType("");
mRtmClient.publish(mChannelName, message, options, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
String text = "Message sent to channel " + mChannelName + " : " + message + "\n";
writeToMessageHistory(text);
}
@Override
public void onFailure(ErrorInfo errorInfo) {
String text = "Message fails to send to channel " + mChannelName + " Error: " + errorInfo + "\n";
writeToMessageHistory(text);
}
});
```
调用 `subscribe` 方法订阅此频道以接收此频道中的消息。将以下代码添加到程序中:
```java showLineNumbers
// Paste the following code snippet below "Subscribe to a channel" comment
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
SubscribeOptions options = new SubscribeOptions();
options.setWithMessage(true);
mRtmClient.subscribe(mChannelName, options, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully subscribe to the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to subscribe to the channel!\n");
}
});
```
如果你不再需要在此频道收发消息,你可以调用 `unsubscribe` 方法取消订阅此频道。将以下代码添加到程序中:
``` java
// Paste the following code snippet below "Unsubscribe from a channel" comment
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
mRtmClient.unsubscribe(mChannelName, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully unsubscribe from the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to unsubscribe from the channel!\n");
}
});
```
如需了解更多收发消息的信息,查看[消息](/zh-CN/api-reference/rtm/android/message)。
### 6. 登出服务 [#6-登出服务]
当不再需要使用 RTM 服务时,你可以调用 `logout` 方法登出 RTM 系统。将以下代码添加到程序中:
```java
// Paste the following code snippet below "Log out from the RTM server" comment
mRtmClient.logout(new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully log out from the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to log out from the channel!\n");
}
});
```
:::info[信息]
本操作会影响你账单中的 PCU 计费项。
:::
### 7. 组合到一起 [#7-组合到一起]
经过上述步骤,你程序中的代码应该如下所示:
```java
// Replace the package path with the path of your real project.
package com.example.rtm;
import android.content.pm.ActivityInfo;
import android.os.Bundle;
import android.view.View;
import android.widget.EditText;
import android.widget.TextView;
import android.widget.Toast;
import androidx.appcompat.app.AppCompatActivity;
import io.agora.rtm.ErrorInfo;
import io.agora.rtm.LinkStateEvent;
import io.agora.rtm.LockEvent;
import io.agora.rtm.MessageEvent;
import io.agora.rtm.PresenceEvent;
import io.agora.rtm.PublishOptions;
import io.agora.rtm.ResultCallback;
import io.agora.rtm.RtmClient;
import io.agora.rtm.RtmConfig;
import io.agora.rtm.RtmConstants;
import io.agora.rtm.RtmEventListener;
import io.agora.rtm.RtmMessage;
import io.agora.rtm.StorageEvent;
import io.agora.rtm.SubscribeOptions;
import io.agora.rtm.TopicEvent;
public class MainActivity extends AppCompatActivity {
private EditText etUserId;
private EditText etChannelName;
private EditText etMessageContent;
// The user ID of the publisher
private String mUserId;
// The channel name of the message channel
private String mChannelName;
// The RTM client instance
private RtmClient mRtmClient;
// The TextView to show the messages that you send
private TextView mMessageHistory;
// Add the event listener
private RtmEventListener eventListener = new RtmEventListener() {
@Override
public void onMessageEvent(MessageEvent event) {
String text = "Message received from " + event.getPublisherId() + " Message: " + event.getMessage().getData() + "\n";
writeToMessageHistory(text);
}
@Override
public void onPresenceEvent(PresenceEvent event) {
String text = "receive presence event, user: " + event.getPublisherId() + " event: " + event.getEventType() + "\n";
writeToMessageHistory(text);
}
@Override
public void onLinkStateEvent(LinkStateEvent event) {
String text = "Link state event: " + event + "\n";
writeToMessageHistory(text);
}
};
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);
}
@Override
protected void onResume() {
super.onResume();
}
@Override
protected void onDestroy() {
super.onDestroy();
}
public void onClickLogin(View v)
{
try {
etUserId = (EditText) findViewById(R.id.uid);
mUserId = etUserId.getText().toString();
if (mUserId == null || mUserId.isEmpty()) {
showToast("invalid userId");
return;
}
RtmConfig config = new RtmConfig.Builder(getBaseContext().getString(R.string.app_id), mUserId)
.eventListener(eventListener)
.build();
mRtmClient = RtmClient.create(config);
} catch (Exception e) {
showToast("create rtm client is null");
}
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Log in the RTM server
String token =getBaseContext().getString(R.string.token);
mRtmClient.login(token, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully log in the RTM server!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
CharSequence text = "User: " + mUserId + " Fail to log in to the RTM system!" + errorInfo.toString();
int duration = Toast.LENGTH_SHORT;
runOnUiThread(new Runnable() {
public void run() {
Toast toast = Toast.makeText(getApplicationContext(), text, duration);
toast.show();
}
});
}
});
}
public void onClickSubscribe(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Subscribe to a channel
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
SubscribeOptions options = new SubscribeOptions();
options.setWithMessage(true);
mRtmClient.subscribe(mChannelName, options, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully subscribe to the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to subscribe to the channel!\n");
}
});
}
public void onClickLogout(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
}
// Log out from the RTM server
mRtmClient.logout(new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully log out from the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to log out from the channel!\n");
}
});
}
public void onClickUnsubscribe(View v)
{
if (mRtmClient == null) {
showToast("rtm client is null");
return;
}
// Unsubscribe from a channel
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
mRtmClient.unsubscribe(mChannelName, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
writeToMessageHistory("Successfully unsubscribe from the channel!\n");
}
@Override
public void onFailure(ErrorInfo errorInfo) {
writeToMessageHistory("Fail to unsubscribe from the channel!\n");
}
});
}
public void onClickSendChannelMsg(View v)
{
etMessageContent = findViewById(R.id.msg_box);
String message = etMessageContent.getText().toString();
// Publish a message
etChannelName = (EditText) findViewById(R.id.channel_name);
mChannelName = etChannelName.getText().toString();
PublishOptions options = new PublishOptions();
options.setCustomType("");
mRtmClient.publish(mChannelName, message, options, new ResultCallback() {
@Override
public void onSuccess(Void responseInfo) {
String text = "Message sent to channel " + mChannelName + " : " + message + "\n";
writeToMessageHistory(text);
}
@Override
public void onFailure(ErrorInfo errorInfo) {
String text = "Message fails to send to channel " + mChannelName + " Error: " + errorInfo + "\n";
writeToMessageHistory(text);
}
});
}
// Write message history to TextView
public void writeToMessageHistory(String record)
{
mMessageHistory = findViewById(R.id.message_history);
mMessageHistory.append(record);
}
private void showToast(String text) {
Toast.makeText(this, text, Toast.LENGTH_SHORT).show();
}
}
```
现在,你可以开始运行你的程序:
1. 保存项目。
2. 在菜单栏中依次点击 **Run > Select Device > Select Multiple Devices** 并添加两个设备。例如,选择一个虚拟机和一个真机。
3. 运行项目。成功运行后,你可以在两个设备中看到 App 界面。
4. 将一个设备作为接收端,进行如下操作:
1. 输入用户名,点击 **LOGIN**。
2. 输入频道名,点击 **SUB**。
5. 将另一个设备作为发送端,进行如下操作:
1. 输入不同的用户名,点击 **LOGIN**。
2. 输入相同的频道名。
3. 输入消息,点击 **PUBLISH MSG**。
6. 将上面的发送端和设备端互换,重复步骤 4 和 5。
如果两个设备均可收发消息,那么你已经成功集成并正确使用了 RTM 服务。
## 贯穿始终 [#贯穿始终]
相比于介绍如何写出代码,声网更愿意帮助你掌握上述程序编写的过程和逻辑。上述程序依次完成了以下操作,让你可以正确地收发消息:
1. 设置并初始化 RTM 对象。
2. 添加 `onMessageEvent`、`onPresenceEvent` 和 `onLinkStateEvent` 事件监听函数。
3. 调用 `login` 登录了 RTM 服务。
4. 调用 `subscribe` 订阅了一个 Message Channel。
5. 调用 `publish` 发送消息。
6. 调用 `unsubscribe` 取消订阅一个 Message Channel。
7. 调用 `logout` 登出 RTM 系统。
## 下一步 [#下一步]
现在,你已经学会了如何使用 RTM Java SDK 来实现 Message Channel 的收发消息功能。下一步,你可以通过 SDK 的 [API 参考](/zh-CN/api-reference/rtm/android/configuration)了解更多功能的使用方法。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" />
本文将指导你如何利用 RTM Objective-C SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。
## 准备工作 [#准备工作-1]
开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的开发环境是否满足[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)中的最低版本要求。
## 构建项目 [#构建项目-1]
### 1. 项目配置 [#1-项目配置-1]
根据以下步骤配置你的项目:
1. 在 Xcode 中创建一个 iOS 平台下的 **Single View App**,项目设置如下:
- **Product Name** 设为 `RtmQuickstart`。
- **Organization Identifier** 设为 `agora`。
- **User Interface** 选择 **Storyboard**。
- **Language** 选择 **Objective-C**。
2. 通过以下任意一种方式获取最新的 RTM Objective-C SDK 并导入你的项目。
使用 CDN
使用 Cocoapods
通过 SPM 集成 SDK
1. [点击此处](https://download.shengwang.cn/rtm2/release/RTM_OC_SDK_v2.3.1.zip)下载最新版本的 Objective-C SDK。
2. 复制 SDK 包中 `/libs` 路径下所有的 `xcframework` 文件至项目路径下。
3. 打开 Xcode,进入 **TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content** 菜单。
4. 点击 **+ > Add Other… > Add Files** 添加所有的 `xcframework` 文件,并确保添加的动态库 **Embed** 属性设置为 **Embed & Sign**。
添加完成后,项目会自动链接所需系统库。
1. 开始前请确保你已安装 Cocoapods,如尚未安装 Cocoapods,参考 [Getting Started with CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 安装说明。
2. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。
3. 打开 `Podfile` 文件。自 v2.3.1 起,需要添加声网 CocoaPods 源,并保留项目已有的源。将文件修改为如下内容,注意将 `Your App` 替换为你的 Target 名称。
```ruby
source 'https://download.shengwang.cn/cocoapods/'
platform :ios, '11.0'
target 'Your App' do
# 对于 2.2.8 及之后版本:
# RtmKit 为 RTM 主库,RtmBasic 为 aosl 基础库
pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmKit']
pod 'ShengWang-Rtm', '2.3.1', :subspecs => ['RtmBasic']
# 对于 2.2.7 版本:
# pod 'ShengwangRtm', 'x.y.z'
# 对于 2.2.6 及之前版本:
# pod 'AgoraRtm', 'x.y.z'
# 如需获取 2.2.0 之前的版本,请将包名修改为 AgoraRtm_iOS
end
```
4. 在终端内运行 `pod install` 命令安装声网 SDK。成功安装后,Terminal 中会显示 `Pod installation complete!`。
5. 成功安装后,项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件,通过 Xcode 打开该文件进行后续操作。
使用如下链接,通过 SPM (Swift Package Manager) 集成 SDK:
```text
https://github.com/AgoraIO/AgoraRtm_Apple.git
```
:::info[信息]
如果你同时集成了 2.2.0 及以上版本的 RTM SDK 和 4.3.0 及以上版本的 RTC SDK,请参考 [FAQ](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue) 处理集成问题。
:::
### 2. 初始化 RTM [#2-初始化-rtm-1]
调用 RTM SDK 的任何 API 之前,需要先初始化一个 `AgoraRtmClientKit` 对象实例。参考如下步骤创建用户界面、初始化一个 `AgoraRtmClientKit` 对象实例。
1. 创建用户界面。实时消息 App 一般会有如下输入框和按钮:
- 用户名、频道名、消息输入框
- 登录、登出按钮
- 订阅、取消订阅频道按钮
- 发送消息按钮
本节提供简易的 UI 界面设计以便于验证功能特性,你可以根据实际项目需求进行修改。
1. 使用 **Code View** 打开 `Main.storyboard` 并将文件内容替换为以下代码:
```xml
```
2. 打开 `ViewController.h` 文件,将文件内容替换为如下代码:
```objc
#import
#import
@interface ViewController : UIViewController
// Buttons
@property (weak, nonatomic) IBOutlet UIButton *LoginButton;
@property (weak, nonatomic) IBOutlet UIButton *LogoutButton;
@property (weak, nonatomic) IBOutlet UIButton *SubsctibeButton;
@property (weak, nonatomic) IBOutlet UIButton *UnSubscribeButton;
@property (weak, nonatomic) IBOutlet UIButton *GroupMsgButton;
// Textfields
@property (weak, nonatomic) IBOutlet UITextField *UserIDTextField;
@property (weak, nonatomic) IBOutlet UITextField *ChannelIDTextField;
@property (weak, nonatomic) IBOutlet UITextField *GroupMsgTextField;
@property (weak, nonatomic) IBOutlet UITextView *MsgTextView;
@end
```
2. 打开 `ViewController.m` 文件,将文件内容替换为如下代码。你会发现此程序并不完整,不用紧张,我们在后续步骤中将一步步指导你补充完善代码。
:::info[信息]
你需要将示例中的 `your_appid` 和 `your_token` 字段替换成你项目的 App ID 和 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后将示例中的 `your_appid` 和 `your_token` 字段都替换成你项目的 App ID。
:::
```objc
#import "ViewController.h"
@interface ViewController ()
@property(nonatomic, strong)AgoraRtmClientKit* kit;
@property NSString* appID;
@property NSString* token;
@property NSString* uid;
@property NSString* peerID;
@property NSString* channelID;
@property NSString* peerMsg;
@property NSString* channelMsg;
@property NSString* text;
@property NSMutableArray* textArray;
- (void)AddMsgToRecord:(NSString*)text;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// Enter your App ID
self.appID = @"your_appid";
self.MsgTextView.textColor = UIColor.blueColor;
self.textArray = [[NSMutableArray alloc]init];
}
// Add the event listener
// Add message to the UI TextView
- (void)AddMsgToRecord:(NSString*)text {
[self.textArray addObject:(self.text)];
self.MsgTextView.text = [self.textArray componentsJoinedByString:(@"\n")];
}
- (IBAction)Login:(id)sender {
self.uid = self.UserIDTextField.text;
// Enter your token
self.token = @"your_token";
AgoraRtmClientConfig* rtm_config = [[AgoraRtmClientConfig alloc] initWithAppId:_appID userId:_uid];
NSError* initError = nil;
_kit = [[AgoraRtmClientKit alloc] initWithConfig:rtm_config delegate:self error:&initError];
if (initError != nil) {
self.text = [NSString stringWithFormat:@"init error %@",initError];
NSLog(@"%@", self.text);
[self AddMsgToRecord:(self.text)];
}
// Log in the RTM server
}
- (IBAction)Logout:(id)sender {
if (_kit != nil) {
// Log out from the RTM server
}
}
- (IBAction)SubscribeChannel:(id)sender {
self.channelID = self.ChannelIDTextField.text;
if (_kit != nil) {
// Subscribe to a channel
}
}
- (IBAction)UnsubscribeChannel:(id)sender {
if (_kit == nil)
return;
// Unsubscribe from a channel
}
- (IBAction)SendMessageToMessageChannel:(id)sender {
self.channelID = self.ChannelIDTextField.text;
self.channelMsg = self.GroupMsgTextField.text;
// Publish a message
}
@end
```
如需了解更多初始化的信息,查看[初始配置](/zh-CN/api-reference/rtm/ios/configuration)。
### 3. 添加事件监听 [#3-添加事件监听-1]
事件监听程序帮助你实现频道中消息、事件到达后的处理逻辑,添加以下代码到你的程序中以显示收到的消息或事件通知:
```objc showLineNumbers
// Paste the following code snippet below "Add the event listener" comment
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
NSLog(@"%@", self.text);
self.text = [NSString stringWithFormat:@"receive message\nFrom channel: %@\npublisher:%@\nmessage:%@\n",event.channelName,event.publisher, event.message.stringData];
[self AddMsgToRecord:(self.text)];
}
```
### 4. 登录服务 [#4-登录服务-1]
你需要执行登录操作才能建立与 RTM 服务器的连接,然后才能调用 SDK 的其他 API。将以下代码添加到程序中:
```objc showLineNumbers
// Paste the following code snippet below "Log in the RTM server" comment
[_kit loginByToken:self.token completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo.errorCode != AgoraRtmErrorOk){
self.text = [NSString stringWithFormat:@"Login failed for user %@. Code: %ld",self.uid, (long)errorInfo.errorCode];
NSLog(@"%@", self.text);
} else {
NSLog(@"%@", self.text);
self.text = [NSString stringWithFormat:@"Login successful for user %@. Code: %ld",self.uid, (long)errorInfo.errorCode];
}
[self AddMsgToRecord:(self.text)];
}];
```
### 5. 收发消息 [#5-收发消息-1]
调用 `publish` 方法向 Message Channel 发送消息后,RTM 会把该消息分发给该频道的所有订阅者,以下代码演示如何发送字符串类型的消息,将此代码片段添加到程序中:
:::info[信息]
你需要先对消息负载进行字符串序列化,才能调用 `publish` 方法发送消息。
:::
```objc showLineNumbers
// Paste the following code snippet below "Publish a message" comment
[_kit publish:self.channelID message:self.channelMsg option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil) {
self.text = [NSString stringWithFormat:@"Message sent to channel %@ : %@", self.channelID, self.channelMsg];
} else {
self.text = [NSString stringWithFormat:@"Message failed to send to channel %@ : %@ ErrorCode: %ld", self.channelID, self.channelMsg, (long)errorInfo.errorCode];
}
[self AddMsgToRecord:(self.text)];
}];
```
调用 `subscribeWithChannel` 方法订阅此频道以接收此频道中的消息。将以下代码添加到程序中:
```objc showLineNumbers
// Paste the following code snippet below "Subscribe to a channel" comment
[_kit subscribeWithChannel:self.channelID option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if(errorInfo == nil) {
self.text = [NSString stringWithFormat:@"Successfully subscribe channel %@",self.channelID];
NSLog(@"%@", self.text);
} else {
self.text = [NSString stringWithFormat:@"Failed to subscribe channel %@ Code: %ld",self.channelID, (long)errorInfo.errorCode];
NSLog(@"%@", self.text);
}
[self AddMsgToRecord:(self.text)];
}];
```
如果你不再需要在此频道收发消息,你可以调用 `unsubscribeWithChannel` 方法取消订阅此频道。将以下代码添加到程序中:
``` objc showLineNumbers
// Paste the following code snippet below "Unsubscribe from a channel" comment
[_kit unsubscribeWithChannel:self.channelID completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil){
self.text = [NSString stringWithFormat:@"Leave channel successful"];
} else {
self.text = [NSString stringWithFormat:@"Failed to leave channel Code: %ld", (long)errorInfo.errorCode];
}
[self AddMsgToRecord:(self.text)];
}];
```
如需了解更多收发消息的信息,查看[消息](/zh-CN/api-reference/rtm/ios/message)。
### 6. 登出服务 [#6-登出服务-1]
当不再需要使用 RTM 服务时,你可以调用 `logout` 方法登出 RTM 系统。将以下代码添加到程序中:
```objc showLineNumbers
// Paste the following code snippet below "Log out from the RTM server" comment
[_kit logout:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil){
self.text = [NSString stringWithFormat:@"Logout successful"];
NSLog(@"%@", self.text);
[_kit destroy];
_kit = nil;
} else {
self.text = [NSString stringWithFormat:@"Logout failed. Code: %ld",(long)errorInfo.errorCode];
NSLog(@"%@", self.text);
}
[self AddMsgToRecord:(self.text)];
}];
```
:::info[信息]
本操作会影响你账单中的 PCU 计费项。
:::
### 7. 组合到一起 [#7-组合到一起-1]
经过上述步骤,你程序中的代码应该如下所示:
```objc
#import "ViewController.h"
@interface ViewController ()
@property(nonatomic, strong)AgoraRtmClientKit* kit;
@property NSString* appID;
@property NSString* token;
@property NSString* uid;
@property NSString* peerID;
@property NSString* channelID;
@property NSString* peerMsg;
@property NSString* channelMsg;
@property NSString* text;
@property NSMutableArray* textArray;
- (void)AddMsgToRecord:(NSString*)text;
@end
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
// Enter your App ID
self.appID = @"your_appid";
self.MsgTextView.textColor = UIColor.blueColor;
self.textArray = [[NSMutableArray alloc]init];
}
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
NSLog(@"%@", self.text);
self.text = [NSString stringWithFormat:@"receive message\nFrom channel: %@\npublisher:%@\nmessage:%@\n",event.channelName,event.publisher, event.message.stringData];
[self AddMsgToRecord:(self.text)];
}
// Add message to the UI TextView
- (void)AddMsgToRecord:(NSString*)text {
[self.textArray addObject:(self.text)];
self.MsgTextView.text = [self.textArray componentsJoinedByString:(@"\n")];
}
- (IBAction)Login:(id)sender {
self.uid = self.UserIDTextField.text;
// Enter your token
self.token = @"your_token";
AgoraRtmClientConfig* rtm_config = [[AgoraRtmClientConfig alloc] initWithAppId:_appID userId:_uid];
NSError* initError = nil;
_kit = [[AgoraRtmClientKit alloc] initWithConfig:rtm_config delegate:self error:&initError];
if (initError != nil) {
self.text = [NSString stringWithFormat:@"init error %@",initError];
NSLog(@"%@", self.text);
[self AddMsgToRecord:(self.text)];
}
// Log in the RTM server
[_kit loginByToken:self.token completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo.errorCode != AgoraRtmErrorOk){
self.text = [NSString stringWithFormat:@"Login failed for user %@. Code: %ld",self.uid, (long)errorInfo.errorCode];
NSLog(@"%@", self.text);
} else {
NSLog(@"%@", self.text);
self.text = [NSString stringWithFormat:@"Login successful for user %@. Code: %ld",self.uid, (long)errorInfo.errorCode];
}
[self AddMsgToRecord:(self.text)];
}];
}
- (IBAction)Logout:(id)sender {
if (_kit != nil) {
// Log out from the RTM server
[_kit logout:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil){
self.text = [NSString stringWithFormat:@"Logout successful"];
NSLog(@"%@", self.text);
[_kit destroy];
_kit = nil;
} else {
self.text = [NSString stringWithFormat:@"Logout failed. Code: %ld",(long)errorInfo.errorCode];
NSLog(@"%@", self.text);
}
[self AddMsgToRecord:(self.text)];
}];
}
- (IBAction)SubscribeChannel:(id)sender {
self.channelID = self.ChannelIDTextField.text;
if (_kit != nil) {
// Subscribe to a channel
[_kit subscribeWithChannel:self.channelID option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if(errorInfo == nil) {
self.text = [NSString stringWithFormat:@"Successfully subscribe channel %@",self.channelID];
NSLog(@"%@", self.text);
} else {
self.text = [NSString stringWithFormat:@"Failed to subscribe channel %@ Code: %ld",self.channelID, (long)errorInfo.errorCode];
NSLog(@"%@", self.text);
}
[self AddMsgToRecord:(self.text)];
}];
}
}
- (IBAction)UnsubscribeChannel:(id)sender {
if (_kit == nil)
return;
// Unsubscribe from a channel
[_kit unsubscribeWithChannel:self.channelID completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil){
self.text = [NSString stringWithFormat:@"Leave channel successful"];
} else {
self.text = [NSString stringWithFormat:@"Failed to leave channel Code: %ld", (long)errorInfo.errorCode]; }
[self AddMsgToRecord:(self.text)];
}];
}
- (IBAction)SendMessageToMessageChannel:(id)sender {
self.channelID = self.ChannelIDTextField.text;
self.channelMsg = self.GroupMsgTextField.text;
// Publish a message
[_kit publish:self.channelID message:self.channelMsg option:nil completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
if (errorInfo == nil)
{
self.text = [NSString stringWithFormat:@"Message sent to channel %@ : %@", self.channelID, self.channelMsg]; }
else
{
self.text = [NSString stringWithFormat:@"Message failed to send to channel %@ : %@ ErrorCode: %ld", self.channelID, self.channelMsg, (long)errorInfo.errorCode]; }
[self AddMsgToRecord:(self.text)];
}];
}
@end
```
现在,你可以开始运行你的程序:
1. 保存项目。
2. 复制当前项目,使用相同的 `appId` 和不同的 `userId`。
3. 运行上面的两个项目。成功运行后,你可以在两个设备中看到 App 界面。
4. 将一个设备作为接收端,进行如下操作:
1. 输入用户名,点击 **Login**。
2. 输入频道名,点击 **Subscribe**。
5. 将另一个设备作为发送端,进行如下操作:
1. 输入不同的用户名,点击 **Subscribe**。
2. 输入相同的频道名。
3. 输入消息,点击 **Publish MSG**。
6. 将上面的发送端和设备端互换,重复步骤 4 和 5。
如果两个设备均可收发消息,那么你已经成功集成并正确使用了 RTM 服务。
## 贯穿始终 [#贯穿始终-1]
相比于介绍如何写出代码,声网更愿意帮助你掌握上述程序编写的过程和逻辑。上述程序依次完成了以下操作,让你可以正确地收发消息:
1. 设置并初始化 RTM 对象。
2. 添加 `didReceiveMessageEvent` 事件监听函数。
3. 调用 `loginByToken` 登录了 RTM 服务。
4. 调用 `subscribeWithChannel` 订阅了一个 Message Channel。
5. 调用 `publish` 发送消息。
6. 调用 `unsubscribeWithChannel` 取消订阅一个 Message Channel。
7. 调用 `logout` 登出 RTM 系统。
## 下一步 [#下一步-1]
现在,你已经学会了如何使用 RTM Objective-C SDK 来实现 Message Channel 的收发消息功能。下一步,你可以通过 SDK 的 [API 参考](/zh-CN/api-reference/rtm/ios/configuration)了解更多功能的使用方法。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
本文将指导你如何利用 RTM JavaScript SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。
## 准备工作 [#准备工作-2]
开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的浏览器是否满足[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)中的最低版本要求。
## 获取 SDK [#获取-sdk]
你可以通过以下任意一种方式获取最新的 RTM JavaScript SDK。
#### 方式一:使用 CDN 添加 SDK [#方式一使用-cdn-添加-sdk]
[点击此处](https://download.agora.io/rtm2/release/Agora_RTM_JavaScript_SDK_for_Web_v2.3.0.zip)下载最新版本的 JavaScript SDK,并在你的项目中添加以下代码引用它:
```javascript
// 使用 CDN 直接将以下代码添加到你的 Web 应用中,或下载 SDK 文件后在本地引用
// 将 x.y.z 替换为具体的 SDK 版本号,如 2.3.0
// 可通过发版说明获取最新版本号
```
#### 方式二:使用包管理器引入 SDK [#方式二使用包管理器引入-sdk]
1. 根据你的应用场景和开发需要,选择一种方式和工具安装 SDK。
**场景一**:项目仅使用 RTM 产品,且没有集成声网任何版本的 RTC 产品。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtm
```
```shell
pnpm add agora-rtm
```
```shell
yarn add agora-rtm
yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
```
**场景二**:项目中已经集成了 RTC 产品,需要新接入 RTM 产品。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtm
```
```shell
pnpm add agora-rtm
```
如果项目使用的 RTC 版本与 RTM 中依赖的 RTC 版本不一致,会收到提示:`unmet peer agora-rtc-sdk-ng@4.22.0: found 4.16.0`。此时你需要升级 RTC 的版本:
```shell
pnpm update agora-rtc-sdk-ng@4.22.0
```
或者通过以下命令同时保留两个版本的 RTC 库:
```shell
pnpm add agora-rtc-sdk-ng-4.16@npm:agora-rtc-sdk-ng@4.16.0 --save-exact
pnpm add agora-rtc-sdk-ng@4.22.0 --save-exact
```
然后将代码中原来的 `import AgoraRTC from "agora-rtc-sdk-ng"` 替换为如下行:
```javascript
import AgoraRTC from "agora-rtc-sdk-ng-4.16"
```
:::warning[注意]
保留两个版本的 RTC 库会增加项目的包体积。
:::
```shell
yarn add agora-rtm
```
如果项目使用的 RTC 版本与 RTM 中依赖的 RTC 版本不一致,会收到提示:`unmet peer agora-rtc-sdk-ng@4.22.0: found 4.16.0`。此时你需要升级 RTC 的版本:
```shell
yarn upgrade agora-rtc-sdk-ng@4.22.0
```
或者通过以下命令同时保留两个版本的 RTC 库:
```shell
yarn add agora-rtc-sdk-ng-4.16@npm:agora-rtc-sdk-ng@4.16.0 --save-exact
yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
```
然后将代码中原来的 `import AgoraRTC from "agora-rtc-sdk-ng"` 替换为如下行:
```javascript
import AgoraRTC from "agora-rtc-sdk-ng-4.16"
```
:::warning[注意]
保留两个版本的 RTC 库会增加项目的包体积。
:::
**场景三**:你的项目是全新的,且需要同时集成 RTM 和 RTC,以利用其共频道、数据优先级控制等能力。这种场景下建议你集成融合版本的 SDK。
使用 npm
使用 pnpm
使用 Yarn
```shell
npm install agora-rtx
```
```shell
pnpm add agora-rtx --shamefully-hoist
```
```shell
# 若版本为 2.2.0
# yarn add agora-rtx
# yarn add agora-rtc-sdk-ng@4.22.0 --save-exact
# 2.2.0 及之后版本
yarn add agora-rtx
```
2. 完成安装后,在你的 `app.js` 中引入 RTM:
```javascript
// 如果安装的是 agora-rtm
import AgoraRTM from 'agora-rtm';
// 如果安装的是融合版 agora-rtx
// import AgoraRTM from 'agora-rtx';
// import AgoraRTC from 'agora-rtc-sdk-ng';
```
## 构建项目 [#构建项目-2]
### 1. 项目配置 [#1-项目配置-2]
新建一个文件夹存放项目文件,进入文件夹中为你的 App 创建文件并安装其他依赖项。以下为在终端操作的命令行示例:
```shell showLineNumbers
mkdir HelloWorld
cd HelloWorld
# Your app is in index.html.
touch index.html
```
### 2. 初始化 RTM [#2-初始化-rtm-2]
初始化 `rtm` 时,你需要提供如下信息:
- 从控制台获取的 App ID(`appId`)。
- 你自行定义的用户 ID(`userId`),你需要保证其全局唯一性。
```html showLineNumbers
Text Display App
```
:::info[信息]
你需要在初始化时填入项目的 App ID 和 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后在初始化时只需填入项目的 App ID。
:::
### 3. 添加事件监听 [#3-添加事件监听-2]
事件监听程序帮助你实现频道中消息、事件到达后的处理逻辑,添加以下代码到你的程序中以显示收到的消息或事件通知:
```javascript showLineNumbers
// Paste the following code snippet below "Add the event listener" comment
// Message event handler.
rtm.addEventListener("message", event => {
showMessage(event.publisher, event.message);
});
// Pressence event handler.
rtm.addEventListener("presence", event => {
if (event.eventType === "SNAPSHOT") {
showMessage("INFO", "I Join");
}
else {
showMessage("INFO", event.publisher + " is " + event.eventType);
}
});
// Link state changed event handler.
rtm.addEventListener("linkState", event => {
const currentState = event.currentState;
const previousState = event.previousState;
const serviceType = event.serviceType;
const operation = event.operation;
const reason = event.reason;
const affectedChannels = event.affectedChannels;
const timestamp = event.timestamp;
const isResumed = event.isResumed;
showMessage("INFO", JSON.stringify(event));
});
```
### 4. 登录服务 [#4-登录服务-2]
你需要执行登录操作才能建立与 RTM 服务器的连接,然后才能调用 SDK 的其他 API。将以下代码添加到程序中,并传入你在服务端自行生成的 Token:
```javascript showLineNumbers
// Paste the following code snippet below "Log in the RTM server." comment
try {
const result = await rtm.login({ token: 'your_token' });
console.log(result);
} catch (status) {
console.log(status);
}
```
### 5. 收发消息 [#5-收发消息-2]
调用 `publish` 方法向 Message Channel 发送消息后,RTM 会把该消息分发给该频道的所有订阅者,以下代码演示如何发送字符串类型的消息,将此代码片段添加到程序中:
:::info[信息]
你需要先对消息负载进行字符串序列化,才能调用 `publish` 方法发送消息。
:::
```javascript showLineNumbers
// Paste the following code snippet below "Publish a message" comment
const publishMessage = async (message) => {
const payload = { type: "text", message: message };
const publishMessage = JSON.stringify(payload);
const publishOptions = { channelType: 'MESSAGE'}
try {
const result = await rtm.publish(msChannelName, publishMessage, publishOptions);
showMessage(userId, publishMessage);
console.log(result);
} catch (status) {
console.log(status);
}
}
```
调用 `subscribe` 方法订阅此频道以接收此频道中的消息。将以下代码添加到程序中:
```javascript showLineNumbers
// Paste the following code snippet below "Subscribe to a channel." comment
try {
const result = await rtm.subscribe(msChannelName);
console.log(result);
} catch (status) {
console.log(status);
}
```
如需了解更多收发消息的信息,查看[消息](/zh-CN/api-reference/rtm/web/message)。
### 6. 组合到一起 [#6-组合到一起]
经过上述步骤,你程序中的代码应该如下所示:
```html showLineNumbers
Text Display App
```
现在,你可以开始运行你的程序:
1. 保存 **index.html**,并在浏览器中运行。我们称此时看到的页面为 A 页面。
2. 复制当前项目,在 **index.html** 的 `userId` 变量中填入一个不同的用户 ID,保存后运行。我们称此时看到的页面为 B 页面。
3. 在 A 页面文本输入框中输入要发送的信息,点击 **Send** 按钮发送,然后在 B 页面中观察是否收到信息。
4. 在 B 页面文本输入框中输入要发送的信息,点击 **Send** 按钮发送,然后在 A 页面中观察是否收到信息。
如果步骤 3 和步骤 4 中都能看到正确的信息,那么你已经成功集成并正确使用了 RTM 服务。
## 贯穿始终 [#贯穿始终-2]
相比于介绍如何写出代码,声网更愿意帮助你掌握上述程序编写的过程和逻辑。上述程序依次完成了以下操作,让你可以正确地收发消息:
1. 设置并初始化 RTM 对象。
2. 添加 `message`、`presence` 和 `linkState` 事件监听函数。
3. 调用 `login` 登录了 RTM 服务。
4. 调用 `subscribe` 订阅了一个 Message Channel。
5. 调用 `publish` 发送消息。
## 下一步 [#下一步-2]
现在,你已经学会了如何使用 RTM JavaScript SDK 来实现 Message Channel 的收发消息功能。下一步,你可以通过 SDK 的 [API 参考](/zh-CN/api-reference/rtm/web/configuration)了解更多功能的使用方法。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" />
本文将指导你如何利用 RTM HarmonyOS SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。
## 准备工作 [#准备工作-3]
开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的开发环境是否满足[平台支持](/zh-CN/realtime-media/rtm/reference/capabilities-and-compatibility/platform-support)中的最低版本要求。
## 构建项目 [#构建项目-3]
### 1. 获取 SDK [#1-获取-sdk]
[点击此处](https://download.shengwang.cn/rtm2/release/RTM_ArkTS_SDK_for_HarmonyOS_v2.3.1.zip)下载最新版本的 HarmonyOS SDK。
下载完成后,解压 SDK 包,你将获得一个 `.har` 文件,这是 HarmonyOS 的静态共享包格式。
:::info[信息]
如果你同时集成了 2.2.0 及以上版本的 RTM SDK 和 4.3.0 及以上版本的 RTC SDK,请参考 [FAQ](/zh-CN/reference/faq/integration/rtm2_rtc_integration_issue) 处理集成问题。
:::
### 2. 项目配置 [#2-项目配置]
根据以下步骤配置你的项目:
1. 在 DevEco Studio 中,创建一个新的 HarmonyOS 应用项目。
2. 将下载的 `.har` 文件导入到你的项目中:
- 在项目根目录下创建 `libs` 文件夹(如果不存在)
- 将 `.har` 文件复制到 `libs` 文件夹中
- 在模块的 `oh-package.json5` 文件中添加依赖:
```json
{
"dependencies": {
"@shengwang/rtm-full": "file:./libs/AgoraRtmSDK.har"
}
}
```
3. 在模块的 `module.json5` 文件中添加网络权限:
```json
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
},
{
"name": "ohos.permission.GET_NETWORK_INFO"
}
]
}
}
```
4. 同步项目依赖,确保 SDK 正确导入。
### 3. 创建并初始化 RTM [#3-创建并初始化-rtm]
调用 RTM SDK 的任何 API 之前,需要先创建一个 `RtmClient` 对象实例。在你的项目中创建一个 ArkTS 文件(例如 `RtmManager.ets`),添加以下代码作为程序模版。你会发现此程序并不完整,不用紧张,我们在后续步骤中将一步步指导你补充完善代码。
:::info[信息]
你需要在初始化时填入已开通 RTM 服务的项目的 App ID 和 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后在示例中填入项目的 App ID 即可。
:::
```typescript
import { RtmClient, RtmConfig, RtmChannelType, SubscribeOptions, PublishOptions } from '@shengwang/rtm-full';
import type { LinkStateEvent, MessageEvent, PresenceEvent } from '@shengwang/rtm-full';
import { RtmError } from '@shengwang/rtm-full';
// 填入你的 App ID
const APP_ID = '';
// 填入你的 Token(测试阶段可以为空字符串)
const TOKEN = '';
export class RtmManager {
private rtmClient: RtmClient | null = null;
private userId: string = '';
/**
* 初始化 RTM 客户端
*/
async initialize(userId: string): Promise {
try {
this.userId = userId;
// 创建 RTM 配置
const config: RtmConfig = {
appId: APP_ID,
userId: userId
};
// 创建 RTM 客户端实例
this.rtmClient = new RtmClient(config);
// 添加事件监听(后续步骤中补充)
console.log('RTM client initialized successfully');
} catch (error) {
console.error('Failed to initialize RTM client:', error);
if (error instanceof RtmError) {
throw new Error(`初始化失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('RTM client initialization failed');
}
}
}
/**
* 登录 RTM 服务
*/
async login(): Promise {
// 后续步骤中补充
}
/**
* 订阅频道
*/
async subscribe(channelName: string): Promise {
// 后续步骤中补充
}
/**
* 取消订阅频道
*/
async unsubscribe(channelName: string): Promise {
// 后续步骤中补充
}
/**
* 发送消息
*/
async publish(channelName: string, message: string): Promise {
// 后续步骤中补充
}
/**
* 登出 RTM 服务
*/
async logout(): Promise {
// 后续步骤中补充
}
/**
* 释放资源
*/
release(): void {
if (this.rtmClient) {
this.rtmClient.release();
this.rtmClient = null;
}
}
}
```
### 4. 添加事件监听 [#4-添加事件监听]
事件监听程序帮助你实现频道中消息、事件到达后的处理逻辑。在 `initialize` 方法中添加事件监听器,以显示收到的消息或事件通知:
```typescript showLineNumbers
// 在 initialize 方法中,创建 RTM 客户端后添加以下代码
// 添加事件监听(替换之前的注释)
// 监听连接状态变化
this.rtmClient.addEventListener('linkState', (event) => {
console.log('Link state changed:', event);
console.log(`State: ${event.previousState} -> ${event.currentState}`);
console.log(`Reason: ${event.reason}`);
});
// 监听接收到的消息
this.rtmClient.addEventListener('message', (event) => {
console.log('Received message:', event);
console.log(`From: ${event.publisher}`);
console.log(`Channel: ${event.channelName}`);
console.log(`Message: ${event.message}`);
});
// 监听 Presence 事件(用户加入/离开)
this.rtmClient.addEventListener('presence', (event) => {
console.log('Presence event:', event);
console.log(`Event type: ${event.eventType}`);
console.log(`User: ${event.publisher}`);
});
```
### 5. 登录服务 [#5-登录服务]
你需要执行登录操作才能建立与 RTM 服务器的连接,然后才能调用 SDK 的其他 API。在 `login` 方法中添加以下代码:
```typescript showLineNumbers
// 在 login 方法中添加以下代码
async login(): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.login(TOKEN);
console.log('Login successful:', response);
} catch (error) {
console.error('Login failed:', error);
if (error instanceof RtmError) {
throw new Error(`登录失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Login failed');
}
}
}
```
:::info[信息]
你需要在登录时传入 Token。在测试阶段,为快速验证功能,我们建议你在创建声网项目时将鉴权模式设置为调试模式,然后在登录时传入空字符串即可。
:::
### 6. 收发消息 [#6-收发消息]
调用 `publish` 方法向 Message Channel 发送消息后,RTM 会把该消息分发给该频道的所有订阅者。以下代码演示如何发送字符串类型的消息:
:::info[信息]
你需要先对消息负载进行字符串序列化,才能调用 `publish` 方法发送消息。
:::
```typescript showLineNumbers
// 在 publish 方法中添加以下代码
async publish(channelName: string, message: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const options: PublishOptions = {
channelType: RtmChannelType.MESSAGE,
customType: ''
};
const response = await this.rtmClient.publish(channelName, message, options);
console.log('Message published successfully:', response);
} catch (error) {
console.error('Failed to publish message:', error);
if (error instanceof RtmError) {
throw new Error(`发送消息失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Publish failed');
}
}
}
```
调用 `subscribe` 方法订阅此频道以接收此频道中的消息:
```typescript showLineNumbers
// 在 subscribe 方法中添加以下代码
async subscribe(channelName: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const options: SubscribeOptions = {
withMessage: true,
withMetadata: false,
withPresence: true,
withLock: false
};
const response = await this.rtmClient.subscribe(channelName, options);
console.log('Subscribed to channel successfully:', response);
} catch (error) {
console.error('Failed to subscribe to channel:', error);
if (error instanceof RtmError) {
throw new Error(`订阅失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Subscribe failed');
}
}
}
```
如果你不再需要在此频道收发消息,你可以调用 `unsubscribe` 方法取消订阅此频道:
```typescript showLineNumbers
// 在 unsubscribe 方法中添加以下代码
async unsubscribe(channelName: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.unsubscribe(channelName);
console.log('Unsubscribed from channel successfully:', response);
} catch (error) {
console.error('Failed to unsubscribe from channel:', error);
if (error instanceof RtmError) {
throw new Error(`取消订阅失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Unsubscribe failed');
}
}
}
```
如需了解更多收发消息的信息,查看[消息](/zh-CN/api-reference/rtm/harmonyos/message)。
### 7. 登出服务 [#7-登出服务]
当不再需要使用 RTM 服务时,你可以调用 `logout` 方法登出 RTM 系统:
```typescript showLineNumbers
// 在 logout 方法中添加以下代码
async logout(): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.logout();
console.log('Logout successful:', response);
} catch (error) {
console.error('Logout failed:', error);
if (error instanceof RtmError) {
throw new Error(`登出失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Logout failed');
}
}
}
```
:::info[信息]
本操作会影响你账单中的 PCU 计费项。
:::
### 8. 组合到一起 [#8-组合到一起]
经过上述步骤,你的完整代码应该如下所示:
```typescript
import { RtmClient, RtmConfig, RtmChannelType, SubscribeOptions, PublishOptions } from '@shengwang/rtm-full';
import type { LinkStateEvent, MessageEvent, PresenceEvent } from '@shengwang/rtm-full';
import { RtmError } from '@shengwang/rtm-full';
// 填入你的 App ID
const APP_ID = '';
// 填入你的 Token(测试阶段可以为空字符串)
const TOKEN = '';
export class RtmManager {
private rtmClient: RtmClient | null = null;
private userId: string = '';
/**
* 初始化 RTM 客户端
*/
async initialize(userId: string): Promise {
try {
this.userId = userId;
// 创建 RTM 配置
const config: RtmConfig = {
appId: APP_ID,
userId: userId
};
// 创建 RTM 客户端实例
this.rtmClient = new RtmClient(config);
// 监听连接状态变化
this.rtmClient.addEventListener('linkState', (event: object) => {
const linkEvent = event as LinkStateEvent;
console.log('Link state changed:', linkEvent);
console.log(`State: ${linkEvent.previousState} -> ${linkEvent.currentState}`);
console.log(`Reason: ${linkEvent.reason}`);
});
// 监听接收到的消息
this.rtmClient.addEventListener('message', (event: object) => {
const msgEvent = event as MessageEvent;
console.log('Received message:', msgEvent);
console.log(`From: ${msgEvent.publisher}`);
console.log(`Channel: ${msgEvent.channelName}`);
console.log(`Message: ${msgEvent.message}`);
});
// 监听 Presence 事件(用户加入/离开)
this.rtmClient.addEventListener('presence', (event: object) => {
const presenceEvent = event as PresenceEvent;
console.log('Presence event:', presenceEvent);
console.log(`Event type: ${presenceEvent.eventType}`);
console.log(`User: ${presenceEvent.publisher}`);
});
console.log('RTM client initialized successfully');
} catch (error) {
console.error('Failed to initialize RTM client:', error);
if (error instanceof RtmError) {
throw new Error(`初始化失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('RTM client initialization failed');
}
}
}
/**
* 登录 RTM 服务
*/
async login(): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.login(TOKEN);
console.log('Login successful:', response);
} catch (error) {
console.error('Login failed:', error);
if (error instanceof RtmError) {
throw new Error(`登录失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Login failed');
}
}
}
/**
* 订阅频道
*/
async subscribe(channelName: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const options: SubscribeOptions = {
withMessage: true,
withMetadata: false,
withPresence: true,
withLock: false
};
const response = await this.rtmClient.subscribe(channelName, options);
console.log('Subscribed to channel successfully:', response);
} catch (error) {
console.error('Failed to subscribe to channel:', error);
if (error instanceof RtmError) {
throw new Error(`订阅失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Subscribe failed');
}
}
}
/**
* 取消订阅频道
*/
async unsubscribe(channelName: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.unsubscribe(channelName);
console.log('Unsubscribed from channel successfully:', response);
} catch (error) {
console.error('Failed to unsubscribe from channel:', error);
if (error instanceof RtmError) {
throw new Error(`取消订阅失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Unsubscribe failed');
}
}
}
/**
* 发送消息
*/
async publish(channelName: string, message: string): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const options: PublishOptions = {
channelType: RtmChannelType.MESSAGE,
customType: ''
};
const response = await this.rtmClient.publish(channelName, message, options);
console.log('Message published successfully:', response);
} catch (error) {
console.error('Failed to publish message:', error);
if (error instanceof RtmError) {
throw new Error(`发送消息失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Publish failed');
}
}
}
/**
* 登出 RTM 服务
*/
async logout(): Promise {
if (!this.rtmClient) {
throw new Error('RTM client not initialized');
}
try {
const response = await this.rtmClient.logout();
console.log('Logout successful:', response);
} catch (error) {
console.error('Logout failed:', error);
if (error instanceof RtmError) {
throw new Error(`登出失败: ${error.reason} (code: ${error.errorCode})`);
} else {
throw new Error('Logout failed');
}
}
}
/**
* 释放资源
*/
release(): void {
if (this.rtmClient) {
this.rtmClient.release();
this.rtmClient = null;
}
}
}
```
现在,你可以在你的 HarmonyOS 应用中使用这个 `RtmManager` 类。以下是一个简单的页面示例,展示如何在 Index 页面中使用 RTM 功能:
```typescript
// Index.ets
import { RtmManager } from './RtmManager';
import { RtmChannelType } from '@shengwang/rtm-full';
@Entry
@Component
struct Index {
@State userId: string = '';
@State channelName: string = '';
@State message: string = '';
@State messageHistory: string = '';
@State isLoggedIn: boolean = false;
private rtmManager: RtmManager = new RtmManager();
build() {
Column() {
// 标题
Text('RTM 快速开始')
.fontSize(24)
.fontWeight(FontWeight.Bold)
.margin({ top: 20, bottom: 20 })
// 用户 ID 输入
Row() {
Text('用户 ID:')
.width(80)
TextInput({ placeholder: '请输入用户 ID' })
.layoutWeight(1)
.onChange((value: string) => {
this.userId = value;
})
}
.width('90%')
.margin({ bottom: 10 })
// 登录/登出按钮
Row() {
Button(this.isLoggedIn ? '登出' : '登录')
.width('45%')
.onClick(() => {
if (this.isLoggedIn) {
this.handleLogout();
} else {
this.handleLogin();
}
})
}
.width('90%')
.margin({ bottom: 20 })
Divider()
.margin({ bottom: 20 })
// 频道名输入
Row() {
Text('频道名:')
.width(80)
TextInput({ placeholder: '请输入频道名' })
.layoutWeight(1)
.onChange((value: string) => {
this.channelName = value;
})
}
.width('90%')
.margin({ bottom: 10 })
// 订阅/取消订阅按钮
Row() {
Button('订阅')
.width('45%')
.onClick(() => {
this.handleSubscribe();
})
.enabled(this.isLoggedIn)
Button('取消订阅')
.width('45%')
.onClick(() => {
this.handleUnsubscribe();
})
.enabled(this.isLoggedIn)
}
.width('90%')
.justifyContent(FlexAlign.SpaceBetween)
.margin({ bottom: 20 })
// 消息输入
Row() {
Text('消息:')
.width(80)
TextInput({ placeholder: '请输入消息内容' })
.layoutWeight(1)
.onChange((value: string) => {
this.message = value;
})
}
.width('90%')
.margin({ bottom: 10 })
// 发送消息按钮
Button('发送消息')
.width('90%')
.onClick(() => {
this.handlePublish();
})
.enabled(this.isLoggedIn)
.margin({ bottom: 20 })
Divider()
.margin({ bottom: 10 })
// 消息历史
Text('消息历史:')
.fontSize(16)
.fontWeight(FontWeight.Bold)
.alignSelf(ItemAlign.Start)
.margin({ left: '5%', bottom: 10 })
Scroll() {
Text(this.messageHistory)
.width('100%')
.padding(10)
}
.width('90%')
.height(200)
.backgroundColor('#F0F0F0')
.borderRadius(8)
}
.width('100%')
.height('100%')
.padding({ top: 20 })
}
// 登录处理
async handleLogin() {
if (!this.userId) {
this.addMessage('请输入用户 ID');
return;
}
try {
await this.rtmManager.initialize(this.userId);
await this.rtmManager.login();
this.isLoggedIn = true;
this.addMessage(`用户 ${this.userId} 登录成功`);
} catch (error) {
this.addMessage(`登录失败: ${error}`);
}
}
// 登出处理
async handleLogout() {
try {
await this.rtmManager.logout();
this.rtmManager.release();
this.isLoggedIn = false;
this.addMessage('登出成功');
} catch (error) {
this.addMessage(`登出失败: ${error}`);
}
}
// 订阅频道
async handleSubscribe() {
if (!this.channelName) {
this.addMessage('请输入频道名');
return;
}
try {
await this.rtmManager.subscribe(this.channelName);
this.addMessage(`订阅频道 ${this.channelName} 成功`);
} catch (error) {
this.addMessage(`订阅失败: ${error}`);
}
}
// 取消订阅频道
async handleUnsubscribe() {
if (!this.channelName) {
this.addMessage('请输入频道名');
return;
}
try {
await this.rtmManager.unsubscribe(this.channelName);
this.addMessage(`取消订阅频道 ${this.channelName} 成功`);
} catch (error) {
this.addMessage(`取消订阅失败: ${error}`);
}
}
// 发送消息
async handlePublish() {
if (!this.channelName) {
this.addMessage('请输入频道名');
return;
}
if (!this.message) {
this.addMessage('请输入消息内容');
return;
}
try {
await this.rtmManager.publish(this.channelName, this.message);
this.addMessage(`发送消息到 ${this.channelName}: ${this.message}`);
} catch (error) {
this.addMessage(`发送消息失败: ${error}`);
}
}
// 添加消息到历史记录
addMessage(msg: string) {
const timestamp = new Date().toLocaleTimeString();
this.messageHistory += `[${timestamp}] ${msg}\n`;
}
}
```
这个示例展示了如何:
1. **创建 RTM 管理器实例**:在组件中创建 `RtmManager` 实例
2. **用户登录**:输入用户 ID,点击登录按钮初始化并登录 RTM
3. **订阅频道**:输入频道名,点击订阅按钮订阅消息频道
4. **发送消息**:输入消息内容,点击发送按钮向频道发送消息
5. **取消订阅**:点击取消订阅按钮退出频道
6. **用户登出**:点击登出按钮断开 RTM 连接
你也可以使用更简单的方式来测试 RTM 功能:
```typescript
// 在你的页面或组件中使用
import { RtmManager } from './RtmManager';
// 创建 RTM 管理器实例
const rtmManager = new RtmManager();
// 初始化并登录
await rtmManager.initialize('user123');
await rtmManager.login();
// 订阅频道
await rtmManager.subscribe('test-channel');
// 发送消息
await rtmManager.publish('test-channel', 'Hello, RTM!');
// 取消订阅
await rtmManager.unsubscribe('test-channel');
// 登出
await rtmManager.logout();
// 释放资源
rtmManager.release();
```
至此,你已经成功集成并正确使用了 RTM 服务。
## 贯穿始终 [#贯穿始终-3]
相比于介绍如何写出代码,声网更愿意帮助你掌握上述程序编写的过程和逻辑。上述程序依次完成了以下操作,让你可以正确地收发消息:
1. 创建并初始化 RTM 对象。
2. 添加 `linkState`、`message` 和 `presence` 事件监听函数。
3. 调用 `login` 登录了 RTM 服务。
4. 调用 `subscribe` 订阅了一个 Message Channel。
5. 调用 `publish` 发送消息。
6. 调用 `unsubscribe` 取消订阅一个 Message Channel。
7. 调用 `logout` 登出 RTM 系统。
## 下一步 [#下一步-3]
现在,你已经学会了如何使用 RTM HarmonyOS SDK 来实现 Message Channel 的收发消息功能。下一步,你可以通过 SDK 的 [API 参考](/zh-CN/api-reference/rtm/harmonyos/configuration)了解更多功能的使用方法。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unity" />
本文将指导你如何利用 RTM SDK 构建简单的应用程序,内容涵盖了集成和开发的基础知识:开通声网账号、获取 SDK、发送消息、接收消息等。
## 准备工作 [#准备工作-4]
开始构建项目前,你需要完成[开通 RTM 服务](/zh-CN/realtime-media/rtm/build/rtm-initialization/enable-service),并检查你的开发环境和运行环境是否满足如下要求:
- [Unity Hub](https://unity.com/download) 任意版本
- Unity 2018.4.0 或以上版本
- 操作系统与编译器要求:
| 开发平台 | 操作系统版本 | 编译器版本 |
| ------ | ---------------- | ----- |
| Android | Android 4.1 或以上 | Android Studio 3.0 或以上 |
| iOS | iOS 11.0 或以上 | Xcode 9.0 或以上 |
| macOS | macOS 10.10 或以上 | Xcode 9.0 或以上 |
| Windows | Windows 7 或以上 | Microsoft Visual Studio 2017 或以上 |
## 获取 SDK [#获取-sdk-1]
[点击此处](https://download.agora.io/sdk/release/Agora_Unity_RTM_SDK_v2.1.9.zip)下载最新版本的 Unity SDK,并在你的项目中导入它。
## 导入 SDK [#导入-sdk]
1. 打开 Unity Hub,点击 **New Project** 新建一个 Unity 3D 项目。
2. 点击顶部菜单栏的 **Assets** 菜单,依次选择 **Import Package**、**Custom Package** 向项目中导入你刚刚获取的 RTM Unity Package。
## 初始化 RTM [#初始化-rtm]
调用 RTM SDK 的任何 API 之前,需要先初始化一个 `IRtmClient` 对象实例。参考如下步骤创建用户界面、初始化一个 `IRtmClient` 对象实例并添加项目脚本:
:::tip[初始化配置]
初始化 RTM 的时候可以通过配置某些参数改变 `IRtmClient` 其后续行为,例如配置事件监听函数、端侧消息加密等。详见[初始配置](/zh-CN/api-reference/rtm/unity/configuration)。
:::
1. 我们为你提供了一个简单的示例项目,其中进行了简易的 UI 界面设计以便于验证功能特性。UI 界面及组件架构如下图所示:

```json showLineNumbers
SampleScene
- Main Camera
- Canvas
- Image // 窗口背景
- Txt1 // 文本标签,文本内容为 Send string message to message channel
- InputField1 // 消息输入框
- Btn1 // 发送消息按钮
- Txt2 // 文本标签,文本内容为 Send binary message to stream channel
- Btn2 // 创建 Stream Channel 按钮
- Btn3 // 加入 Stream Channel 按钮
- Btn4 // 加入 Topic 按钮
- Btn5 // 订阅 Topic 中的消息发布者按钮
- InputField2 // 消息输入框
- Btn6 // 发送消息按钮
- Btn7 // 释放 Stream Channel 按钮
- Btn8 // 离开 Stream Channel 按钮
- Btn9 // 离开 Topic 按钮
- Btn10 // 取消订阅 Topic 中的消息发布者按钮
- Pannel // 信息输出面板
- Txt3 // 信息输出文字
- EventSystem
```
2. 在 Unity 编辑器中,选择顶部菜单栏的 **Assets** 菜单,依次点击 **Create**、**C# Script** 为项目新建脚本,名为 **HelloWorld.cs**。
3. 在 **HelloWorld.cs** 脚本中添加以下代码作为程序模版。你会发现此程序并不完整,不用紧张,我们在后续步骤中将一步步指导你补充完善代码。
```csharp showLineNumbers title="Assets/Hello_world.cs"
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;
using Agora.Rtm;
public class HelloWorld : MonoBehaviour
{
[SerializeField]
private string appId = "your_appId";
// Get an App ID from console portal
private string userId = "your_userId";
// Change the user ID by yourself
private string msChannelName = "SeeYou";
private string stChannelName = "Greeting";
private string topicName = "Hello_world";
private IRtmClient rtmClient;
private IStreamChannel streamChannel;
public void Awake()
{
Initialize();
}
// Initialize the RTM
public async void Initialize()
{
// Initialize the RTM Client
// Add listener
if (rtmClient != null)
{
// Add message event listener
rtmClient.OnMessageEvent += OnMessageEvent;
// Add the presence event listener
rtmClient.OnPresenceEvent += OnPresenceEvent;
// Add the connection state change listener
rtmClient.OnConnectionStateChanged += OnConnectionStateChanged;
// Log in to the RTM server
// Subscribe to a Message Channel
}
}
private void ChangeComponentView(string[] componentsList, string viewType)
{
for (int i = 0; i < componentsList.Length; i++)
{
if (viewType == "ACTIVATE")
GameObject.Find(componentsList[i]).GetComponent