Native Android SDK

Reference

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.

compile 'io.smooch:core:latest.release'
compile 'io.smooch:ui:latest.release'

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 setup for working with the Smooch SDK. Before your code can invoke its functionality, you’ll have to initialize the library using your app’s token.

This token is free and 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 token by logging into Smooch and copying it from the settings page as shown below.

App Token on Overview Page

Once you’ve located your token, use the code below to initialize Smooch.

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

Smooch.init(this, "YOUR_APP_TOKEN");

If you don’t have an Application class, we recommend that you create one to make sure Smooch is always initialized properly. If you don’t have one, you can copy the following and save it to your application package.

package your.package;

import android.app.Application;
import io.smooch.core.Smooch;

public class YourApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Smooch.init(this, "YOUR_APP_TOKEN");
    }
}

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(appToken);
settings.setFileProviderAuthorities(authoritiesString);
Smooch.init(this, settings);

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

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 going to Manage for your app and heading to the CLOUD MESSAGING section)

Step 3. Configure Android application to accept push

  1. Add the dependency to your project’s top-level build.gradle:

    classpath 'com.google.gms:google-services:3.0.0'

  2. Add the plugin to the bottom of your app-level build.gradle:

    apply plugin: 'com.google.gms.google-services'

Step 4. 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.

If you translate Smooch’s strings to a language not currently supported, we encourage you to share it with us so that every Smooch user can benefit from it. You can do so by forking our GitHub repo and creating a pull request, or just send us your string file at help@smooch.io

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.

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>

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.