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 ''

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.


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

public void onCreate() {
  WebEngageConfig webEngageConfig = new WebEngageConfig.Builder()
              .setDebugMode(true) // only in development mode
  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

Locating your WebEngage license code

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

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

Step 3: Depending on your data center, add one of the below meta-data under application tag of your AndroidManifest.xml file.

  • If your WebEngage dashboard URL starts with, 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

Data Center


<meta-data android:name="" android:value="us" />


<meta-data android:name="" 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 application tag in your AndroidManifest.xml.


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


3. Attribution Tracking

Please Note

App Installed event will not be tracked on your Android app unless you follow the steps mentioned in this section.

Android only supports one BroadcastReceiver for the INSTALL_REFERRER IntentFilter. If your app or another SDK in your app is already listening for the INSTALL_REFERRER IntentFilter to track user acquisition source on Android, follow the below instructions for using WebEngage in addition to other attribution providers.

Pass the Intent broadcast received in the BroadcastReceiver of your primary InstallReferrer to onReceive() of WebEngage's InstallReferrer. This is illustrated below.

public class PrimaryInstallTracker extends BroadcastReceiver {
    public void onReceive(Context context, Intent intent) {

In case the primary InstallReferrer is part of some library, or there is some other issue that prevents you from modifying the existing InstallReferrer, you can set up a new InstallReferrer. You can make it the primary file, and call the immutable InstallReferrer and WebEngage's InstallReferrer from this new primary InstallReferrer.

Here's how you can go about it:

Step 1: Set up a new InstallReferrer.

Step 2: Declare it in AndroidManifest.xml.

Step 3: Call the immutable InstallReferrer and WebEngage's InstallReferrer from the onReceive() of this new primary InstallReferrer.

Step 4: Call other InstallReferrers if you are using more attribution trackers.

Alternatively, if you don't have any other primary install referrer tracker and want to make WebEngage as the primary one, add the below receiver tag inside the application tag of your AndroidManifest.xml file.

     <action android:name="" />

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.


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 2 days 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.