Quick Start: Android

  • Jul 5, 2016
  • Starting Guide
  • Android
  • Tutorial

Get your free API key

Before you can use the Realtime Messaging API you need to register, create a "Realtime Messaging Subscription" and make a note of your Realtime application key (this document will refer to it as APP_KEY).

A note about security

This Quick Start Guide assumes your APP_KEY has authentication disabled (by default and for simplity reasons all Realtime application keys have authentication disabled when they are created).

This means you can use any token to connect to a Realtime server. In the examples below we'll use testToken.

When you're ready for production you should enable authentication (we'll cover this on the Security section ahead).

Install the client library

In your build.gradle script for your application module, add the Realtime library as a dependency:

dependencies {
    compile 'co.realtime:messaging-android:2.1.+'

Open a connection to Realtime

Before you can start sending and receiving messages you need to open a connection to a Realtime server. Use the following code replacing APP_KEY with your Realtime application key:

import ibt.ortc.extensibility.*;
import ibt.ortc.api.*;


OrtcFactory factory;
OrtcClient client;

Ortc ortc = new Ortc();

try {
    factory = ortc.loadOrtcFactory("IbtRealtimeSJ");
    client = factory.createClient();
    client.connect("APP_KEY", "testToken");
} catch (Exception e) {
    System.out.println(String.format("Realtime Error: %s", e.toString()));

Subscribe to a channel

Realtime Messaging is a pub/sub system based on channels (aka as topics). This means that each connected client can only receive messages on channels that were subscribed. To subscribe a channel you simply define the channel name and which callback function should handle each message received.

However you must guarantee that your client is propertly connected before you subscribe a channel by implementing the onConnected event. This event will be invoked when the connection is ready for subscriptions and/or sending messages.

The following code shows how to subscribe to channel myChannel using the onConnected event. Add it after your client.connect call entered above:

client.onConnected = new OnConnected() {
  public void run(final OrtcClient sender) {
    // Messaging client connected

    // Now subscribe the channel
    client.subscribe("myChannel", true,
        new OnMessage() {
        	// This function is the message handler
        	// It will be invoked for each message received in myChannel

            public void run(OrtcClient sender, String channel, String message) {
            	// Received a message

You're now ready to build and run your app! The previous code will show each message received through myChannel in your logcat.

To send messages to test your app you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co

Send a message to a channel

As soon as you are connected you can start sending messages directly from your webpage using the send method. Add the following code to your onConnected event handler to send a message to the myChannel channel:

client.send("myChannel", "A simple string message");			

Note that Realtime messages are text-based (UTF-8 encoded).

To receive messages sent from your app you can use the simple console available in the Realtime Account Management website or the advanced console available at console.realtime.co. Don't forget to subscribe the channel myChannel

More Android resources

The Realtime Android Java SDK has more methods, like requesting the presence data of a given channel, that are beyond the scope of this quick starting guide. Please refer to the complete Android console example in GitHub to test the entire SDK features.

Back to JavaScript Quick Start - Next: iOS Quick Start

If you find this interesting please share: