Android SDK

The Smooch android SDK is a highly customizable chat embeddable that can be added to any Android app. It supports all the Smooch API capabilities, push notifications and is fully localized.

Current version: v

Reference

Smooch Android SDK includes a client side API to initialize, customize and enable advanced use cases of the SDK. See the Android API reference to discover all the classes and methods available.

Capabilities

Native Android SDK supports a wide variety of capabilities as seen in the channel capabilities grid. Below is a detailed view of each capabilities.

Content Types

  • Text

    Full SupportAPI
  • Image

    Full SupportAPI
  • File

    Full SupportAPI
  • Emoji

    Full SupportAPI
  • GIF

    Partial SupportAPI
  • Location

    Partial SupportAPI

Action Types

  • Link

    Full SupportAPI
  • Extension

    Full SupportAPI
  • Buy

    Full SupportAPI
  • Postback

    Full SupportAPI
  • Reply

    Full SupportAPI
  • Location Request

    Full SupportAPI

Structured Messages

  • Compound Message

    Full SupportAPI
  • Carousel

    Full SupportAPI

Indicators

  • Typing

    Full SupportAPI
  • Read

    Full SupportAPI
  • Conversation Start

    Full SupportAPI

Delivery Events

Delivery events allow you to track deliveries of Smooch messages to the Android SDK by subscribing to the message:delivery:channel webhook.

Carousels are rendered natively with full functionality in the Android SDK. See our API documentation for instructions on how to send one.

Carousel android

Carousels support up to a maximum of 10 message items. Each message item must include a title and at least one supported action. Optionally, an image and description can be included as well. Images can be displayed in two different aspect ratios, “square” and “horizontal”. For more information, see our API documentation.

Carousel items with “horizontal” images (default):

Carousel Android horizontal

Carousel items with “square” images:

Carousel Android square

Supported actions

The Android SDK supports the following action types in a carousel message item:

  • Link
  • Postback
  • Buy
  • Webview

List message fallback

If the Android SDK receives a list type message, it will display a carousel instead.

Files

The Android SDK has full native support for sending and receiving files. See our API documentation for instructions on how to send one.

Adding Smooch to your app

The Smooch library is distributed in both AAR and JAR format. If you are using Android Studio, follow the instructions for installation of the AAR package.

Android Studio with Gradle

Bintray

The Smooch library is hosted on Bintray and is available on JCenter.

Setup JCenter as a repository.

repositories {
    jcenter()
}

Add the dependencies right into your build.gradle file.

// See https://github.com/smooch/smooch-android to pin the latest version
compile 'io.smooch:core:5.+'
compile 'io.smooch:core:5.+'

Sync the Gradle project, then add the necessary code to initialize Smooch in your app.

Initialize Smooch in your app

After following the steps above, your app is set up for working with the Smooch SDK. Before your code can invoke its functionality, you’ll have to initialize the library using your app’s ID. This ID uniquely identifies your app and links it to the Smooch backend that does the heavy lifting necessary to bridge the gap between you and your users.

You can find your ID by logging into Smooch and copying it from the settings page as shown below.

App ID on Overview Page

Once you’ve located your ID, you can initialize Smooch in two different ways: from your Application class (suggested), or from an Activity class:

Initialize from your Application class

Add the following lines of code to your onCreate method on your Application class:

Smooch.init(this, new Settings("YOUR_APP_ID"), new SmoochCallback() {
    @Override
    public void run(Response response) {
        if (response.getError() == null) {
            // Your code after init is complete
        } else {
            // Something went wrong during initialization
        }
    }
});

If you don’t have an Application class, you must create one to make sure Smooch is always initialized properly. You can follow the instructions here.

Initialize from an Activity class

You can also initialize Smooch from an Activity. This is useful if you don’t know your Smooch app ID at app launch or if you want to run many Smooch apps in the same Android app.

Add the following line of code to your onCreate method on your Application class:

Smooch.init(this);

If you don’t have an Application class, you must create one to make sure Smooch is always initialized properly. You can follow the instructions here.

Add the following line of code where you want to initialize Smooch in your Activity class:

