SDK quickstart

This page shows you how to create your first Signaling app using Signaling SDK.

Understand the tech

Log in to Signaling

The login process includes:

The app client requests a token from your app server.
The app server returns the token to the app client.
The app client logs in to Signaling with the token.

Peer-to-peer messaging

The peer messaging process includes:

Client A sends a peer message to Signaling.
Signaling sends the message to client B. Client B receives the peer message.

Channel messaging

The channel messaging process includes:

Client A creates a channel and join the channel.
Client B and client C joins the channel created by client A.
Client A sends a channel message to Signaling.
Signaling sends the channel message to client B and C. Client B and client C receives the message.

For an app client to join a channel, you need the following information:

The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
A token: In a test or production environment, your app client retrieves tokens from your server.
The channel name: A string that identifies the channel for the channel messaging.

Prerequisites

In order to follow this procedure you must have:

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.

Project setup

Follow the steps to create the environment necessary to add Signaling into your app.

1. Create an Android project

Use Android Studio to create an Android project.

Select the Project Template as Empty Activity.
Enter RtmQuickstart as the Name.
Enter com.example.rtmquickstart as the Package name.
Select Language as Java.

2. Add permissions

Add the following permissions in the AndroidManifest.xml file.

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  // As of v1.4.10, you don't need to add the WRITE_EXTERNAL_STORAGE permission:
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  // As of v1.4.9, you also need to add the following permission to check the connection status of the WIFI network:
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

If your app targets Android 6.0 or higher, you need to dynamically apply for the above permissions, see Request app permissions for details.

If your app targets Android 10 or higher, refer to Privacy changes in Android 10.

3. Prevent code obfuscation

Add the following line in the app/proguard-rules.pro file to prevent code obfuscation:

    -keep class io.agora.**{*;}

If an error is reported, you can change the code as:

 -keep class io.agora**{\*;}

4. Integrate the SDK

Integrate the Agora Signaling Android SDK into your project with Maven Central. For more integration methods, see Other approaches to integrate the SDK.

In /Gradle Scripts/build.gradle(Project: <projectname>), add the following lines to add the Maven Central dependency:

_14buildscript { _14repositories { _14… _14mavenCentral() _14} _14… _14} _14 _14allprojects { _14repositories { _14… _14mavenCentral() _14} _14}
In /Gradle Scripts/build.gradle(Module: <projectname>.app), add the following lines to integrate the Agora Signaling Android SDK into your Android project:

