Skip to main content

You are viewing Agora Docs forBeta products and features. Switch to Docs

Stream channel quickstart

Stream Channels are based on the room model. In a stream channel, users join a topic in order to send message to all users subscribed to that topic. Signaling enables each user to join up to one hundred channels at the same time. Each channel can have unlimited topics and up to 128 simultaneous users. Topics have a higher message transmission rate, greater message concurrency capability, and enable synchronous transmission of audio and video data. You use topics for Metaverse, AR/VR, interactive games, real-time collaboration, and parallel manipulation app.

For information about message channels where users communicate using a pub-sub model, see the Message channel quickstart.

Understand the tech

The following figure shows the stream channel workflow:

Stream channel

Prerequisites

In order to follow this procedure you must:

  • Android Studio 4.1 or higher.
  • Android SDK API Level 24 or higher.
  • A mobile device that runs Android 4.1 or higher.
  • An Agora account and project.

  • A computer with Internet access.

    Ensure that no firewall is blocking your network communication.

  • Raise a support ticket to activate Signaling. In your ticket, please provide the following details:
    • Your Agora Customer Id
    • The project VID for which you want Signaling enabled
    • The App Id for the project in which you want to integrate Signaling
    • Do you require Stream Channel activation: Yes or No
    • Do you need data storage (Storing user and channel attributes as metadata): Yes or No
    • Your geographical region for product activation: US, EU, APAC (excluding China), or China
      The Agora support team confirms activation through a ticket update.
Note
  • Signaling 2.x is an enhanced version compared to 1.x with a wide range of new features. It follows a new pricing structure. Please visit the Pricing page for details.
  • The beta version of Signaling 2.x is offered free of charge for testing its features and performance for the duration of its public beta.

Project setup

Agora supplies a single GitHub reference repository. This runnable and testable repo contains all the code used in this Signaling SDK documentation. To create a Signaling SDK development environment:

  1. Clone the Signaling SDK reference app to <samples-root> on your development environment:

    Navigate to your <samples-root> folder and run the following command:


    _1
    git clone https://github.com/AgoraIO/video-sdk-samples-android.git

  2. Open the reference app in Android Studio:

    From the File menu select Open... then navigate to <samples-root>/video-sdk-samples-android/android-reference-app and click OK. Android Studio loads the project and Gradle sync downloads the dependencies.

Implement communication in a stream channel

This section shows how to use the Signaling SDK to implement stream channels and presence in your app.

Setup an event listener

Keep track of the users who join and leave topics, and events in the topic. In this implementation, we use the event listener we implemented in the SDK quickstart.

Join and leave a stream channel

To create a new stream channel, call createStreamChannel. When you join the channel, you configure the features you will use.


_47
fun joinStreamChannel(channelName: String): Int {
_47
fetchRTCToken(channelName,1, object : TokenCallback {
_47
override fun onTokenReceived(token: String?) {
_47
// Use the received token to log in
_47
if (token != null) {
_47
streamChannel = signalingEngine!!.createStreamChannel(channelName)
_47
streamChannel.join(
_47
JoinChannelOptions(token, true, true, true),
_47
object : ResultCallback<Void?> {
_47
override fun onFailure(errorInfo: ErrorInfo?) {
_47
notify("Join stream channel failed:\n" + errorInfo.toString())
_47
isStreamChannelJoined = false
_47
}
_47
_47
override fun onSuccess(responseInfo: Void?) {
_47
isStreamChannelJoined = true
_47
mListener?.onSubscribeUnsubscribe(true)
_47
notify("Joined stream channel: $channelName")
_47
}
_47
})
_47
}
_47
}
_47
_47
override fun onError(errorMessage: String) {
_47
// Handle the error
_47
notify("Error fetching token: $errorMessage")
_47
}
_47
})
_47
return 0
_47
}
_47
_47
fun leaveStreamChannel(channelName: String): Int {
_47
streamChannel.leave(object : ResultCallback<Void?> {
_47
override fun onFailure(errorInfo: ErrorInfo?) {
_47
notify("Leave stream channel failed:\n" + errorInfo.toString())
_47
}
_47
_47
override fun onSuccess(responseInfo: Void?) {
_47
isStreamChannelJoined = false
_47
isTopicJoined =false
_47
joinedTopicName = ""
_47
mListener?.onSubscribeUnsubscribe(false)
_47
notify("Left stream channel: $channelName")
_47
}
_47
})
_47
return 0
_47
}