Smooch.init(this, new Settings("YOUR_APP_ID"), new SmoochCallback() {
    @Override
    public void run(Response response) {
        if (response.getError() == null) {
            // Your code after init is complete
        } else {
            // Something went wrong during initialization
        }
    }
});

For example, to initialize Smooch when a button is tapped, you can do the following:

package your.package;

import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.view.View;
import android.widget.Button;

import io.smooch.core.Settings;
import io.smooch.core.Smooch;
import io.smooch.core.SmoochCallback;
import io.smooch.ui.ConversationActivity;

public class YourActivity extends AppCompatActivity implements View.OnClickListener {
    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        Button showConversationActivityButton = findViewById(R.id.button_show_conversation_activity);
        showConversationActivityButton.setOnClickListener(this);
    }

    public void onClick(View v) {
        final int id = v.getId();

        if (id == R.id.button_show_conversation_activity) {
            Smooch.init(getApplication(), new Settings("YOUR_APP_ID"), new SmoochCallback() {
                @Override
                public void run(Response response) {
                    if (response.getError() == null) {
                        ConversationActivity.show(getApplicationContext());
                    } else {
                        // Something went wrong during initialization
                    }
                }
            });

        }
    }
}

If you initialize Smooch from an Activity, you’ll need to handle initialization when receiving a push notification. To do so, override the activity that is opened when tapping a notification and initialize Smooch before opening ConversationActivity. For example:

package your.package;

import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;

import io.smooch.core.Settings;
import io.smooch.core.Smooch;
import io.smooch.core.SmoochCallback;
import io.smooch.ui.ConversationActivity;

public class YourNotificationHandlerActivity extends AppCompatActivity {
    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Smooch.init(getApplication(), new Settings("YOUR_APP_ID"), new SmoochCallback() {
            @Override
            public void run(Response response) {
                if (response.getError() == null) {
                    ConversationActivity.show(getApplicationContext());
                } else {
                    // Something went wrong during initialization
                }
            }
        });
    }
}

Adding an Application class to your app

If you don’t have an Application class in your app, you can copy the following and save it to your application package.

package your.package;

import android.app.Application;

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Initialize Smooch here
    }
}

You also need to declare your newly created Application class in the <application> tag in your AndroidManifest.

<application
    android:name="your.package.YourApplication">
    ...
</application>

Displaying the Smooch User Interface

Once you’ve initialized Smooch, you’re ready to try it out.

Find a suitable place in your app’s interface to invoke Smooch and use the code below to display the Smooch user interface. You can bring up Smooch whenever you think that your user will need access to help or a communication channel to contact you.

ConversationActivity.show(this);

You should also take the time to configure the push notifications setup.

Replacing the Smooch FileProvider

In order to replace the Smooch FileProvider with your own, please do the following:

  1. Add tools:replace="android:authorities" to the <provider> entry.

  2. Add the following path to your android.support.FILE_PROVIDER_PATHS resource file:

<external-path name="dcim" path="DCIM"/>
  1. When initializing Smooch, call settings.setFileProviderAuthorities(authoritiesString); on the settings object.
Settings settings = new Settings(appId);
settings.setFileProviderAuthorities(authoritiesString);
Smooch.init(this, settings, myInitCallback);

Region configuration

The Android SDK is supported in the following regions:

NameRegion identifier
United StatesLeave unspecified
European Unioneu-1

To target the EU region for example, set the region identifier with Settings.setRegion():

Settings settings = new Settings("YOUR_APP_ID");
settings.setRegion("eu-1");
Smooch.init(this, settings, new SmoochCallback() {
    @Override
    public void run(Response response) {
        if (response.getError() == null) {
            // Your code after init is complete
        } else {
            // Something went wrong during initialization
        }
    }
});

Log in with userId and JWT

After Smooch has initialized, your user can start sending messages right away. These messages will show up on the business side under a new Smooch appUser. However, these appUsers will not yet be associated to any user record you might have in an existing user directory.

If your application has a login flow, or if a user needs to access the same conversation from multiple devices, this is where the login method comes into play. You can associate Smooch users with your own user directory by assigning them a userId. You will then issue each user a jwt credential during the login flow. You can read more about this in the Authenticating users section.

