Android

The Mitter.io Android SDK is distributed freely via jCenter and you can add it easily to your project by adding it as a standard dependency.

Creating a new project

Create a new Android app project by following the standard procedure listed below. Alternatively, you can skip the setup part by cloning our starter template and loading it into Android Studio.

To create a project from scratch, do the following:

• Go to File

• Click on New, followed by New Project

• Follow the steps, keep everything set to default or customize to your needs

Adding dependency

Now add the Android SDK to your newly created project by opening up your build.gradle file and pasting the following line in the dependencies block:

build.gradle
implementation 'io.mitter.android:core:0.1.7'

Once that is added, perform a Gradle sync.

Basic setup

Now that you’ve added the SDK, the next step is to add some initial configuration for the SDK to work.

Note: This documentation contains code snippets for both Kotlin and Java. Switch to the relevant tab while building the demo.

To start working, you need to configure a Mitter object with your application details, which you can access from the Mitter.io Dashboard.

Before you proceed, visit the Mitter.io Dashboard, create an application and grab the application ID.

Next, you need to create a custom implementation of the Application class for your app. You can do so by creating a new class and extending the Application class:

MyApp.kt
class MyApp: Application() {}

MyApp.java
class MyApp extends Application {}

Once that’s in place, override the onCreate() method. This is where you’ll be configuring the Mitter object.

Your custom Application class should look something like this:

MyApp.kt
class MyApp: Application() {
    //Defining the mitter object
    lateinit var mitter: Mitter
​
    override fun onCreate() {
        super.onCreate()
    }
}

MyApp.java
class MyApp extends Application {
    //Defining the mitter object
    private Mitter mitter;
​
    @Override
    public void onCreate() {
        super.onCreate();
    }
}

Just defining the Mitter object isn’t enough. You need to configure it with the application ID that you retrieved from the Mitter.io Dashboard.

Here's how to do that: Just paste this inside your onCreate() method in the MyApp class:

MyApp.kt
val mitterConfig = MitterConfig(
    applicationId = "your-application-id-here"
)
​
mitter = Mitter(
    context = this,
    mitterConfig = mitterConfig
)

MyApp.java
MitterConfig mitterConfig = new MitterConfig(
    "your-application-id-here",
    LoggingLevel.BASIC,
    null
);
​
mitter = new Mitter(
    this,
    mitterConfig,
    new UserAuth("", "")
);

Using the SDK with containerised Mitter.io

If you're using the Mitter.io docker container, then you need to override the default API endpoint in the SDK, as follows:

MyApp.kt
val mitterConfig = MitterConfig(
    applicationId = "your-application-id-here",
    apiEndpoint = MitterApiEndpoint(
        "http://localhost:11901",
        "http://localhost:11901"
    )
)

MyApp.java
MitterConfig mitterConfig = new MitterConfig(
    "your-application-id-here",
    LoggingLevel.BASIC,
    new MitterApiEndpoint(
        "http://localhost:11901",
        "http://localhost:11901"
    )
);

That’s all you need to do for the very basic configuration. It’s not ready to connect with the platform just yet, but we’ll get to that part in the later sections.

Setup FCM

Mitter.io works hand-in-hand with Firebase Cloud Messaging (FCM) to deliver messages in real-time to Android devices.

To start receiving messages, you need to setup FCM in your Android app and make a couple of changes in your application in the Mitter.io Dashboard.

First of all, you need to setup FCM in your Android project. The steps for this setup are beyond the scope of this tutorial, and since Google has done a pretty good job explaining the same, you can check out their docs if you haven’t already added FCM to your project.

After you’re through with that, the only thing that's left is to feed your FCM server key in your Mitter.io application inside the Dashboard.

You can do that by following these steps:

• Open the Mitter.io Dashboard and select your application from the list

• Go to the Properties tab

• Click on New Property -> Google -> FCM -> FCM Property

• You’ll get a modal where you need to fill out your app’s instance ID, which can be easily retrieved from the Google Cloud Console​

• Also, you need to feed in your FCM server key, which can be accessed from your FCM admin panel

• After you’re done feeding this data, click on New FCM Configuration Property

Once you’ve completed these steps, you need to register a delivery endpoint for Mitter.io to deliver your messages.

In your Android project, create a class called MyFirebaseMessagingService which extends FirebaseMessagingService and override the onNewToken() method.

In the onNewToken() you need to get a reference to your Mitter object which you declared in your custom Application class.

MyFirebaseMessagingService.kt
class MyFirebaseMessagingService: FirebaseMessagingService() {
    override fun onNewToken(token: String?) {
        val mitter = (application as MyApp).mitter
    }
}

MyFirebaseMessagingService.java
public class MyFirebaseMessagingServiceJava extends FirebaseMessagingService {
    @Override
    public void onNewToken(String token) {
        Mitter mitter = ((MyApp) getApplication()).mitter;
    }
}

