​

Sync Chat SDK for Android (Compose): Quickstart

Note: This page is for Jetpack Compose. See the Android View version of this SDK.

The Sync Chat SDK allows you to add real-time text chat to your Android app quickly and easily, without tackling the complexities of building a real-time system on your own.

This version of the SDK provides a composable that you can customize completely and embed within your existing apps.

Before starting

Enable Compose

To use this SDK, you must enable Jetpack Compose in your application. Add the following to your application module's build.gradle:

buildFeatures {
    compose true
}

Set the SDK version

Set the minimum Android SDK version to 26. A target of 33 is highly recommended.

android {
    defaultConfig {
        minSdk 26
        targetSdk 33
    }
}

Install the SDK

Download

To add the Aircore Sync Chat SDK for Compose to your app, include the following in your dependencies declaration inside your application module's build.gradle:

dependencies {
    implementation "io.aircore.panel:chat:$sync_version"
}

Get required permissions

Declare the following permissions in your AndroidManifest.xml:

<application>
    ...
    <uses-permission android:name="android.permission.INTERNET" />
    ...
</application>

Authenticate

To authenticate, create an app in the Developer Console and choose between one of the two different API keys.

To learn more about API keys and choose the right one for your needs, see Apps and API Keys.

Copying a publishable API key from the console.

Initialize the client

The Client object is the primary controller which powers this SDK. Besides authentication, it allows you to configure user metadata, control logging, and listen to important events that happen behind the scenes.

The client allows your app to bring your existing user/channel models and seamlessly integrate them into the panel.

Using a publishable API Key

import io.aircore.panel.common.*
import io.aircore.panel.chat.*

// Use a Publishable API Key directly from the developer console
private val client = Client.createWithPublishableApiKey(
    application = application,
    key = publishableApiKey,
    userId = userId
)

Using a secret API key and session auth tokens

import io.aircore.panel.common.*
import io.aircore.panel.chat.*

// Use a session auth token provided by your server by
// communicating with the Aircore's provisioning service using the Secret API key
private val client = Client.createWithSessionAuthToken(
    application = application,
    token = authToken,
    userId = userId
)

Once you create a Client object, you can set properties for the user that represent them on the panel.

client.userDisplayName = "Jane Doe"
client.userAvatarURL =  "http://user-profile-picture.png"

Configure the panel

To modify the panel's behavior or change the defaults of its various elements, create a ChatPanelConfiguration object.

private val config = ChatPanelConfiguration(
    panelTitle = "My Channel",
    panelSubtitle = "My Channel is a happy space where people can have fun",
    ...
)

You can configure the text used in every element of the panel by setting the appropriate property.

private val stringsConfig = ChatPanelStrings(
    joinButton = "Join",
    joiningButton = "Joining...",
    joinButtonTooltip = "Tap Join to start the the conversation",
    leaveButton = "Leave",
    retryButton = "Retry",
    emptyChatTitle = "No one is in the chat yet.",
    emptyChatJoinedSubtitle = "Be the first to send a message!",
    emptyChatNotJoinedSubtitle = "Tap Join below to be the first!",
    composerPlaceholder = "Send a message",
    genericErrorLabel = "Something went wrong..."
)

private val config = ChatPanelConfiguration(
    ...
    strings = stringsConfig
    ...
)

Set collapsed and expanded state options

You can further customize the expanded and collapsed state independently.

private val config = ChatPanelConfiguration(
    ...
    // Can be null to display Expanded state only
    collapsedStateOptions = CollapsedStateOptions.Bar(
        maxAvatar = 3,
        panelTitle = "Collpased Title",
        joinButtonText = "Collapsed Join"
        ...
    ),
    // Can be null to display Collapsed state only
    expandedStateOptions = ExpandedStateOptions(
        panelTitle = "Expanded Title",
        panelSubtitle = "Expanded Sub-title",
        joinButtonText = "Expanded Join"
        ...
    )
    ...
)
Expanded state
Collapsed state

For the complete configuration options, refer to our configuration docs.