Configuring push notifications

Push notifications are a great, unobtrusive way to let your users know that a reply to their message has arrived.

Step 1. Generate a FCM configuration file for your Android project

  1. Go to Google’s Firebase console.

  2. If you do not have a project already, create a new one.

  3. Once created, click on “Add Firebase to your Android app” and follow the instructions to generate your google-services.json file (for your package name, copy and paste the package used in your application’s AndroidManifest.xml file).

  4. Save the google-services.json file generated by the tool at the root of your Android application (<project>/<app-module>/google-services.json).

  5. Follow the Gradle instructions and modify your build.gradle files accordingly:

    1. Project-level build.gradle (<project>/build.gradle):
    buildscript {
        dependencies {
            // Add this line
            classpath 'com.google.gms:google-services:3.2.0'
        }
    }
    1. App-level build.gradle (<project>/<app-module>/build.gradle):
    dependencies {
        // Add this line
        compile 'com.google.firebase:firebase-core:12.0.1'
    }
    ...
    // Add to the bottom of the file
    apply plugin: 'com.google.gms.google-services'
    1. Press Sync now in the bar that appears in the IDE.

Step 2. Configure push notifications in Smooch

  1. Go to the Android integration page.

  2. Click on the Connect or Configure button.

  3. Enter your Server API Key and Sender ID (these can be retrieved by clicking on the cogwheel (Settings) next to Project Overview on the sidebar, then clicking on the CLOUD MESSAGING tab).

Step 3. Test it out!

  1. Kill and restart your app.

  2. Launch Smooch.

  3. Send a message.

  4. Press the home button or navigate away from the conversation.

  5. Reply to the message from your choice of Smooch integrated service.

You’ll receive a notification on the phone!

Localization

Every string you see in Smooch can be customized and localized. Smooch provides a few languages out of the box, but adding new languages is easy to do. When localizing strings, Smooch looks for values in the strings.xml in your app first then in the Smooch ui bundle, enabling you to customize any strings and add support for other languages.

Adding more languages

To enable other languages beside the provided ones, first copy the english strings.xml file from the Smooch ui bundle to the corresponding values folder for that language. Then, translate the values to match that language.

Customization

Strings customization

Smooch lets you customize any strings it displays by overwriting its keys. In order to do so, simply add res/values-<your-language-code>/strings.xml file in your Android project and specify new values for the keys used in Smooch. You can find all available keys by browsing to the ui-x.x.x/res/values/values.xml file in the External Libraries in Android Studio.

Dates shown in the conversation view are already localized to the user’s device.

For example, if you wanted to override strings for English, you would create a file res/values-en/strings.xml and include the following in that file:

<resources>
    <string name="Smooch_activityConversation">Messages</string>
    <string name="Smooch_startOfConversation">This is the start of your conversation with the team.</string>
    <string name="Smooch_welcome">Feel free to leave us a message about anything that\'s on your mind.</string>
    <string name="Smooch_messageHint">Type a message…</string>
</resources>

Styling the Conversation Interface

Using a colors.xml file in your res/values folder, you can change the colors used by Smooch:

<resources>
    <color name="Smooch_accent">#9200aa</color>
    <color name="Smooch_accentDark">#76008a</color>
    <color name="Smooch_accentLight">#be7cca</color>

    <color name="Smooch_backgroundInput">#ffffff</color>

    <color name="Smooch_btnSendHollow">#c0c0c0</color>
    <color name="Smooch_btnSendHollowBorder">#303030</color>

    <color name="Smooch_header">#989898</color>

    <color name="Smooch_messageDate">@color/Smooch_header</color>
    <color name="Smooch_messageShadow">#7f999999</color>

    <color name="Smooch_remoteMessageAuthor">@color/Smooch_header</color>
    <color name="Smooch_remoteMessageBackground">#ffffff</color>
    <color name="Smooch_remoteMessageBorder">#d9d9d9</color>
    <color name="Smooch_remoteMessageText">#000000</color>

    <color name="Smooch_userMessageBackground">@color/Smooch_accent</color>
    <color name="Smooch_userMessageBorder">@color/Smooch_accentDark</color>
    <color name="Smooch_userMessageFailedBackground">@color/Smooch_accentLight</color>
    <color name="Smooch_userMessageText">#ffffff</color>