Now that you have a reference to the Mitter object, you need to register the token with Mitter.io. Just add the following piece of code in your onNewToken() method:

MyFirebaseMessagingService.kt
token?.let {
    mitter.registerFcmToken(
        it,
        object : Mitter.OnValueAvailableCallback<DeliveryEndpoint> {
            override fun onValueAvailable(value: DeliveryEndpoint) {
                //Delivery endpoint registered
            }
​
            override fun onError(error: ApiError) {
                //Delivery endpoint failed to register, retry
            }
        }
    )
}

MyFirebaseMessagingService.java
if (token != null) {
    mitter.registerFcmToken(
        token,
        new Mitter.OnValueAvailableCallback<DeliveryEndpoint>() {
            @Override
            public void onValueAvailable(DeliveryEndpoint deliveryEndpoint) {
                //Delivery endpoint registered
            }
​
            @Override
            public void onError(ApiError apiError) {
                //Delivery endpoint failed to register, retry
            }
        }
    );
}

Once that is done, the next step is to intercept any incoming push messages and pass them to the SDK for processing.

Get started by overriding the onMessageReceived() method and adding this piece of code inside the method:

MyFirebaseMessagingService.kt
if (remoteMessage.data.isNotEmpty()) {
    val mitter = (application as MyApp).mitter
    val messagingPipelinePayload = mitter.parseFcmMessage(remoteMessage.data)
​
    if (mitter.isMitterMessage(messagingPipelinePayload)) {
        mitter.processPushMessage(messagingPipelinePayload)
    }
}

MyFirebaseMessagingService.java
if (!remoteMessage.getData().isEmpty()) {
    Mitter mitter = ((MyApp) getApplication()).mitter;
    MessagingPipelinePayload messagingPipelinePayload = mitter.parseFcmMessage(remoteMessage.getData());
​
    if (mitter.isMitterMessage(messagingPipelinePayload)) {
        mitter.processPushMessage(messagingPipelinePayload, null);
    }
}

Okay, the SDK is all set to intercept incoming messages and process them. The only thing that’s left is to register a callback on the Mitter object to get notified when a new message arrives.

Head back to your custom Application class and register a OnPushMessageReceivedCallback on the Mitter object that you had already created.

MyApp.kt
mitter.registerOnPushMessageReceivedListener(object : Mitter.OnPushMessageReceivedCallback {
    override fun onChannelStreamData(
        channelId: String,
        streamId: String,
        streamData: ContextFreeMessage
    ) {
        //Called when there's some streaming data such as typing indicator
    }
​
    override fun onNewChannel(channel: Channel) {
        //Called when a new channel is created where the user is a participant
    }
​
    override fun onNewChannelTimelineEvent(
        channelId: String,
        timelineEvent: TimelineEvent
    ) {
        //Called when there's a new timeline event for a channel
    }
​
    override fun onNewMessage(
        channelId: String,
        message: Message
    ) {
        //Called when a new message has arrived for the user
    }
​
    override fun onNewMessageTimelineEvent(
        messageId: String,
        timelineEvent: TimelineEvent
    ) {
        //Called when there's a new timeline event for a message
    }
​
    override fun onParticipationChangedEvent(
        channelId: String,
        participantId: String,
        newStatus: ParticipationStatus,
        oldStatus: ParticipationStatus?
    ) {
        //Called when the user has joined a new channel or has been removed from one
    }
})

MyApp.java
mitter.registerOnPushMessageReceivedListener(new Mitter.OnPushMessageReceivedCallback() {
    @Override
    public void onNewMessage(
        String channelId,
        Message message
    ) {
        //Called when a new message has arrived for the user
    }
​
    @Override
    public void onNewChannel(Channel channel) {
        //Called when a new channel is created where the user is a participant
    }
​
    @Override
    public void onNewMessageTimelineEvent(
        String messageId,
        TimelineEvent timelineEvent
    ) {
        //Called when there's a new timeline event for a message
    }
​
    @Override
    public void onNewChannelTimelineEvent(
        String channelId,
        TimelineEvent timelineEvent
    ) {
        //Called when there's a new timeline event for a channel
    }
​
    @Override
    public void onParticipationChangedEvent(
        String channelId, String participantId,
        ParticipationStatus participationStatus,
        ParticipationStatus participationStatus1
    ) {
        //Called when the user has joined a new channel or has been removed from one
    }
​
    @Override
    public void onChannelStreamData(
        String channelId,
        String streamId,
        ContextFreeMessage contextFreeMessage
    ) {
        //Called when there's some streaming data such as typing indicator
    }
});

You’re now done with the basic setup. Let’s move on to set up a user to start interacting with the platform and send messages.