_7… _7dependencies { _7… _7// For x.y.z, fill in a specific SDK version number. For example, 1.4.9. _7// Get the latest version number through the release notes. _7implementation 'io.agora.rtm:rtm-sdk:x.y.z' _7}

Implement Signaling

This section shows how to use the Agora Signaling SDK to implement Signaling into your app step by step.

1. Implement the UI and resource files

To help you quickly understand and implement functions of Agora Signaling, this section shows how to implement the following functions in an Activity with minimum effort:

Log in to and log out of Agora Signaling
Join and leave a channel
Send and receive peer-to-peer or channel messages
See the changes in connection state of the user
1. Open the app/res/layout/activity_main.xml file with Android Studio, edit it in Code mode, and replace the contents of the file with the following:
  
  _161<?xml version="1.0" encoding="utf-8"?> _161<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android" _161xmlns:app="http://schemas.android.com/apk/res-auto" _161xmlns:tools="http://schemas.android.com/tools" _161android:layout_width="match_parent" _161android:layout_height="match_parent" _161android:background="#FFFFFF" _161tools:context=".MainActivity"> _161 _161<Button _161 android:id="@+id/login_button" _161 android:layout_width="wrap_content" _161 android:layout_height="wrap_content" _161 android:layout_marginStart="4dp" _161 android:layout_marginTop="40dp" _161 android:layout_marginEnd="132dp" _161 android:onClick="onClickLogin" _161 android:text="@string/login_button" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintHorizontal_bias="0.0" _161 app:layout_constraintStart_toEndOf="@+id/uid" _161 app:layout_constraintTop_toTopOf="parent" /> _161 _161<EditText _161 android:id="@+id/uid" _161 android:layout_width="150dp" _161 android:layout_height="40dp" _161 android:layout_marginStart="37dp" _161 android:layout_marginTop="40dp" _161 android:autofillHints="" _161 android:hint="@string/uid" _161 android:inputType="text" _161 android:lines="1" _161 android:padding="5dp" _161 app:layout_constraintStart_toStartOf="parent" _161 app:layout_constraintTop_toTopOf="parent" /> _161 _161<EditText _161 android:id="@+id/channel_name" _161 android:layout_width="155dp" _161 android:layout_height="41dp" _161 android:layout_marginStart="36dp" _161 android:layout_marginTop="124dp" _161 android:layout_marginBottom="41dp" _161 android:autofillHints="" _161 android:ems="10" _161 android:hint="@string/channel_name" _161 android:inputType="text" _161 app:layout_constraintBottom_toTopOf="@+id/msg_box" _161 app:layout_constraintStart_toStartOf="parent" _161 app:layout_constraintTop_toTopOf="parent" /> _161 _161<Button _161 android:id="@+id/join_button" _161 android:layout_width="wrap_content" _161 android:layout_height="wrap_content" _161 android:layout_marginStart="8dp" _161 android:layout_marginTop="28dp" _161 android:layout_marginBottom="24dp" _161 android:onClick="onClickJoin" _161 android:text="@string/join_button" _161 app:layout_constraintBottom_toTopOf="@+id/msg_box" _161 app:layout_constraintStart_toEndOf="@+id/channel_name" _161 app:layout_constraintTop_toBottomOf="@+id/login_button" /> _161 _161<EditText _161 android:id="@+id/msg_box" _161 android:layout_width="198dp" _161 android:layout_height="57dp" _161 android:layout_marginStart="32dp" _161 android:layout_marginTop="10dp" _161 android:layout_marginBottom="12dp" _161 android:autofillHints="" _161 android:ems="10" _161 android:hint="@string/msg" _161 android:inputType="textPersonName" _161 android:singleLine="false" _161 app:layout_constraintBottom_toTopOf="@+id/peer_name" _161 app:layout_constraintStart_toStartOf="parent" _161 app:layout_constraintTop_toBottomOf="@+id/join_button" /> _161 _161<Button _161 android:id="@+id/send_channel_msg_button" _161 android:layout_width="126dp" _161 android:layout_height="45dp" _161 android:layout_marginTop="38dp" _161 android:layout_marginEnd="36dp" _161 android:layout_marginBottom="26dp" _161 android:onClick="onClickSendChannelMsg" _161 android:text="@string/send_channel_msg_button" _161 app:layout_constraintBottom_toTopOf="@+id/send_peer_msg_button" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintTop_toBottomOf="@+id/leave_button" /> _161 _161<Button _161 android:id="@+id/logout_button" _161 android:layout_width="wrap_content" _161 android:layout_height="wrap_content" _161 android:layout_marginStart="11dp" _161 android:layout_marginTop="40dp" _161 android:layout_marginEnd="28dp" _161 android:onClick="onClickLogout" _161 android:text="@string/logout_button" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintHorizontal_bias="0.0" _161 app:layout_constraintStart_toEndOf="@+id/login_button" _161 app:layout_constraintTop_toTopOf="parent" /> _161 _161<Button _161 android:id="@+id/leave_button" _161 android:layout_width="wrap_content" _161 android:layout_height="wrap_content" _161 android:layout_marginTop="27dp" _161 android:layout_marginEnd="28dp" _161 android:onClick="onClickLeave" _161 android:text="@string/leave_button" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintTop_toBottomOf="@+id/logout_button" /> _161 _161<EditText _161 android:id="@+id/peer_name" _161 android:layout_width="121dp" _161 android:layout_height="48dp" _161 android:layout_marginStart="64dp" _161 android:layout_marginTop="24dp" _161 android:ems="10" _161 android:hint="@string/peer_name" _161 android:inputType="text" _161 app:layout_constraintStart_toStartOf="parent" _161 app:layout_constraintTop_toBottomOf="@+id/send_channel_msg_button" /> _161 _161<Button _161 android:id="@+id/send_peer_msg_button" _161 android:layout_width="wrap_content" _161 android:layout_height="wrap_content" _161 android:layout_marginTop="17dp" _161 android:layout_marginEnd="56dp" _161 android:onClick="onClickSendPeerMsg" _161 android:text="@string/send_peer_msg_button" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintTop_toBottomOf="@+id/send_channel_msg_button" /> _161 _161<TextView _161 android:id="@+id/message_history" _161 android:layout_width="412dp" _161 android:layout_height="339dp" _161 android:layout_marginTop="392dp" _161 android:background="#AEA8A8" _161 android:freezesText="false" _161 android:isScrollContainer="false" _161 android:scrollbars="vertical" _161 android:textColor="#2196F3" _161 app:layout_constraintBottom_toBottomOf="parent" _161 app:layout_constraintEnd_toEndOf="parent" _161 app:layout_constraintHorizontal_bias="0.491" _161 app:layout_constraintStart_toStartOf="parent" _161 app:layout_constraintTop_toTopOf="parent" _161 app:layout_constraintVertical_bias="0.352" /> _161 _161 _161</androidx.constraintlayout.widget.ConstraintLayout>
2. Open the app/res/values/strings.xml file and replace the contents of the file with the following:
  
  _16<resources> _16<string name="app_name">RtmQuickstart</string> _16<string name="login_button">Login</string> _16<string name="logout_button">Logout</string> _16<string name="join_button">Join</string> _16<string name="leave_button">Leave</string> _16<string name="send_peer_msg_button">Peer MSG</string> _16<string name="send_channel_msg_button">Group MSG</string> _16<string name="uid">Enter your uid</string> _16<string name="msg">Enter your message</string> _16<string name="channel_name">Channel name</string> _16<string name="peer_name">Peer name</string> _16<string name="app_id">Your App ID</string> _16<string name="token">Your Token</string> _16 _16</resources>

You need to edit the following fields:

Replace Your App ID with the App ID of your project.
Replace Your Token with the Token you obtained.

2. Implement the logic of sending and receiving messages

Open the app/java/com.example.rtmquickstart/MainActivity.java file and replace the contents of the file with the following:

package com.example.rtmquickstart;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.view.View;
import android.widget.EditText;
import android.widget.TextView;
import android.widget.Toast;
import java.util.List;
import java.util.Map;
import io.agora.rtm.ErrorInfo;
import io.agora.rtm.ResultCallback;
import io.agora.rtm.RtmChannel;
import io.agora.rtm.RtmChannelAttribute;
import io.agora.rtm.RtmChannelListener;
import io.agora.rtm.RtmChannelMember;
import io.agora.rtm.RtmClient;
import io.agora.rtm.RtmClientListener;
import io.agora.rtm.RtmFileMessage;
import io.agora.rtm.RtmImageMessage;
import io.agora.rtm.RtmMediaOperationProgress;
import io.agora.rtm.RtmMessage;
import io.agora.rtm.SendMessageOptions;
public class MainActivity extends AppCompatActivity {
// Define global variables
// EditText objects from the UI
private EditText et_uid;
private EditText et_channel_name;
private EditText et_message_content;
private EditText et_peer_id;
// <Vg k="MESS" /> uid
private String uid;
// <Vg k="MESS" /> channel name
private String channel_name;
// Agora App ID
private String AppID;
// <Vg k="MESS" /> client instance
private RtmClient mRtmClient;
// <Vg k="MESS" /> channel instance
private RtmChannel mRtmChannel;
// TextView to show message records in the UI
private TextView message_history;
// <Vg k="MESS" /> user ID of the message receiver
private String peer_id;
// Message content
private String message_content;
@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    // Initialize the <Vg k="MESS" /> client
    try {
        AppID = getBaseContext().getString(R.string.app_id);
        // Initialize the <Vg k="MESS" /> client
        mRtmClient = RtmClient.createInstance(getBaseContext(), AppID,
                new RtmClientListener() {
                    @Override
                    public void onConnectionStateChanged(int state, int reason) {
                        String text = "Connection state changed to " + state + "Reason: " + reason + "\n";
                        writeToMessageHistory(text);
                    }
                    @Override
                    public void onImageMessageReceivedFromPeer(RtmImageMessage rtmImageMessage, String s) {
                    }
                    @Override
                    public void onFileMessageReceivedFromPeer(RtmFileMessage rtmFileMessage, String s) {
                    }
                    @Override
                    public void onMediaUploadingProgress(RtmMediaOperationProgress rtmMediaOperationProgress, long l) {
                    }
                    @Override
                    public void onMediaDownloadingProgress(RtmMediaOperationProgress rtmMediaOperationProgress, long l) {
                    }
                    @Override
                    public void onTokenExpired() {
                    }
                    @Override
                    public void onPeersOnlineStatusChanged(Map<String, Integer> map) {
                    }
                    @Override
                    public void onMessageReceived(RtmMessage rtmMessage, String peerId) {
                        String text = "Message received from " + peerId + " Message: " + rtmMessage.getText() + "\n";
                        writeToMessageHistory(text);
                    }
                });
    } catch (Exception e) {
        throw new RuntimeException("<Vg k="MESS" /> initialization failed!");
    }
}
// Button to login to Signaling
public void onClickLogin(View v)
{
    et_uid = (EditText) findViewById(R.id.uid);
    uid = et_uid.getText().toString();
    String token =getBaseContext().getString(R.string.token);
    // Log in to Signaling
    mRtmClient.login(token, uid, new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void responseInfo) {
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
            CharSequence text = "User: " + uid + " failed to log in to Signaling!" + errorInfo.toString();
            int duration = Toast.LENGTH_SHORT;
            runOnUiThread(new Runnable() {
                public void run() {
                    Toast toast = Toast.makeText(getApplicationContext(), text, duration);
                    toast.show();
                }
            });
        }
    });
}
// Button to join the <Vg k="MESS" /> channel
public void onClickJoin(View v)
{
    et_channel_name = (EditText) findViewById(R.id.channel_name);
    channel_name = et_channel_name.getText().toString();
    // Create a channel listener
    RtmChannelListener mRtmChannelListener = new RtmChannelListener() {
        @Override
        public void onMemberCountUpdated(int i) {
        }
        @Override
        public void onAttributesUpdated(List<RtmChannelAttribute> list) {
        }
        @Override
        public void onMessageReceived(RtmMessage message, RtmChannelMember fromMember) {
            String text = message.getText();
            String fromUser = fromMember.getUserId();
            String message_text = "Message received from " + fromUser + " : " + text + "\n";
            writeToMessageHistory(message_text);
        }
        @Override
        public void onImageMessageReceived(RtmImageMessage rtmImageMessage, RtmChannelMember rtmChannelMember) {
        }
        @Override
        public void onFileMessageReceived(RtmFileMessage rtmFileMessage, RtmChannelMember rtmChannelMember) {
        }
        @Override
        public void onMemberJoined(RtmChannelMember member) {
        }
        @Override
        public void onMemberLeft(RtmChannelMember member) {
        }
    };
    try {
        // Create an <Vg k="MESS" /> channel
        mRtmChannel = mRtmClient.createChannel(channel_name, mRtmChannelListener);
    } catch (RuntimeException e) {
    }
    // Join the <Vg k="MESS" /> channel
    mRtmChannel.join(new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void responseInfo) {
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
            CharSequence text = "User: " + uid + " failed to join the channel!" + errorInfo.toString();
            int duration = Toast.LENGTH_SHORT;
            runOnUiThread(new Runnable() {
                public void run() {
                    Toast toast = Toast.makeText(getApplicationContext(), text, duration);
                    toast.show();
                }
            });
        }
    });
}
// Button to log out of Signaling
public void onClickLogout(View v)
{
    // Log out of Signaling
    mRtmClient.logout(null);
}
// Button to leave the <Vg k="MESS" /> channel
public void onClickLeave(View v)
{
    // Leave the <Vg k="MESS" /> channel
    mRtmChannel.leave(null);
}
// Button to send peer-to-peer message
public void onClickSendPeerMsg(View v)
{
    et_message_content = findViewById(R.id.msg_box);
    message_content = et_message_content.getText().toString();
    et_peer_id = findViewById(R.id.peer_name);
    peer_id = et_peer_id.getText().toString();
    // Create <Vg k="MESS" /> message instance
    final RtmMessage message = mRtmClient.createMessage();
    message.setText(message_content);
    SendMessageOptions option = new SendMessageOptions();
    option.enableOfflineMessaging = true;
    // Send message to peer
    mRtmClient.sendMessageToPeer(peer_id, message, option, new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            String text = "Message sent from " + uid + " To " + peer_id + " ： " + message.getText() + "\n";
            writeToMessageHistory(text);
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
            String text = "Message fails to send from " + uid + " To " + peer_id + " Error ： " + errorInfo + "\n";
            writeToMessageHistory(text);
        }
    });
}
// Button to send channel message
public void onClickSendChannelMsg(View v)
{
    et_message_content = findViewById(R.id.msg_box);
    message_content = et_message_content.getText().toString();
    // Create <Vg k="MESS" /> message instance
    RtmMessage message = mRtmClient.createMessage();
    message.setText(message_content);
    // Send message to channel
    mRtmChannel.sendMessage(message, new ResultCallback<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            String text = "Message sent to channel " + mRtmChannel.getId() + " : " + message.getText() + "\n";
            writeToMessageHistory(text);
        }
        @Override
        public void onFailure(ErrorInfo errorInfo) {
            String text = "Message fails to send to channel " + mRtmChannel.getId() + " Error: " + errorInfo + "\n";
            writeToMessageHistory(text);
        }
    });
}
// Write message records to the TextView
public void writeToMessageHistory(String record)
{
    message_history = findViewById(R.id.message_history);
    message_history.append(record);
}
}