</resources>

If you need to update the image of the Send button, simply add an image with the following name to your drawables:

smooch_btn_send_normal.png

You can find the original resources by browsing external libraries through Android Studio.

The Android SDK features a tappable menu icon that allows the user to send various message types. The types displayed in this menu can be customized, or the menu can be hidden altogether.

If you want to control this menu, simply override the following resource in settings.xml to the value of your choice:

<string-array name="Smooch_settings_showMenuOptions" type="array">
    <item>@string/Smooch_settings_takePhotoMenuKey</item>
    <item>@string/Smooch_settings_chooseMediaMenuKey</item>
    <item>@string/Smooch_settings_uploadFileMenuKey</item>
    <item>@string/Smooch_settings_shareLocationMenuKey</item>
</string-array>

Menu Options

To hide the menu completely, override the resource as follows:

<string-array name="Smooch_settings_showMenuOptions" type="array"/>

Menu Options

Notification Action Intent Override

The default behavior of tapping on a push or in-app notification is to open the Smooch ConversationActivity intent. If you want to change this behavior, simply override the following resource in settings.xml to the value of your choice:

<resources>
  <string name="Smooch_settings_notificationIntent">io.smooch.ui.ConversationActivity</string>
</resources>

Notification Channel Settings Override

Apps targeting Android Oreo (SDK 26) or higher will have push notifications delivered to a notification channel. If you wish to override the channel settings for Smooch notifications, set the following resources in settings.xml to the values of your choice:

<resources>
  <string name="Smooch_settings_notificationChannelId">your_channel_id</string>
  <string name="Smooch_settings_notificationChannelName">Your Channel Name</string>
</resources>

Starting Text

Smooch allows to you to prefill the text box in the conversation when opening it. To do so, simply supply a startingText string when calling ConversationActivity.show:

ConversationActivity.show(this, "Hi there! Can you help me please?");

Extending ConversationActivity

In some cases it may be desirable to use your own custom ConversationActivity in place of the one provided by Smooch. One such case is if you want to modify or remove the action bar. This can be achieved if you extend the Smooch ConversationActivity.

To do so, do the following:

  1. Create a new activity that extends ConversationActivity
  2. Add the Smooch theme to your activity in your AndroidManifest.xml file (or create one which specifies <item name="android:windowActionBarOverlay">true</item>)

At this point, your Activity should look something like this:

package your.package;

import android.os.Bundle;

import io.smooch.ui.ConversationActivity;

public class CustomConversationActivity extends ConversationActivity {
    @Override
    protected void onCreate(final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setTitle("Whatever You Want");
        getSupportActionBar().setDisplayHomeAsUpEnabled(false);
    }
}

And your manifest should look something like this:

<activity
    android:name="your.package.CustomConversationActivity"
    android:theme="@style/Theme.Smooch" />
  1. When showing Smooch in your Android code, instead of calling ConversationActivity.show(this), call startActivity(new Intent(this, CustomConversationActivity.class));

  2. To ensure the correct activity is launched when a notififcation is tapped, override the setting Smooch_settings_notificationIntent to provide the full path of your new activity

ex: <string name="Smooch_settings_notificationIntent"><your.package.CustomConversationActivity</string>

Implementing your own User Interface

If you need more customization options than the ones supported natively by Smooch, you can implement a complete custom UI by leveraging events and APIs exposed by the SDK, which will continue to facilitate the connection with the Smooch platform.

Our sample custom UI project covers the first steps you need to follow to get started.

Permissions

The Smooch library includes the following permissions by default:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
  • WRITE_EXTERNAL_STORAGE is used to take photos and to store downloaded pictures locally to avoid needless re-downloading.
  • ACCESS_FINE_LOCATION is used in order to access the customer’s location when requested using location request buttons.

If you do not intend to request the user’s location at any point, it is safe to remove the ACCESS_FINE_LOCATION using the following override:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove" />

All other permissions are necessary for Smooch to function as intended.