Topic

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

信息

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

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

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
)

参数类型必填默认值描述

topic String 必填 - Topic 名称。

option AgoraRtmJoinTopicOption 选填 - 加入 Topic 选项。

completion

AgoraRtmOperationBlock

选填

调用结果回调：

调用成功：在 response 参数中返回 AgoraRtmCommonResponse 数据，在 errorInfo 参数中返回 nil。
调用失败：在 response 参数中返回 nil，在 errorInfo 参数中返回错误信息。

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

属性	类型	必填	默认值	描述
`qos`	`AgoraRtmMessageQos`	选填	`.ordered`	定义此 Topic 中传输数据是否保序。详见 `AgoraRtmMessageQos`。
`priority`	`AgoraRtmMessagePriority`	选填	`.normal`	定义此 Topic 中传输数据的优先级（相比于同频道中的其他 Topic）。详见 `AgoraRtmMessagePriority`。
`meta`	String	选填	-	加入 Topic 时携带的其他辅助信息。
`syncWithMedia`	Bool	选填	`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.")
}

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

stChannel.joinTopic(topic, option: joinOption) { (response, error) in
    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
)

参数	类型	必填	默认值	描述
`topic`	String	必填	-	Topic 名称。
`message`	String	必填	-	在 `publishTopicMessage`[1/2] 方法中发布 String 型消息负载。
`data`	Data	必填	-	在 `publishTopicMessage`[2/2] 方法中发布 Byte 型消息负载。
`options`	`AgoraRtmTopicMessageOptions`	选填	-	消息选项。
`completion`	`AgoraRtmOperationBlock`	选填	-	调用结果回调：调用成功：在 `response` 参数中返回 `AgoraRtmCommonResponse` 数据，在 `errorInfo` 参数中返回 `nil`。调用失败：在 `response` 参数中返回 `nil`，在 `errorInfo` 参数中返回错误信息。

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

属性	类型	是否必填	默认值	描述
`sendTs`	`UInt64`	选填	`0`	消息发送时间戳。只有在 `joinTopic` 中设置 `syncWithMedia = true` 时，该参数才有效，SDK 会根据此时间戳与 RTC 音视频数据流进行数据同步。
`customType`	String	必填	-	用户自定义字段。仅支持 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.")
}

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

stChannel.publishTopicMessage(
    topic: topic,
    message: message,
    option: messageOptions
) { (response, error) in
    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.")
}

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

stChannel.publishTopicMessage(
    topic: topic,
    ata: binaryData,
    option: messageOptions
) { (response, error) in
    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
)

参数类型必填默认值描述

topic String 必填 - Topic 名称。

completion

AgoraRtmOperationBlock

选填

调用结果回调：

调用成功：在 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.")
}

Swift
// callback
let topic = "exampleTopic"

stChannel.leaveTopic(topic) { (response, error) in
    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 方法订阅该频道中 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
)

参数类型必填默认值描述

topic String 必填 - Topic 名称。

option AgoraRtmTopicOption 选填 - 订阅 Topic 选项。

completion

AgoraRtmTopicSubscriptionBlock

选填

调用结果回调：

调用成功：在 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.")
}

Swift
// callback
let topic = "exampleTopic"
let topicOption = AgoraRtmTopicOption()               // Optional
topicOption.users = ["user1", "user2"]                // Specify users to subscribe to

stChannel.subscribeTopic(topic, option: topicOption) { (response, error) in
    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.")
}

Swift
// callback
let topic = "exampleTopic"

stChannel.subscribeTopic(topic, option: nil) { (response, error) in
    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
)

参数类型必填默认值描述

topic String 必填 - Topic 名称。

options AgoraRtmTopicOption 选填 - 取消订阅 Topic 选项。

completion

AgoraRtmOperationBlock

选填

调用结果回调：

调用成功：在 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.")
}

Swift
// callback
let topic = "exampleTopic"
let topicOption = AgoraRtmTopicOption()
// Set specific users to unsubscribe from if needed
topicOption.users = ["user1", "user2"]

stChannel.unsubscribeTopic(topic, option: topicOption) { (response, error) in
    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.")
}

Swift
// callback
let topic = "exampleTopic"

// Unsubscribing without options
stChannel.unsubscribeTopic(topic, option: nil) { (response, error) in
    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.")
    }
}

joinTopic​

接口描述​

接口方法​

基本用法​

publishTopicMessage​

接口描述​

接口方法​

接口方法​

leaveTopic​

接口描述​

接口方法​

基本用法​

subscribeTopic​

接口描述​

接口方法​

基本用法​

unsubscribeTopic​

接口描述​

接口方法​

基本用法​

joinTopic

接口描述

接口方法

基本用法

publishTopicMessage

接口描述

接口方法

接口方法

leaveTopic

接口描述

接口方法

基本用法

subscribeTopic

接口描述

接口方法

基本用法

unsubscribeTopic

接口描述

接口方法

基本用法