Getting Started

1. Installation

The easiest way to use WebEngage in your Android project is with Maven. WebEngage Android SDK is hosted on jcenter Maven repository.

Add dependencies of WebEngage and Google Play Service Ads in the app/build.gradle file.

dependencies {
  implementation 'com.webengage:android-sdk:3.+'
  implementation 'com.google.android.gms:play-services-ads:15.0.1'
}

🚧

Please Note

Adding the Google Play Service Ads dependency is optional. Use it only if you have integrations enabled with other attribution partners.

After application build, WebEngage SDK size is around 150kB if minifyEnabled is set to false. The size will be less than 150kB if minifyEnabled is set to true.

2. Initialization

Step 1: Import WebEngage packages in your Application class.

import com.webengage.sdk.android.WebEngageConfig;
import com.webengage.sdk.android.WebEngageActivityLifeCycleCallbacks;

Step 2: Initialize WebEngage SDK with your license code from onCreate callback of your Application class as shown below.

@Override
public void onCreate() {
  super.onCreate();
  WebEngageConfig webEngageConfig = new WebEngageConfig.Builder()
              .setWebEngageKey(YOUR_WEBENGAGE_LICENSE_CODE)
              .setDebugMode(true) // only in development mode
              .build();
  registerActivityLifecycleCallbacks(new WebEngageActivityLifeCycleCallbacks(this, webEngageConfig));

}

Please replace YOUR_WEBENGAGE_LICENSE_CODE with your WebEngage license code in the code snippets provided above.

Locating your WebEngage license code

As shown above, navigate to the Account Setup section to find your license code.

  • Your License Code might start with tilde (~).
  • It is the value of manifest key: com.webengage.sdk.android.key.

Step 3: Add meta-data under in the AndroidManifest.xml file

🚧

IMPORTANT: Identifying Your Data Center

  • If your WebEngage dashboard URL starts with dashboard.webengage.com, then it means you're using our Global Data Center. (All data is stored here by default).

  • If you have specifically asked for your data to be stored in our India Data Center in your contract with WebEngage, then your dashboard url will start with dashboard.in.webengage.com.

Thus, depending on your data center, add the appropriate meta-data under the application tag of your AndroidManifest.xml file:

Data Center

Meta Data Tag

Global (US)

<meta-data android:name="com.webengage.sdk.android.environment" android:value="us" />

India

<meta-data android:name="com.webengage.sdk.android.environment" android:value="in" />

🚧

Please Note

  1. If you support Android API level less than 14 then use alternative initialization instead of the above approach.

  2. If you have multiple apps, you can use the same license code for integrating all of them.

Step 4: Disable automatic backup inside the 1application1 tag in your AndroidManifest.xml file.

<application
        ...
        android:allowBackup="false"
        ....
                >

If your application needs allowBackup to be set as true, then follow the steps below:

a. Create backup rules inside res/xml folder (res/xml/my_backup_rules.xml)

<?xml version="1.0" encoding="utf-8"?>
    <full-backup-content>
        <exclude domain="sharedpref" path="webengage_prefs.txt.xml" />
        <exclude domain="sharedpref" path="webengage_volatile_prefs.txt.xml" />
        <exclude domain="database" path="event_data.db" />
        <exclude domain="database" path="http_data.db" />
        <exclude domain="database" path="user_data.db" />
        <exclude domain="file" path="we_http_cache" />

b. Add backup file inside application tag in your AndroidManifest.xml

<application
        ...
        android:allowBackup="true"
         android:fullBackupContent="@xml/my_backup_rules">

3. Attribution Tracking

Add the following library in your app/build.gradle file (ensure that the SDK version being used is >= 3.16.0):

dependencies {
  implementation 'com.android.installreferrer:installreferrer:1.1.1'
}

🚧

Please Note

App Installed event and First Acquisition Details data in user profile will not be tracked on your Android app unless you follow the above step.

4. Additional steps (Optional)

If you are using WebViews in your Android app, check out WebEngage JavaScript bridge.

For other integration options such as location tracking, please refer to the Advanced section.

Session Lifecycle

WebEngage SDK automatically starts tracking user data (e.g., device model, OS version, device IDs) and engagement with the basic setup above. This data is stored on the device and is periodically uploaded in batches to reduce network and power usage, and to increase the likelihood of successful uploads. The upload cycle is based on the number of datapoints in local database and last synced time. This local database size is capped and is deleted as soon as it is successfully uploaded. WebEngage allows you to change this upload behavior during runtime, so that you can make events sync faster to WebEngage if available network connectivity is good.

WebEngage SDK also starts tracking user sessions with this basic setup. Upon app backgrounding, the SDK marks the current time. If the user returns to the app after more than 15 seconds since the user had last backgrounded the app, the SDK will close the previous session. If the user foregrounds the app within 15 seconds of the previous backgrounding, the previous session is resumed as if the user did not leave the app at all. Also, if the user force kills the app and launches it again after being force killed (irrespective of the time gap between force kill and launch), the SDK will close the previous session upon force-kill and start a new session upon app launch.

🚧

Congratulations!

You have now successfully integrated the WebEngage SDK with your Android app and are sending user session and system events data to your dashboard. Please note that it may take up to a few minutes for your data to reflect on the dashboard.

Please feel free to drop in a few lines at [email protected] in case you have any further queries. We're always just an email away!

Updated 4 months ago


So, what's next?

We recommend that you implement the following integrations before releasing your app for the first time with WebEngage.

Track User Properties as User Attributes
Track User Actions as Events
Configure Push Messaging
Configure In-app Messaging

Getting Started


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.