Android SDK

Overview

The Instaply SDK opens a conversation between your customer and a representative inside your Android app.

Repository and dependency

In your root build.gradle / settings.gradle (depending on your Gradle setup), add the Instaply Maven repository. Legacy documentation used:

repositories {
    jcenter() // deprecated; migrate to mavenCentral or your mirror as appropriate
    maven {
        url "https://nexus.instaply.com/repository/android"
    }
}

Caution

jcenter() is end-of-life. Prefer mavenCentral() plus the Instaply Nexus URL, or follow whatever repository coordinates Instaply currently provides for your project.

In the module build.gradle, add the SDK artifact (version from legacy docs):

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

Confirm the current artifact coordinates and version with Instaply.

Permissions

Required / common

• INTERNET
• WRITE_EXTERNAL_STORAGE — needed to send a photo from the SDK

Optional (connectivity UX)

• ACCESS_NETWORK_STATE

Push (if used)

<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" />

Replace APP_PACKAGE_NAME with your application id (for example com.example.app).

Transitive dependencies

The SDK historically depended on:

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

Resolve any classpath conflicts against these versions (or their AndroidX equivalents if you migrate).

Supported versions

• Minimum Android API 14 (legacy doc)
• Locales: English, French, Swedish (locale follows the host app)

Usage

Initialize

Prefer your Application subclass:

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

Authenticate

Build an Authentication object:

Authentication auth = new Authentication(apiKey, nonce, digest, customerId, businessId, gcmRegId);
instaplySharedAPI.authenticate(auth, loginResponseHandler);

Argument	Meaning
apiKey	Your Instaply API token
nonce	Random nonce used to compute digest
digest	SHA1 verification token (see SDK authentication)
customerId	Stable customer identifier (email, phone, etc.)
businessId	Instaply business / store id
gcmRegId	FCM/GCM registration id — optional unless you use push

InstaplyAPILoginResponseHandler receives onLoginSuccess or onLoginFailed.

Session

• You do not need to authenticate on every use; after success, credentials are stored.
• instaplySharedAPI.isAuthenticated() checks state.
• instaplySharedAPI.setOnAuthenticationExpiredCallback(...) handles token expiry.
• instaplySharedAPI.getAccountManager().clearIdentity() clears the user and token.

Open conversation

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

Unread count

instaplySharedAPI.getUnreadCount(new InstaplySharedAPI.InstaplyAPIUnreadCountResponseHandler() {
    @Override
    public void onUnreadCountResponseReceived(InstaplySharedAPI api, int unreadCount) { }

    @Override
    public void onUnreadCountResponseError(InstaplySharedAPI api) { }
});

User metadata

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);
instaplySharedAPI.getAccountManager().setUser(user);

Profile pictures are limited to 1024×1024; the SDK does not resize images for you.