You use Signaling SDK to add low-latency, high-concurrency signaling and synchronization capabilities for real-time systems into your app. You can also use Signaling to enhance the user experience for Video Calling, Voice Calling, Interactive Live Streaming, and Broadcast Streaming.
This page shows you how to easily integrate pub-sub messaging into your app using Signaling SDK. For information about stream channels where users communicate using topics in a channel, see Stream channel quickstart.
Pub-sub is the simplest form of messaging. Signaling creates a channel when a user subscribes to it. Your app listens for events which contain messages users publish to a channel.
You use an authentication token to authenticate a user with Signaling and join a channel. Each token is bound to a single user UID. This means that only one concurrent user may login from an instance of your app.
To create a pub-sub session for Signaling , implement the following steps in your app:
In this guide you retrieve a temporary token from a Token Generator. To understand how to create an authentication server for development purposes, see Implement the authentication workflow. To develop your own token generator and integrate it into your production IAM system, read Token generators.
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.
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.
- 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.
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:
Clone the Signaling SDK reference app to
<samples-root>on your development environment:
Navigate to your
<samples-root>folder and run the following command:
Open the reference app in Android Studio:
From the File menu select Open... then navigate to
<samples-root>/video-sdk-samples-android/android-reference-appand click OK. Android Studio loads the project and Gradle sync downloads the dependencies.
Best practice is to separate the Signaling workflows from your UI implementation. The Signaling SDK sample project implements the Signaling business logic in the
SignalingManager class. This class encapsulates the Signaling engine instance and core functionality such as logging in to Signaling, sending a message, listening for messages from other users and logging out.
The following code examples show how to implement these steps in your app:
You use these objects to communicate with Signaling.
Best practice is to keep these variables separate from your code. For example, in the Signaling reference app, we use the following
JSON configuration file.
Your code reads the parameters from the configuration file, initializes the SignalingEngine instance and adds the event listeners.
In Signaling, each token is specific to a user ID. If
token do not match, your user cannot initiate Signaling Engine.
To start receiving messages and event notifications from a channel, you call
Messages are published directly to a channel.
You setup the event handlers for messages received from other users during Signaling Engine initiation.
When you no longer need to receive channel notifications, call
Had enough of the conversation? Just logout.
You have just implemented the Signaling workflow. Yes, it's as easy as that.
This section explains how to run the reference app and see the corresponding features in an app.
In Signaling, each authentication token you create is specific for a user ID. You create a token for each user in the channel. Each user must log in from a different instance of your app.
To test Signaling, you run 2 or more instances of your app. When you call
login using Signaling SDK, ensure that the UID is the same as you used to create the token.
For each user in your tests:
Configure the project
Open the file
- Replace the value for
appIdwith the value from Agora Console.
- Generate an RTM token using your
- Replace the value for
tokenwith the Signaling token.
- Replace the value for
uidwith the the value you used to generate the token.
- Ensure that the
channelNameis filled in. The channel name can be any string.
Run the reference app
- In Android Studio, connect a physical Android device to your development machine.
- Click Run to start the app.
- A moment later you see the project installed on your device.
Test the basic functionality:
- Open a new instance of the reference app.
- Choose the SDK quickstart example.
- Log in to Signaling.
- Subscribe to a channel, then send and receive messages.
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.
After a token expires, you call the logout method to log out of Signaling, then use the new Token to create an
RTM instance, and then call the login method to log in to Signaling again.
For more information, see: