Quickstart

Channel Talk 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

Before installing the SDK, ensure the following conditions are met:

• Paid Channel Talk service plan
• Minimum installable Android API level 15 or higher
  • The minimum Android API level required for SDK to function is Android API level 21.
• Recommended Android Gradle Plugin 8.0.0 or higher
• sourceCompatibility, targetCompatibility 1.8 or higher
• The SDK is using Kotlin version 1.8.22. If you are using lower version of Kotlin, you may encounter issues with Gradle dependency resolution

Installation

Include Channel Talk SDK as a dependency.

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

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

repositories {
	mavenCentral()
}

Transitive Dependencies

While we try our best to prevent transitive dependency conflicts, such as changing package names, there may be cases where you need to resolve it manually by configuring Gradle. Please open a new chat if you encounter any issue related to the dependency resolution with 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 Talk

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 someone whom Channel cannot identify. If an anonymous user boot from a different device, past chat logs will not be accessible. Boot as an anonymous user if you have no way to identify a specific user. One common scenario is when a user that hasn'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 can identify, such as a user currently signed in to your service, can be boot as 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 random delays. If you have tasks that need to be done after the boot, 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 offers 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 wish to change the button’s appearance, see how to customize the Channel button

Opt out of the SDK UI for a 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()