Usage

Initialize

You may initialize the library any time during the life of your application. To make available it any time, we recommend putting the call inside the onCreate method of your application class. You can create credentials for use in your application in the settings section of the Chatvisor application.

The initialize case looks like this:

import com.chatvisor.android.Chatvisor;
import com.chatvisor.android.ChatvisorBase.CustomConfiguration;

public class TestApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        CustomConfiguration config = new CustomConfiguration(
                "<your user id>",
                "<your token>",
                "<should session sharing be enabled>");
        Chatvisor.init(config);

        // Or use: Chatvisor.init("<your user id>", "<your token>"), but this method is depricated and session sharing is disabled

    }
}

If you have an on-premise installation and want to initialize with custom settings you may follow this example:

import com.chatvisor.android.Chatvisor;
import com.chatvisor.android.ChatvisorBase.CustomConfiguration;

public class TestApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        CustomConfiguration config = new CustomConfiguration(
                "<your user id>",
                "<your token>",
                "<your server hostname>",
                "<your cdn server hostname>",
                "<should session sharing be enabled",
                "<context of your application>",
                "<overlayBackgroundColor(optional)>",
                "<controlsColor(optional)>");
        Chatvisor.init(config);
    }
}

Permissions

By default the Gradle build merges all manifest files into a single manifest which gets added to your final app. If you do not use Gradle or you explicitly disabled the merge, then add the following permissions to your manifest file:

  • android.permission.INTERNET

If you want to use session sharing for cobrowsing you need also to add the following permission in your manifest file:

  • com.chatvisor.android.liveview.sessionSharing.PERMISSION_FOR_SHARING_SESSION

Liveview

Enables the liveview feature. As soon as start() is called it sends the currently displayed screen to the server until stop() is called or the liveview is cancelled from server side.

ResultCallback<String>() callback = new ResultCallback<String>() { ... }
Chatvisor.liveView.start(callback); // or Chatvisor.liveView.start(), but this method is depricated

SharedSession for Cobrowsing

By default sharing a session for cobrowsing is disabled. In order to enable it the param sharing inside the ChatvisorBase.CustomConfiguration() must true. Additionaly, every app that wants to participate in the shared session needs to have these lines in their manifest:

...

    <uses-permission android:name="com.chatvisor.android.liveview.sessionSharing.PERMISSION_FOR_SHARING_SESSION" /> 

    ...

        <!-- Each app that wants to share a session needs to be registerd using the <proivder> tag, 
        where as the authorities is always the app's "package name".SharedSessionProvider -->
     <queries>
        <provider
            android:authorities="app.that.wants.the.session.should.be.shared.with.SharedSessionProvider" /> 
    </queries>

Also before calling Chatvisor.coBrowsing.start() the shared session must be setup via

     ArrayList<String> list = ArrayList<String>()
        list.add("app.that.wants.the.session.should.be.shared.with")
        ChatvisorBase.coBrowsing.setUpSharedSession(
            list,
            "my.own.app.package.name"
        )

IMPORTANT - Please note that all apps that want to share a session need to be signed with the same key as a security measure.

User tagging

Users can be tagged using the Chatvisor.user.tag method. This usually happens when a user executes a login. It expects an object of type ActiveUser that takes the same arguments as the JavaScript API method. All fields are optional.

ResultCallback<String>() callback = new ResultCallback<String>() { ... }
List<String> labels = new ArrayList<String>();
labels.put("foo")

Chatvisor.user.tag(  // or Chatvisor.user.tag(new ActiveUser), but this method is depricated
    new ActiveUser()
        .widthId("john.doe")
        .withEmail("john.doe@example.com")
        .withFirstname("John")
        .withLastname("Doe")
        .withLabels(labels)
, callback);

In case a value is passed in the id field, a new user object will be created in the backend and associated to this session. Also the session will be tagged with the id value.