Join and leave a topic

A topic is a data stream management mechanism in stream channels. Users join, leave, subscribe, and unsubscribe to topics. You join a topic to publish and receive messages sent to all users in the topic. You subscribe to listen to messages sent by publishers only. When a user joins or leaves a topic, Signaling triggers an topic event notification. Users in the channel receive the notifications in real time. You use topic events to track changes in topic status. To join a topic:


_29
fun joinTopic (topicName: String) {
_29
streamChannel.joinTopic(topicName, JoinTopicOptions(), object : ResultCallback<Void?> {
_29
override fun onFailure(errorInfo: ErrorInfo?) {
_29
notify("Failed to join topic: $topicName")
_29
isTopicJoined = false
_29
}
_29
_29
override fun onSuccess(responseInfo: Void?) {
_29
notify("Successfully joined topic: $topicName")
_29
joinedTopicName = topicName
_29
isTopicJoined = true
_29
subscribeTopic(topicName)
_29
}
_29
})
_29
}
_29
_29
fun leaveTopic (topicName: String) {
_29
streamChannel.leaveTopic(topicName, object : ResultCallback<Void?> {
_29
override fun onFailure(errorInfo: ErrorInfo?) {
_29
notify("Failed to leave topic: $topicName")
_29
}
_29
_29
override fun onSuccess(responseInfo: Void?) {
_29
notify("Successfully left topic: $topicName")
_29
joinedTopicName = ""
_29
isTopicJoined = false
_29
}
_29
})
_29
}

There is no limit to the number of subscribers and publishers in each topic. However, there are limitations to the number of topics and messages a user can subscribe to.

Publish messages to a topic

Messages are transmitted through the topic. After your user has joined a topic in a channel, you publish messages to the topic. Publishers and subscribers receive the messages. To send a message:


_12
fun publishTopicMessage(topicName: String, message: String): Int {
_12
streamChannel.publishTopicMessage(topicName, message, PublishOptions(), object : ResultCallback<Void?> {
_12
override fun onFailure(errorInfo: ErrorInfo?) {
_12
notify("Message send failed")
_12
}
_12
_12
override fun onSuccess(responseInfo: Void?) {
_12
notify("Message sent to stream channel: $channelName, topic: $topicName")
_12
}
_12
})
_12
return 0
_12
}

Subscribe to a topic

To receive messages published to a topic, you subscribe to the topic. To subscribe:


_12
fun subscribeTopic(topicName: String) {
_12
_12
streamChannel.subscribeTopic(topicName, TopicOptions(), object : ResultCallback<SubscribeTopicResult?> {
_12
override fun onFailure(errorInfo: ErrorInfo?) {
_12
notify("Failed to subscribe to topic: $topicName")
_12
}
_12
_12
override fun onSuccess(responseInfo: SubscribeTopicResult?) {
_12
notify("Subscribed to topic: $topicName")
_12
}
_12
})
_12
}

Test stream channels

To test the stream channel functionality:

  1. Configure the project

    1. Open the file <samples-root>/signaling-manager/src/main/res/raw/config.json

    2. Set appId to the AppID of your project.

    3. Choose one of the following authentication methods:

      • Temporary token:
        1. Generate an RTM token using your uid and set token to this value in config.json.
        2. Generate an RTC token using your uid and channelName and set rtcToken to this value in config.json.
        3. Set channelName to the name of the channel you used to create the rtcToken.
      • Authentication server:
        1. Setup an Authentication server
        2. In config.json, set:
          • channelName to the name of a channel you want to join.
          • token and rtcToken to empty strings.
          • serverUrl to the base URL for your token server. For example: https://agora-token-service-production-yay.up.railway.app.
  2. Run the reference app

    1. In Android Studio, connect a physical Android device to your development machine.
    2. Click Run to start the app.
    3. A moment later you see the project installed on your device.
  3. Test stream channels:

    1. For each user, open a new instance of the reference app.
    2. Choose the Stream Channels example.
    3. Log in to Signaling, then send and receive messages using topics in channels.

Reference

This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product.

Signaling