Customize the user experience

To customize the user experience, you can choose which users can send messages.

The panel shows all users as they join. By default, all users can send messages.

Automatically join the chat

To have users join automatically, set previewBeforeJoin to false.

Customize the theme

The composable inherits its theming attributes such as Typography, Shapes and Colors from its closest MaterialTheme ancestor out of the box. It immediately fits with your brand and the feel of your application.

The PanelsTheme is an optional composable that wraps all Aircore panels. It provides even more customization options for most of the visible elements.

PanelsTheme(
    colors = PanelColors(
        background = Color.Yellow,
        primary = Color.Blue,
        primaryContrast = Color.DarkGray,
        danger = Color.Red,
        dangerContrast = Color.White,
        text = Color.Black,
        subtext = Color.LightGray,
        border = Color.Black
    ),
    avatarStyle = AvatarStyle(
        shape = CircleShape,
        backgroundColor = Color.Red
    ),
    avatarStackStyle = AvatarStackStyle(
        spacing = (-4).dp
    )
) {
    MediaPanel(...)
}

To provide chat-specific customization, you can wrap the chat panel with ChatPanelTheme.

ChatPanelTheme(
    colors = PanelColors(
        background = Color.Yellow,
        primary = Color.Blue,
        primaryContrast = Color.DarkGray,
        danger = Color.Red,
        dangerContrast = Color.White,
        text = Color.Black,
        subtext = Color.LightGray,
        border = Color.Black
    ),
    incomingMessageStyle = MessageStyle(
        backgroundColor = Color.White,
        backgroundContrastColor = Color.Black,
        borderColor = Color.LightGray,
        userNameColor = Color.Black
    ),
    outgoingMessageStyle = MessageStyle(
        backgroundColor = Color.Black,
        backgroundContrastColor = Color.White,
        borderColor = Color.LightGray,
        userNameColor = Color.White
    )
)

Examples

Example 1
Example 2

For the complete theming options for all panels, see our theming docs.

For chat theming options, see our chat-specific theming docs.

Create the panel

Finally, we're ready to put all this together to create the ChatPanel object and set it up in your app!

client.connect(channelId = channel)

MyAppTheme {
    PanelsTheme {
        ChatPanelTheme {
            ChatPanel(
                client = client,
                channelId = channel,
                configuration = configuration
            )
        }
    }
}

In the collapsed state, the ChatPanel fills its container. In the expanded state, it appears in its own Android dialog.

Use listeners for events and errors

You can subscribe to useful events that may be relevant to your app's business logic, such as receiving errors and responding accordingly:

client.addListener(object: ChatClientListener {
    override fun onLocalUserJoined(channelId: String) {
    }

    override fun onLocalUserLeft(channelId: String) {

    }

    override fun onSessionAuthTokenMismatch() {
        // Token does not match with user ID provided
    }

    override fun onSessionAuthTokenNearingExpiry() {
        // Fetch a new auth token from your server and update the client!
    }

    override fun onSessionAuthTokenInvalid() {
        // Request the server for a new token
    }

    override fun onError(e: Exception) {
        // Handle any errors
    }
    
    override fun onMessageSent(channelId: String, userId: String?, messageId: String?, content: String) {
        // A new message sent
    }

    override fun onMessageReceived(channelId: String, userId: String?, messageId: String?, content: String) {
        // A new message received
    }
    
    override fun onMessageFailed(channelId: String, userId: String?, messageId: String?, content: String) {
        // Failed sending a message
    }
    
    override fun onMessageCopied(channelId: String, userId: String?, messageId: String?, content: String) {
        // A message has been copied
    }
})

For the complete reference, see see the docs on events and errors.

Tear down and clean up

When you are done with the panel, you can tear down the client and panel as follows:

// Disconnecting a specific Channel ID
client.disconnect(channelId = channel)

// Tear down of the client (it will disconnect automatically from all connected channels)
client.destroy()

After you call destroy(), you cannot reuse the client with new panels. To continue, you must create a new instance of the client.

More info