If a user logs out of an account it is recommended to call Chatvisor.user.clear() to remove the tag from the session. This also stops the LiveView session.

ConferenceProperties

ConferenceProperties are used to start, join or gather queue status information about the Chatvisor.conference. All fields are optional but can be set in order to provide user information about who is starting or joining the conference.

new ConferenceProperties()
    .widthCustomerId("john.doe")
    .withFirstname("John")
    .withLastname("Doe")
    .withDisplayName("John Doe")
    .withEmail("john.doe@example.com")
    .withPhoneNumber("+123 456 789")

Setup chat notifications

When chat notifications are set up a user can receive push notifications when a chat message arrives as soon as the user is tagged.

If you have an on-premise installation, you need your own Firebase project for sending chat notifications. See the official documentation on how to set up a free Firebase project for Android. IMPORTANT: Type the bundle identifier all lowercase! You do not have to follow the whole process, you just need the GoogleService-Info.plist file.

Additionally, set

application:
    ...
    firebase-cloud-messaging:
        project_id: {project id}
        private_key_id: {private key id}
        private_key: {private key without header, footer and newlines}
        client_email: {client email}
        client_id: {client id}
        token_uri: {token uri}

in the application.yml of your server. You can find all necessaray data in the private key file (JSON) you can generate for a Google service account (See the official documentation). This service account just needs the permission "firebase.messaging" for sending notifications.

Call Chatvisor.init(...).withNotifications(Context context) in the onCreate method of your MainActivity.

If you have an on-premise installation you have to use .withNotifications(Context context, String projectId, String applicationId, String apiKey, String senderId) and provide the data from your custom google-services.json file.

If you are not using Firebase Messaging except for the chatvisor chat you can stop here. Everything is set up.

If you are already using Firebase Messaging and therefore have a service extending com.google.firebase.messaging.FirebaseMessagingService you have to complete the following steps:

Since the Intent on a new notification can only start one service you have to forward relevant Firebase messages to the Chatvisor SDK. For this you have to forward onMessageReceived(RemoteMessage remoteMessage) and onNewToken(String token) calls to a ChatvisorNotificationService (Example below).

Additionally, add the following entry in your AndroidManifest.xml in the <application> tag to disable the Chatvisor FirebaseMessagingService:

<service android:name="com.chatvisor.android.chat.ChatMessagingService" tools:node="remove"/>

(For this the namespace declaration xmlns:tools="http://schemas.android.com/tools" is required in the <manifest> tag)

Example FirebaseMessagingService:


/**
 * An example FirebaseMessagingService class that calls onMessageReceived(...) and onNewToken(...)
 * of ChatvisorNotificationService.
 */
public class ExampleFirebaseMessagingService extends com.google.firebase.messaging.FirebaseMessagingService {

    private ChatvisorNotificationService mChatvisorNotificationService = new ChatvisorNotificationService();

    /**
     * Call ChatvisorNotificationService.onMessageReceived(...) with the received message if
     * the message is from chatvisor (this can be checked by comparing the collapse key).
     *
     * @param remoteMessage the received RemoteMessage
     */
    @Override
    public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
        Log.d("ExampleFirebaseMService", "We got a new message: " + remoteMessage.getCollapseKey());
        if (ChatvisorNotificationService.COLLAPSE_KEY.equals(remoteMessage.getCollapseKey())) {
            mChatvisorNotificationService.onMessageReceived(this, remoteMessage);
        } else {
            // handle your messages
        }
        super.onMessageReceived(remoteMessage);
    }

    /**
     * Call ChatvisorNotificationService.onNewToken(...) with the new token.
     *
     * @param token new FirebaseMessaging device token.
     */
    @Override
    public void onNewToken(@NonNull String token) {
        mChatvisorNotificationService.onNewToken(token);
        super.onNewToken(token);
    }
}

Credentials

You can create credentials for use in your application in the settings section of the Chatvisor application.

← InstallationReference →