Quickstart

Channel.io Android SDK helps you easily install real-time chat and marketing features for Android applications written in Kotlin/Java. For those who want to embed the SDK in the WebView or a mobile web, see how to get started with JavaScript SDK.

Prerequisite

You should check that all these conditions are met before installing the SDK:

• Paid Channel.io service plan
• Minimum installable Android API level ≥ 15
  • The minimum Android API level required for SDK to function is Android API level 21.
• Android Gradle Plugin ≥ 4.0.0
• sourceCompatibility, targetCompatibility ≥ 1.8

Installation

Add a dependency on our SDK.

We guarantee one year maintenance of each versions. See release notes for details.

dependencies {
    implementation 'io.channel:plugin-android:$[version]'
}

repositories {
    mavenCentral()
}

Transitive Dependencies

While we try our best to avoid transitive dependency conflicts (changing package names, for example), you may have to resolve it manually by configuring Gradle. Please open a new chat if you have an issue with the dependency resolution regarding our SDK.

Proguard (optional)

If you are using SDK version 10.0.0 or below and using ProGuard, you should add the following rules to your proguard-rules.pro.

-keep class com.zoyi.**{ *; }
-keep class io.channel.**{ *; }
-dontwarn com.zoyi.**
-dontwarn io.channel.**

Initial Setup

To use Channel SDK, you should call ChannelIO.initialize() from Application#onCreate(). If you don’t have your own Application class, create a new one.

Android Cleartext Traffic

In Android API level 28 or above, an insecure HTTP connection is prohibited by default. If an HTTP URL is delivered during a conversation, the WebView embedded in the SDK cannot show the web page. The best way to resolve the issue is to deliver HTTPS URLs consistently. However, if your team needs to deliver an HTTP URL, change AndroidManifest.xml properties as follows:

<application
    ...
    android:usesCleartextTraffic="true">

🚧

Allowing all HTTP connections might cause a security issue. See Android official documentation about network security.

Using Channel.io

After initializing the SDK, you should boot the SDK to integrate it with your channel. You need your channel’s plugin key, and optionally a user profile and configurations. See how to get a plugin key.

Boot as an anonymous user

An anonymous user is a user that Channel cannot identify whom it is. If an anonymous user boot on a different device, past chat logs will not be shown. Boot as an anonymous user if you have no clue to identify a user. One possible use case is a user that haven’t signed in to your service.

BootConfig bootConfig = new BootConfig.create(YOUR_PLUGIN_KEY);

val bootConfig = BootConfig.create(YOUR_PLUGIN_KEY)

Boot as a member user

A user whom you have a clue to identify with, such as a user who is currently signed in to your service, is a member user. The Channel distinguishes a user by the memberId field which you can set by BootConfig#setMemberId().

❗️

Use member hash to protect the sensitive information of your users

If you set the memberId using predictable values such as user ID or email, an unauthorized third party might acquire your user’s memberId. The unauthorized access might allow the malicious third party to gain your user’s sensitive information, including mobile number and chat logs which can lead to a security breach. Enable member hash for your channel to improve the security level.

Profile profile = Profile.create()
    .setName(userName)
    .setEmail(userEmail)
    .setProperty("homepageUrl", "channel.io");

BootConfig bootConfig = BootConfig.create(YOUR_PLUGIN_KEY)
    .setMemberId(memberId)
    .setProfile(profile);

ChannelIO.boot(bootConfig);

val profile = Profile.create()
    .setName(userName)
    .setEmail(userEmail)
    .setProperty("homepageUrl", "channel.io")

val bootConfig = BootConfig.create(YOUR_PLUGIN_KEY)
    .setMemberId(memberId)
    .setProfile(profile)

ChannelIO.boot(bootConfig)

📘

The information of the same person can be unified

When booting as a member user from an anonymous user state, users can be unified into one if Channel finds a strong evidence that the two users are the same person. See unifying customer information for details.

Awaiting a boot result

Boot requires a network connection which might yield some random delay. If you have some tasks that should be done after the boot ends, BootCallback might be used.

ChannelIO.boot(bootConfig, new BootCallback() {
  @Override
  public void onComplete(BootStatus bootStatus, @Nullable User user) {
    // ...
  }
});

ChannelIO.boot(bootConfig) { bootStatus: BootStatus, user: User? ->
    // ...
}

See BootStatus for the full list of boot results.

Showing the Channel button

Channel Android SDK provides a default Channel button to allow users to easily contact your managers. Call ChannelIO.showChannelButton() to show the Channel button for all Activities that the user sees. When the button is no longer needed, call ChannelIO.hideChannelButton(). See the reference of ChannelIO.showChannelButton() and ChannelIO.hideChannelButton() for details.
If you want to change the button’s appearance, see how to customize the Channel button

Opt out of the SDK UI for specific Activity

If you want the SDK UI, such as the Channel button and in-app popups not to be shown in specific Activity, use @SkipAttachChannelView annotation on the Activity. The annotation will block SDK UI from being shown even if ChannelIO.showChannelButton() is called or a marketing message is sent.

@SkipAttachChannelView
public class SkipButtonActivity extends AppCompatActivity {
  // ...
}

@SkipAttachChannelView
class SkipButtonActivity : AppCompatActivity() {
    // ...
}

sleep

All features except event tracking and push notifications will stop working. Chat and marketing popups will not be shown.

ChannelIO.sleep();

ChannelIO.sleep()

shutdown

Completely terminates the SDK. Real-time chat, marketing, event tracking, and push notification stops working. To continue using the SDK features, you should boot again.
For instance, a service that uses SDK features only when a user has signed in to the service might no longer need to notify the user of a push notification for marketing or a manager’s reply. In this case, use ChannelIO.shutdown().

ChannelIO.shutdown();

ChannelIO.shutdown()