Sync Chat SDK for Android (View): Quickstart

Note: This page is for Android View. See the Jetpack Compose 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 the View system to your app, include the following in your dependencies declaration inside your application module's build.gradle:

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

Get required permissions

Declare the following permissions in your AndroidManifest.xml:

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

Authenticate

This guide uses a publishable API key for a quick setup. To get your API key:

Create an app in the Developer Console.
Copy your publishable API key and use it in the next section.

Copying a publishable API key from the console.

For an overview of API keys, see Authentication.

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.

Use a publishable API key to create the client:

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

// Use a publishable API key directly from the Developer Console
Client client = Client.createWithPublishableApiKey(
        getApplication(),
        mPublishableApiKey,
        mUserId
        );

For more detailed security controls, you can use a secret API key instead. See Customization.

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

client.setUserDisplayName("Jane Doe");
client.setUserAvatarUrl("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.

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

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

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

ChatPanelConfiguration config = new ChatPanelConfiguration(
    ...
    stringsConfig, // strings
    ...
);

Set collapsed and expanded state options

You can further customize the expanded and collapsed state independently.

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

Examples

Expanded state

Collapsed state

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

Customize the user experience

You can customize how users interact with the chat. When a user joins a chat, they can see the full message history for the channel.

Disable sending messages

By default, all users can send messages. To change this, set canSendMessage to false.

Automatically join the chat

By default, users can preview the chat. To join, they must press a button. When users join, they appear on the panel.

To have users join automatically, set previewBeforeJoin to false.

Customize the theme

The view inherits its theming attributes such as text styles and color palette from your application's Theme out of the box. It immediately fits with your brand and the feel of your application.

The ChatPanelTheme is an optional parameter that you can use with the chat panel to customize most of the visible elements.

ChatPanelTheme theme = new ChatPanelTheme(
    // colors
    PanelColorsHelper.fromColorInt(
        getColor(R.color.green_500), // primary
        getColor(R.color.white), // primaryContrast
        getColor(R.color.error), // danger
        getColor(R.color.white), // dangerContrast
        getColor(R.color.white), // background
        getColor(R.color.black), // text
        getColor(android.R.color.darker_gray), // subtext
        getColor(R.color.border) // border
    ),
    // incomingMessageStyle
    new MessageStyle(
        getColor(R.color.white), // backgroundColor
        getColor(R.color.black), // backgroundColorContrast
        getColor(R.color.border), // borderColor
        getColor(R.color.green_500) // userNameColor
    ),
    // outgoingMessageStyle
    new MessageStyle(
        getColor(R.color.green_500), // backgroundColor
        getColor(R.color.white), // backgroundColorContrast
        getColor(R.color.green_200), // borderColor
        getColor(R.color.white) // userNameColor
    ),
    new PanelIconography(
        R.drawable.common_ic_collapse, // collapse
        R.drawable.common_ic_expand, // expand
        R.drawable.common_ic_share, // share
        R.drawable.common_ic_overflow, // overflowMenu
        R.drawable.common_ic_headphones, // join
        R.drawable.common_ic_close,  // leave
    ),
    new Shapes()
    new AvatarStyle(
        RectangleShape,  // shape
        Color(getColor(R.color.green_500)) // backgroundColor
    ),
    new AvatarStackStyle(
        DpKt.getDp(-8) // spacing
    )
);

Examples

Example 1

Example 2

For the complete theming options, see our theming docs.

Create the panel

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

In your activity's layout file, add ChatPanelView:

<LinearLayout
    android:layout_width="match_parent"
    android:layout_height="106dp"
    andorid:orientation="vertical">
    <io.aircore.panel.chat.view.ChatPanelView
        android:id="@+id/chat_panel_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
    />
</LinearLayout>

Finally, find your ChatPanelView and connect:

client.connect(channelId = channel)

ChatPanelView chatPanelView = findViewById(R.id.chat_panel_view);
chatPanelView.connect(client, channelId, customTheme, customConfiguration);

In the collapsed state, the ChatPanelView 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(new ChatClientListener() {
    @Override
    public void onLocalUserJoined(@NonNull String channelId) {}
    
    @Override
    public void onLocalUserLeft(@NonNull String channelId) {}
    
    @Override
    public void onError(@NonNull Exception e) {}
    
    @Override
    public void onMessageSent(@NonNull String channelId, @Nullable String userId, @Nullable String messageId, @NonNull String content) {}

    @Override
    public void onMessageReceived(@NonNull String channelId, @Nullable String userId, @Nullable String messageId, @NonNull String content) {}

    @Override
    public void onMessageFailed(@NonNull String channelId, @Nullable String userId, @Nullable String messageId, @NonNull String content) {}

    @Override
    public void onMessageCopied(@NonNull String channelId, @Nullable String userId, @Nullable String messageId, @NonNull String content) {}

    // Implement other notification handlers.
    // ...
});

For the complete reference, 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(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

To continue customizing the panel, see Customization.
Download the sample app
Download the SDK
See the full API reference