Test your app

Build the project in Android Studio, and run it on a simulator or a physical mobile device. If the project runs successfully, you are able to:

Log in to and log out of Agora Signaling.
Join and leave a channel.
Send and receive peer-to-peer or channel messages.
See the changes in the connection state of the user and changes in the channel state.

You can see the following page if your project runs successfully:

1623051651101

Considerations

The Agora Signaling SDK supports creating multiple RtmClient instances that are independent of each other.
To send and receive peer-to-peer or channel messages, ensure that you have successfully logged in the Agora Signaling (you have received onSuccessonSuccess.
To use any of the channel features, you must first call the createChannel method to create a channel instance.
You can create multiple channel instances for each RtmClient instance, but you can only join a maximum of 20 channels at the same time. The channelId parameter needs to be channel-specific.
When you leave a channel and do not want to join it again, you can call the release method to release all resources used by the channel instance.
You cannot reuse a received RtmMessage instance.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start Signaling with a token that you retrieve from your server.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start live streaming with a token that you retrieve from your server.

SDK quickstart

Understand the tech

Log in to Signaling

Peer-to-peer messaging

Channel messaging

Prerequisites

Project setup

1. Create an Android project

2. Add permissions

3. Prevent code obfuscation

4. Integrate the SDK

Implement Signaling

1. Implement the UI and resource files

2. Implement the logic of sending and receiving messages

Test your app

Considerations

Next steps

See also

Sample project

Other approaches to integrate the SDK

Next steps