Android

Overview

The Instaply SDK allows to open a conversation over Instaply between your customer and a customer representative from inside your Android application.

Installation

The Instaply Android SDK is very easy to setup.

Open your global build.gradle. Add the following lines:

repositories {
    jcenter()
   maven {
           url  "https://nexus.instaply.com/repository/android"
   }
}

Add the following dependencies in your project build.gradle

android {
    ...
    dependencies {
        compile(group: 'android', name: 'instaply-sdk', version: '1.0.19', ext: 'aar')
    }
    ...
}

Necessary permissions

The SDK currently uses 3 permissions. 2 of those are required. WRITE_EXTERNAL_STORAGE is necessary for being able to send a photo.

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

This permission is optional but including it in the app will result in a better user experience when checking the availability of an internet connection:

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

If you want to use push notifications with the app, you will have to set up the next permissions too:

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

<permission android:name="APP_PACKAGE_NAME.permission.C2D_MESSAGE"
        android:protectionLevel="signature" />
<uses-permission android:name="APP_PACKAGE_NAME.permission.C2D_MESSAGE" />

APP_PACKAGE_NAME represents your application package name. For example bar.foo.app

Dependencies used by the Instaply SDK

The Instaply SDK uses the next 2 lines in its build.gradle. In case of classpath conflict, be sure to compare with the versions included in your project.

compile 'com.android.support:appcompat-v7:21.+'
compile 'com.google.code.gson:gson:2.+

Supported Android versions

The minimum supported Android version is API level 14.

Supported locales

The locale of the SDK is the locale as set by the app using the SDK. English, French and Swedish are currently available.

Usage

Initializing the SDK

Initializing the SDK is very simple and is preferably done on your Application subclass:

InstaplySharedAPI instaplySharedAPI = InstaplySharedAPI.sharedAPI(getApplication());

Authentication

First of all, you need to create an Authentication object that will contain all the necessary info for obtaining a token:Authentication auth = new Authentication(apiKey, nonce, digest, customerId, businessId, gcmRegId)

• apiKey represents your API key
• nonce represents your nonce that is used in computing your digest.
• digest is your computed digest, which represents a SHA1 hash of your API secret, nonce and customer ID.
• customerId is anything that can represent a customer. Like an email address or a telephone number.
• gcmRegId represents the device ID by Google Play Services. This is optional but required if you want to use push notifications in the app.

Second, you will have to pass the authentication to the authenticate method of the shared API object:instaplySharedAPI.authenticate(authentication,loginResponseHandler);

The loginResponseHandler implements the InstaplyAPILoginResponseHandler interface:

public static interface InstaplyAPILoginResponseHandler {
  public void onLoginSuccess(final InstaplySharedAPI instaplySharedAPI, final String token);
  public void onLoginFailed(InstaplySharedAPI instaplySharedAPI);
}

Upon authentication success, the onLoginSuccess method will be called. In the other case, onLoginFailed will be called.

Checking if a user was previously authenticated

It is not necessary to authenticate the user every time the SDK is used. The authentication, once successful, is stored. In order to check whether or not a user is authenticated, the instaplySharedAPI.isAuthenticated() can be called.

Handling token expiry

A token could expire and reauthentication, with updated parameters, could be required. In order to detect when authentication expires, a callback can be provided on the shared API object:

instaplySharedAPI.setOnAuthenticationExpiredCallback(new InstaplyAuthenticationExpiredCallback() {
   @Override
   public void onDisconnect() {
      // Your reconnect logic here
  }
});

Clearing the user

If you want to invalidate the token and clear all user data related to your user with the Instaply SDK, you can use:

instaplySharedAPI.getAccountManager().clearIdentity();

Opening a conversation

If you succeeded in the authentication step, you are almost ready to display the conversation. Here is how:

instaplySharedAPI.getUIManager()
  .activityTitle("Title")
  .activitySubtitle("Subtitle")
  .prefillMessage("Do you have ")
  .hint("Message...")
  .startConversationActivity(context);

• activityTitle sets the title of the conversation.
• activitySubtitle sets the subtitle of the conversation. Optional.
• prefillMessage prefills a message in the conversation. Optional.
• hint presets the hint for the message. Optional.
• startConversationActivity starts the conversation activity. You need to provide an Activity context to this method.

Getting the unread counter

Getting the unread counter is as easy as logging in. Once logged in, you can retrieve the amount of unread messages in a very similar way:

instaplySharedAPI.getUnreadCount(new InstaplySharedAPI.InstaplyAPIUnreadCountResponseHandler(){
  @Override
  public void onUnreadCountResponseReceived(InstaplySharedAPI instaplySharedAPI, int unreadCount) {
    // On success this is called
  } 

  @Override
  public void onUnreadCountResponseError(InstaplySharedAPI instaplySharedAPI) {
    // On failure this is called
  }
});

Metadata

In order to set the metadata of a user, you just need to provide a user to this method: instaplySharedAPI.getAccountManager().setUser(user);

A User can contain several elements. For example:

User user = new User();
user.setFirstName("John");
user.setLastName("Doe");
user.setEmail("john@doe.com");
user.setPhone("+33123456789");
user.setAdditionalField("my-business-client-id","23829");
user.setProfilePicture(bitmap);

Please note, the profile picture can be maximum 1024×1024. For memory efficiency reasons, the Instaply SDK does not resize the image.