Message channel quickstart

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.

Understand the tech

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.

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:

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

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

_1git clone https://github.com/AgoraIO/video-sdk-samples-android.git
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 Signaling

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:

Declare the variable to hold a Signaling Engine instance

You use these objects to communicate with Signaling.

protected var signalingEngine: RtmClient? = null

Define configuration parameters

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.

{
    "uid": "1",
    "appId": "",
    "channelName": "",
    "token": "",
    "proxyUrl": "http://localhost:8080/",
    "serverUrl": "<URL to a token server>",
    "tokenExpiryTime": "600",
    "encryptionMode": 1,
    "salt": "",
    "cipherKey": "",
    "presenceTimeout": 300,
    "logUpload": false,
    "logLevel": "debug",
    "cloudProxy": true,
    "useStringUserId": false,
    "rtcToken": ""
}

Configure a Signaling Engine instance

Your code reads the parameters from the configuration file, initializes the SignalingEngine instance and adds the event listeners.

protected open fun setupSignalingEngine(uid: Int): Boolean {
    try {
        val rtmConfig = RtmConfig.Builder(appId, uid.toString())
            .presenceTimeout(config!!.optString("presenceTimeout").toInt())
            .useStringUserId(false)
            .eventListener(eventListener)
            .build()
        signalingEngine = RtmClient.create(rtmConfig)
        localUid = uid
    } catch (e: Exception) {
        notify(e.toString())
        return false
    }
    return true
}

Handle and respond to Signaling events

protected open val eventListener: RtmEventListener = object : RtmEventListener {
    override fun onMessageEvent(eventArgs: MessageEvent) {
        // Receives Message Events
        mListener?.onSignalingEvent("Message", eventArgs) // notify the UI
    }
    override fun onPresenceEvent(eventArgs: PresenceEvent) {
        // Receives Presence Events
        if (eventArgs.eventType == RtmConstants.RtmPresenceEventType.SNAPSHOT) {
            channelType = eventArgs.channelType
        }
        mListener?.onSignalingEvent("Presence", eventArgs) 
    }
    override fun onTopicEvent(eventArgs: TopicEvent) {
        // Receives Topic Events
        mListener?.onSignalingEvent("Topic", eventArgs) 
    }
    override fun onLockEvent(eventArgs: LockEvent) {
        // Receives Lock Events
        mListener?.onSignalingEvent("Lock", eventArgs) 
    }
    override fun onStorageEvent(eventArgs: StorageEvent) {
        // Receives Storage Events
        mListener?.onSignalingEvent("Storage", eventArgs) 
    }
    override fun onConnectionStateChanged(
        channelName: String?,
        state: RtmConstants.RtmConnectionState?,
        reason: RtmConstants.RtmConnectionChangeReason?
    ) {
        super.onConnectionStateChanged(channelName, state, reason)
    }
    override fun onTokenPrivilegeWillExpire(channelName: String) {
        // Receives Token Privilege Will Expire events
    }
}

Event Listeners

In Signaling, each token is specific to a user ID. If uid and token do not match, your user cannot initiate Signaling Engine.

fun login(uid: Int, token: String): Int {
    if (signalingEngine ==  null ) {
        setupSignalingEngine(uid)
    }
    signalingEngine?.login(token, object : ResultCallback<Void?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            if (errorInfo?.errorCode == RtmConstants.RtmErrorCode.DUPLICATE_OPERATION) {
                isLoggedIn = true
                logout()
            }
            notify("Login failed:\n"+ errorInfo.toString())// Handle failure
        }
        override fun onSuccess(responseInfo: Void?) {
            localUid = uid
            isLoggedIn = true
            notify("Successfully logged in")
            mListener?.onLoginLogout(isLoggedIn) // notify the UI
        }           
    })
    return 0
}

To start receiving messages and event notifications from a channel, you call subscribe.

fun subscribe(channelName: String): Int {
    // Subscribe to a channel
    val subscribeOptions = SubscribeOptions(true, true, true, true)
    signalingEngine?.subscribe(channelName, subscribeOptions, object: ResultCallback<Void?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            notify("Subscribe failed:\n"+ errorInfo.toString())
        }
        override fun onSuccess(responseInfo: Void?) {
            isSubscribed = true
            mListener?.onSubscribeUnsubscribe(isSubscribed)
            notify("Subscribed to channel: $channelName")
        }
    })
    return 0
}

Send a message

Messages are published directly to a channel.

fun publishChannelMessage (message: String): Int {
    val publishOptions = PublishOptions()
    signalingEngine?.publish(channelName, message, publishOptions, object: ResultCallback<Void?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            notify("Failed to send message:\n"+ errorInfo.toString())
        }
        override fun onSuccess(responseInfo: Void?) {
            notify("Message sent")
        }
    })
    return 0
}

publish

You setup the event handlers for messages received from other users during Signaling Engine initiation.

Unsubscribe from a channel

When you no longer need to receive channel notifications, call unsubscribe.

fun unsubscribe(channelName: String): Int {
    signalingEngine?.unsubscribe(channelName, object: ResultCallback<Void?> {
        override fun onFailure(errorInfo: ErrorInfo?) {
            notify("Unsubscribe failed:\n"+ errorInfo.toString())
        }
        override fun onSuccess(responseInfo: Void?) {
            isSubscribed = false
            notify("Unsubscribed from channel: $channelName")
            mListener?.onSubscribeUnsubscribe(isSubscribed)
        }
    })
    return 0
}

unsubscribe

Logout of Signaling

Had enough of the conversation? Just logout.

open fun logout() {
    if (!isLoggedIn) {
        notify("You need to login first")
    } else {
        // To leave a channel, call the `leaveChannel` method
        signalingEngine?.logout(object: ResultCallback<Void?> {
            override fun onFailure(errorInfo: ErrorInfo?) {
                notify("Logout failed:\n"+ errorInfo.toString())
            }
            override fun onSuccess(responseInfo: Void?) {
                isLoggedIn = false
                if (isSubscribed) {
                    isSubscribed = false
                    mListener?.onSubscribeUnsubscribe(isSubscribed)
                }
                notify("Logged out successfully")
                mListener?.onLoginLogout(isLoggedIn)
                // Destroy the engine instance
                destroySignalingEngine()
            }
        })
    }
}

logout

You have just implemented the Signaling workflow. Yes, it's as easy as that.

Test Signaling

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
1. Open the file <samples-root>/signaling-manager/src/main/res/raw/config.json
2. Replace the value for appId with the value from Agora Console.
3. Generate an RTM token using your uid.
4. Replace the value for token with the Signaling token.
5. Replace the value for uid with the the value you used to generate the token.
6. Ensure that the channelName is filled in. The channel name can be any string.
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.
Test the basic functionality:
1. Open a new instance of the reference app.
2. Choose the SDK quickstart example.
3. Log in to Signaling.
4. Subscribe to a channel, then send and receive messages.

Reference

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

Token expiration

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:

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