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 app/build.gradle file.

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

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

  1. Import WebEngage packages in your Application class.
import com.webengage.sdk.android.WebEngageConfig;
import com.webengage.sdk.android.WebEngageActivityLifeCycleCallbacks;
  1. 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));

}

Make sure you replace YOUR_WEBENGAGE_LICENSE_CODE with your WebEngage license code

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: com.webengage.sdk.android.key
  • Depending on the data center, add one of the below meta-data under application tag of your AndroidManifest.xml file . Please note that, by default, your data is stored in our global data centers. Therefore, if you're not specifically using our India data center to store/access your data, please use the meta-data based on the Global data center.

Please Note
In your contract with WebEngage, if you have not specifically requested for your data to be stored in our India data center, then your data will be stored in our Global data center.
-
If your WebEngage dashboard URL starts with dashboard.webengage.com, then it means you're using our Global data center.
-
If your WebEngage dashboard URL starts with dashboard.in.webengage.com, then it means you're using our India data center.

Data Center
Tag

Global

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

  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 all of them.

3. Attribution tracking

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 {
    @Override
    public void onReceive(Context context, Intent intent) {
        WebEngage.get().analytics().installed(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, make it primary, and then call the immutable InstallReferrer and WebEngage's InstallReferrer from this new primary InstallReferrer.

Doing this is straightforward:
1. Set up a new InstallReferrer.
2. Declare it in AndroidManifest.xml.
3. Call the immutable InstallReferrer and WebEngage's InstallReferrer from the onReceive() of this new primary InstallReferrer.
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.

<receiver
  android:name="com.webengage.sdk.android.InstallTracker"
  android:exported="true">
  <intent-filter>
     <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

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, 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 duration between force kill and launch), the SDK will close the previous session upon force-kill and start a new session upon app launch.

Next steps

Congratulations! You have now successfully integrated WebEngage SDK with your Android app and are now sending user session and system event data to WebEngage.

Note that it may take a few minutes for your data to show up on the WebEngage dashboard. We suggest you meanwhile proceed to read the next sections to learn how to:

  1. Track user properties as attributes
  2. Track user actions as events
  3. Integrate push messaging
  4. Integrate in-app messaging

We recommend doing these integrations before releasing your app for the first time with WebEngage.

Updated about a month ago

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.