需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

Topic

  • Swift

更新时间不可用

Topic 是 Stream Channel 中的数据流管理机制。用户可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等。

信息

Topic 只存在于 Stream Channel。所以用户在使用相关特性之前，需要先创建一个 AgoraRtmStreamChannel 对象实例。

想要了解 Topic 的更多特性，可以查看：

joinTopic

接口描述

加入 Topic 的目的在于注册成为该 Topic 的消息发布者之一，从而让用户具备发送消息的能力。是否执行该操作都不影响该用户是否成为该 Topic 的订阅者。

信息

  • 当前 RTM 支持单客户端在同一个 Stream Channel 中同时加入 8 个 Topic。
  • 在执行此操作之前，用户需要首先创建 AgoraRtmStreamChannel 对象实例，并调用 join 方法加入频道，详见频道。

成功加入 Topic 后，订阅该 Topic 并添加事件监听的用户会收到 remoteJoinTopic 类型的 didReceiveTopicEvent 事件通知。详见事件监听。

接口方法

你可以通过以下方式调用 joinTopic 方法：

Swift
joinTopic(
    _ topic: String,
    option: AgoraRtmJoinTopicOption?
)   async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
Swift
joinTopic(
    _ topic: String,
    option: AgoraRtmJoinTopicOption?,
    completion completionBlock: AgoraRtmOperationBlock? = nil
)
参数类型必填默认值描述
topicString必填-Topic 名称。
optionAgoraRtmJoinTopicOption选填-加入 Topic 选项。
completionAgoraRtmOperationBlock选填-

调用结果回调：

  • 调用成功：在 response 参数中返回 AgoraRtmCommonResponse 数据，在 errorInfo 参数中返回 nil。
  • 调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

AgoraRtmJoinTopicOption 数据类型包含以下属性：

属性类型必填默认值描述
qosAgoraRtmMessageQos选填.ordered定义此 Topic 中传输数据是否保序。详见 AgoraRtmMessageQos。
priorityAgoraRtmMessagePriority选填.normal定义此 Topic 中传输数据的优先级（相比于同频道中的其他 Topic）。详见 AgoraRtmMessagePriority。
metaString选填-加入 Topic 时携带的其他辅助信息。
syncWithMediaBool选填false此 Topic 中发送的数据是否与共频道的 RTC 音视频数据流实现数据同步（时间戳对齐）。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

Swift
// async-await
let topic = "exampleTopic"
let joinOption = AgoraRtmJoinTopicOption()
joinOption.priority = .high
joinOption.syncWithMedia = false

let (response, error) = await stChannel.joinTopic(topic, option: joinOption)
if let errorInfo = error {
    // Handle error
    print("Failed to join topic with error: \(errorInfo.reason)")
} else if let joinTopicResponse = response {
    // Handle success
    print("Successfully joined topic.")
} else {
    // Handle unknown error
    print("Unknown error occurred while joining the topic.")
}

publishTopicMessage

接口描述

publishTopicMessage 方法用于向 Topic 发送消息，频道中订阅此 Topic 及此消息发布者的用户会在 100 毫秒内收到此消息。调用 publishTopicMessage 方法需要用户首先加入 Stream Channel 并且通过调用 joinTopic 方法注册成为该 Topic 的消息发布者。

用户发送的消息在传输的过程中会被 TLS 加密，数据链路加密默认开启且无法关闭。用户也可以在出初始化的时候开启端侧加密，以获得更高的数据安全等级，详见初始配置。

接口方法

你可以通过以下方式调用 publishTopicMessage[1/2] 和 publishTopicMessage[2/2] 方法：

  • 发送字符串消息：

    Swift
    publishTopicMessage(
    topic: String,
    message: String,
    option options: AgoraRtmTopicMessageOptions?
)   async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
    Swift
    publishTopicMessage(
    topic: String,
    message: String,
    option options: AgoraRtmTopicMessageOptions?,
    completion completionBlock: AgoraRtmOperationBlock? = nil
)

  • 发送二进制消息：

    Swift
    publishTopicMessage(
    topic: String,
    ata: Data,
    option options: AgoraRtmTopicMessageOptions?
)   async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
    Swift
    publishTopicMessage(
    topic: String,
    data: Data,
    option options: AgoraRtmTopicMessageOptions?,
    completion completionBlock: AgoraRtmOperationBlock? = nil
)
参数类型必填默认值描述
topicString必填-Topic 名称。
messageString必填-在 publishTopicMessage[1/2] 方法中发布 String 型消息负载。
dataData必填-在 publishTopicMessage[2/2] 方法中发布 Byte 型消息负载。
optionsAgoraRtmTopicMessageOptions选填-消息选项。
completionAgoraRtmOperationBlock选填-

调用结果回调：

  • 调用成功：在 response 参数中返回 AgoraRtmCommonResponse 数据，在 errorInfo 参数中返回 nil。
  • 调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

AgoraRtmTopicMessageOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
sendTsUInt64选填0消息发送时间戳。只有在 joinTopic 中设置 syncWithMedia = true 时，该参数才有效，SDK 会根据此时间戳与 RTC 音视频数据流进行数据同步。
customTypeString必填-用户自定义字段。仅支持 NSString 型。
表格内容超出当前宽度，可横向滚动查看更多列。

接口方法

示例 1：向指定频道发送 String 消息

Swift
// async-await
let topic = "exampleTopic"
let message = "Hello, Agora!"
let messageOptions = AgoraRtmTopicMessageOptions()
messageOption.customType = "PlainText"

let (response, error) = await stChannel.publishTopicMessage(
    topic: topic,
    message: message,
    option: messageOptions
)
if let errorInfo = error {
    // Handle error
    print("Failed to publish message with error: \(errorInfo.reason)")
} else if let publishResponse = response {
    // Handle success
    print("Message published successfully.")
} else {
    // Handle unknown error
    print("Unknown error occurred while publishing the message.")
}

示例 2：向指定频道发送 Byte 消息

Swift
// async-await
let topic = "exampleTopic"
let messageOptions = AgoraRtmTopicMessageOptions()
messageOption.customType = "BinaryData"
let byteArray: [UInt8] = [0x00, 0x01, 0x02, 0x03]
let binaryData = Data(byteArray)

let (response, error) = await stChannel.publishTopicMessage(
    topic: topic,
    ata: binaryData,
    option: messageOptions
)
if let errorInfo = error {
    // Handle error
    print("Failed to publish binary data with error: \(errorInfo.reason)")
} else if let publishResponse = response {
    // Handle success
    print("Binary data published successfully.")
} else {
    // Handle unknown error
    print("Unknown error occurred while publishing the binary data.")
}

leaveTopic

接口描述

当你不再需要向某个 Topic 发布消息，你可以调用 leaveTopic 方法取消注册为该 Topic 的消息发布者，从而释放资源。该方法不影响你是否订阅该 Topic，也不影响其他用户对该 Topic 的任何操作。

成功调用该方法后，订阅该频道并开启事件监听的用户会收到 remoteLeaveTopic 类型的 didReceiveTopicEvent 事件通知，详见事件监听。

接口方法

你可以通过以下方式调用 leaveTopic 方法：

Swift
leaveTopic(
    _ topic: String
)   async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
Swift
leaveTopic(
    _ topic: String,
    completion completionBlock: AgoraRtmOperationBlock? = nil
)
参数类型必填默认值描述
topicString必填-Topic 名称。
completionAgoraRtmOperationBlock选填-

调用结果回调：

  • 调用成功：在 response 参数中返回 AgoraRtmCommonResponse 数据，在 errorInfo 参数中返回 nil。
  • 调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

Swift
// async-await
let topic = "exampleTopic"

let (response, error) = await stChannel.leaveTopic(topic)
if let errorInfo = error {
    // Handle error
    print("Failed to leave topic with error: \(errorInfo.reason)")
} else if let leaveTopicResponse = response {
    // Handle success
    print("Successfully left topic.")
} else {
    // Handle unknown error
    print("Unknown error occurred while leaving the topic.")
}

subscribeTopic

接口描述

加入频道后，你可以调用 subscribeTopic 方法订阅该频道中 Topic 的消息发布者。

subscribeTopic 为增量方法。例如，第一次调用该方法时，订阅消息发布者列表为 [UserA, UserB]，第二次调用该方法时，订阅消息发布者列表为 [UserB, UserC]，则最后成功订阅的结果是 [UserA, UserB, UserC]。

同一个用户在同一个频道中最多只能同时订阅 50 个 Topic，且每个 Topic 中最多只能订阅 64 个消息发布者。详见 API 调用限制。

接口方法

你可以通过以下方式调用 subscribeTopic 方法：

Swift
subscribeTopic(
    _ topic: String,
    option: AgoraRtmTopicOption?
)   async -> (AgoraRtmTopicSubscriptionResponse?, AgoraRtmErrorInfo?)
Swift
subscribeTopic(
    _ topic: String,
    option: AgoraRtmTopicOption?,
    completion completionBlock: AgoraRtmTopicSubscriptionBlock? = nil
)
参数类型必填默认值描述
topicString必填-Topic 名称。
optionAgoraRtmTopicOption选填-订阅 Topic 选项。
completionAgoraRtmTopicSubscriptionBlock选填-

