Android

This is for:

Developer

In this article, we’ll walk you through the steps for setting up the Coveo Experience Hub on your Android mobile apps in the ecommerce vertical.

Tip

Check out Coveo Qubit Android SDK on Github. This public repository provides the code to be installed and is the best place to keep up with the releases.

Adding dependencies

In build.gradle of your Android application module (usually $projectRoot/app/build.gradle) add the following in the dependencies section:

dependencies   {
    compile  'com.qubit:qubit-sdk-android:2.0.1'
}

Initialization

Provide application context and tracking ID. Log level is optional. See Logging for more information. Call start method to initialize the SDK. You might place this code in your Application file:

@Override
public void onCreate() {
    super.onCreate();

    QubitSDK.initialization()
        .inAppContext(this)
        .withTrackingId("YOUR_TRACKING_ID")
        .withLogLevel(QBLogLevel.DEBUG)
        .start();
}

Permissions

Coveo Qubit’s Android SDK needs the following permissions to communicate with the server and to detect network connectivity (they are added in library manifest):

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

You don’t have to add these permissions to the manifest of your application.

Sending events

QProtocol (QP) is Experience Hub’s industry-standard, extensible data layer. To send a QP event, call the sendEvent method taking QBEvent object as an argument, as shown in the following example.

In the example, we emit a standard ecView event, but you can modify this data to send any data you wish, based on the event schema:

QubitSDK.tracker().sendEvent(QBEvents.fromJsonString("ecView", viewJson));

Where:

  • viewJson takes the example form (this may vary depending on custom schema configuration):

{
    "type": "home",
    "subtypes": ["Women", "Dresses", "Cocktail Dresses"]
}

Creating events

QBEvents class provides several methods that allow you to create an event as QBEvent object.

From a json as String:

Example:

String jsonString = "{ \"type\" : \"home\" }";

QubitSDK.tracker().sendEvent(QBEvents.fromJsonString("ecView", jsonString));

From JsonObject:

Example:

JsonObject jsonObject = new JsonObject();
jsonObject.addProperty("type", "home");

QubitSDK.tracker().sendEvent(QBEvents.fromJson("ecView", jsonObject));

From Object:

Example:

public class EcViewEventData {
    private String type;

    // some code
}
EcViewEventData object = new EcViewEventData();
object.setType("home");

QubitSDK.tracker().sendEvent(QBEvents.fromObject("ecView", object));

Enabling and disabling tracking

To disable/enable message dispatch on event occurrence, use the following method:

QubitSDK.tracker().enable(false); // disable
QubitSDK.tracker().enable(true); // enable
Note

Tracking is enabled by default, so you don’t need to enable it if you’ve never disabled it anywhere.

Integrating experiences

Use getExperiences() to integrate Experiences into your app.

Kotlin snippet

QubitSDK.getExperiences(
    listOfExperienceIds,
    { experienceList -> experienceList.forEach { it.shown() } },
    { throwable -> Log.e(TAG, "Error: ", throwable) },
    222,
    false,
    true
)

Java snippet

QubitSDK.getExperiences(
    listOfExperienceIds,
    experienceList -> {
      for (Experience experience : experienceList) {
        experience.shown();
      }
      return Unit.INSTANCE;
    },
    throwable -> {
      Log.d(TAG, throwable.toString());
      return Unit.INSTANCE;
    }, 222, false, true
);

Where:

  • variation, preview, ignoreSegments are optional parameters.

Adding placements

Use getPlacement() to add Experience Hub Placements into your app.

Kotlin

QubitSDK.getPlacement(
    "83f6b528-9336-11eb-a8b3",
    PlacementMode.LIVE,
    PlacementPreviewOptions("1ybrhki9RvKWpA", "AUuQ_8z7SV-Fw"),
    { placement ->

        // get our payload
        placement?.content

        // send an impression event
        placement?.impression()

        // send a clickthrough event
        placement?.clickthrough()
    },
    { throwable -> Log.e(TAG, "Failed to fetch Placement", throwable) }
)

A Placement has two callbacks defined: impression and clickthrough. These can be invoked explicitly from Placement object:

placement.impression()
placement.clickthrough()

or through separate methods from QubitSDK, which expects URL to be requested:

QubitSDK.sendCallbackRequest(placement.impressionUrl)

Tracker properties

You can get the trackingID and deviceID from the QubitSDK via the following methods:

QubitSDK.getTrackingId();
QubitSDK.getDeviceId();

Logging

You can specify which level of logs from the SDK to print in Logcat during initialization. Refer to Initialization for details.

The default log level is WARN. You can turn off logs by setting SILENT log level.