调用结果回调：

  • 调用成功：在 response 参数中返回 AgoraRtmTopicSubscriptionResponse 数据，在 errorInfo 参数中返回 nil。
  • 调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

AgoraRtmTopicOption 数据类型包含以下属性：

属性类型必填默认值描述
users[String]选填-需要订阅的消息发布者（Publisher）的 UserId 列表，如果不设置，则默认随机订阅不超过 64 个用户。
表格内容超出当前宽度，可横向滚动查看更多列。

AgoraRtmTopicSubscriptionResponse 数据类型包含如下属性：

属性类型描述
succeedUsers[String]订阅成功的用户列表。
failedUsers[String]订阅失败的用户列表。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

示例 1：订阅 Topic 中指定的消息发布者

Swift
// async-await
let topic = "exampleTopic"
let topicOption = AgoraRtmTopicOption()                 // Optional, configure if needed
topicOption.users = ["user1", "user2"]                  // Specify users to subscribe to

let (response, error) = await stChannel.subscribeTopic(topic, option: topicOption)
if let errorInfo = error {
    // Handle error
    print("Failed to subscribe to topic with error: \(errorInfo.reason)")
} else if let subscriptionResponse = response {
    // Handle success
    print("Successfully subscribed to topic.")
} else {
    // Handle unknown error
    print("Unknown error occurred while subscribing to the topic.")
}

示例 2：随机订阅 Topic 中的 64 个消息发布者

Swift
// async-await
let topic = "exampleTopic"

let (response, error) = await stChannel.subscribeTopic(topic, option: nil)
if let errorInfo = error {
    // Handle error
    print("Failed to subscribe to topic with error: \(errorInfo.reason)")
} else if let subscriptionResponse = response {
    // Handle success
    print("Successfully subscribed to topic.")
} else {
    // Handle unknown error
    print("Unknown error occurred while subscribing to the topic.")
}

unsubscribeTopic

接口描述

如果你对某个 Topic 不再感兴趣，或者不再需要订阅 Topic 中的一个或多个消息发布者，你可以调用 unsubscribeTopic 方法取消订阅该 Topic 或取消订阅该 Topic 中指定的消息发布者。

接口方法

你可以通过以下方式调用 unsubscribeTopic 方法：

Swift
unsubscribeTopic(
    _ topic: String,
    option: AgoraRtmTopicOption?
)   async -> (AgoraRtmCommonResponse?, AgoraRtmErrorInfo?)
Swift
unsubscribeTopic(
    _ topic: String,
    option: AgoraRtmTopicOption?,
    completion completionBlock: AgoraRtmOperationBlock? = nil
)
参数类型必填默认值描述
topicString必填-Topic 名称。
optionsAgoraRtmTopicOption选填-取消订阅 Topic 选项。
completionAgoraRtmOperationBlock选填-

调用结果回调：

  • 调用成功：在 response 参数中返回 AgoraRtmCommonResponse 数据，在 errorInfo 参数中返回 nil。
  • 调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。
表格内容超出当前宽度，可横向滚动查看更多列。

AgoraRtmTopicOption 数据类型包含以下属性：

属性类型必填默认值描述
users[String]选填-需要取消订阅的消息发布者（Publisher）的 UserId 列表，如果不设置，则默认随机取消订阅不超过 64 个用户。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

示例 1：取消订阅 Topic 中指定的消息发布者

Swift
// async-await
let topic = "exampleTopic"
let topicOption = AgoraRtmTopicOption()
// Set specific users to unsubscribe from if needed
topicOption.users = ["user1", "user2"]
let (response, error) = await stChannel.unsubscribeTopic(topic, option: topicOption)
if let errorInfo = error {
    // Handle error
    print("Failed to unsubscribe from topic with error: \(errorInfo.reason)")
} else if let unsubscribeResponse = response {
    // Handle success
    print("Successfully unsubscribed from topic with specified options.")
} else {
    // Handle unknown error
    print("Unknown error occurred while unsubscribing from the topic.")
}

示例 2：随机取消订阅 Topic 中的 64 个消息发布者

Swift
// async-await
let topic = "exampleTopic"

// Unsubscribing without options
let (response, error) = await stChannel.unsubscribeTopic(topic, option: nil)
if let errorInfo = error {
    // Handle error
    print("Failed to unsubscribe from topic with error: \(errorInfo.reason)")
} else if let unsubscribeResponse = response {
    // Handle success
    print("Successfully unsubscribed from topic.")
} else {
    // Handle unknown error
    print("Unknown error occurred while unsubscribing from the topic.")
}

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利