Android SDK Quick Start Guide

Learn how to quickly integrate and start using the CleverTap Android SDK.

Overview

This section shows how to install the CleverTap SDK, track your first user event, and see this information within the CleverTap dashboard in less than ten minutes. CleverTap provides an Android SDK that enables app developers to track, segment, and engage their users.

Install SDK

To use the CleverTap Android SDK, you have two options. You can install it automatically using Gradle in Android Studio or manually install it by including the SDK source code in your Android Studio project.

Option A: Install using Android Studio and Gradle (Recommended)

  1. For FCM, add the dependencies below in your application's build.gradle file. You will also have to add the FCM generated google-services.json file to your project.

  2. Add the following configuration to your gradle properties file.

dependencies {
    implementation 'com.clevertap.android:clevertap-android-sdk:4.5.0'
    implementation 'com.google.firebase:firebase-messaging:21.0.0'
        implementation 'androidx.core:core:1.3.0'
  //Mandatory for CleverTap Android SDK v3.6.4 and above add the following -
        implementation 'com.android.installreferrer:installreferrer:2.2'
}
// at the end of the build.gradle file
apply plugin: 'com.google.gms.google-services'
  1. Once you have updated your build.gradle file, sync your project by clicking on Sync Project With Gradle Files button.

Option B: Manual Install

For a manual install, follow these steps:

  1. Download this AAR file.
  2. Copy the AAR file to your project's /libs directory.
  3. Add it as a dependency to your project.

Add Your CleverTap Credentials in AndroidManifest.xml

To associate your Android app with your CleverTap account, you need to add your CleverTap credentials in the AndroidManifest.xml file in your application.

  1. Navigate to the AndroidManifest.xml file in your project navigator.
  1. Add your CleverTap Account ID and Token to your AndroidManifest.xml within the tags.
<meta-data
    android:name="CLEVERTAP_ACCOUNT_ID"
    android:value="Your CleverTap Account ID"/>
<meta-data
    android:name="CLEVERTAP_TOKEN"
    android:value="Your CleverTap Account Token"/>
<!-- IMPORTANT: To force use Google AD ID to uniquely identify  users, use the following meta tag. GDPR mandates that if you are using this tag, there is prominent disclousure to your end customer in their application. Read more about GDPR here - https://clevertap.com/blog/in-preparation-of-gdpr-compliance/ -->
<meta-data
    android:name="CLEVERTAP_USE_GOOGLE_AD_ID"
    android:value="1"/>

🚧

Using Google AD ID to uniquely identify users

GDPR mandates that if you use Google AD ID to identify users uniquely, there should be prominent disclosure in your application that explains this to your end customer. Refer to this GDPR article.

Note: If you still want to use Google AD ID to generate a user's identity so that you can identify users across re-installs, add the meta tag that forces the use of the Google AD ID to generate an identity in CleverTap.

  1. Insert the account (Project) ID and account token values from your CleverTap account. These values are available on the Settings page at the bottom left-hand corner of your dashboard. Click Project.

Add Region Code

Refer to the following table to identify the region for your account:

To enable the CleverTap Region, complete the following step. Add the following snippet according to your location in your AndroidManifest.xml file between the tags.

<meta-data 
android:name="CLEVERTAP_REGION" 
android:value="in1"/>
<meta-data 
android:name="CLEVERTAP_REGION" 
android:value="us1"/>
<meta-data 
android:name="CLEVERTAP_REGION" 
android:value="sg1"/>
<meta-data 
android:name="CLEVERTAP_REGION" 
android:value="sk1"/>

For more information on adding region codes for OS, channels, and APIs, refer to Region Codes.

Enable Tracking by Adding Permissions

Option A: No Application Class

You can add CleverTap's class as your application class to capture system events correctly.

To enable tracking by adding permissions with the following steps:

  1. In your AndroidManifest.xml file, add the following snippet within the tags.
<application
    android:label="@string/app_name"
    android:icon="@drawable/ic_launcher"
    android:name="com.clevertap.android.sdk.Application">
  1. Next, add the snippet below in the same file so that the CleverTap SDK can access the internet.
<!-- Required to allow the app to send events and user profile information -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- Recommended so that CleverTap knows when to attempt a network call -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Option B: Custom Application Class

If you have a custom application class, call ActivityLifecycleCallback.register(this); before super.onCreate() in your class.

Initialize the CleverTap SDK

Include the code below in the onCreate() method of your application's main activity. This code initializes the CleverTap SDK.

CleverTapAPI clevertapDefaultInstance = CleverTapAPI.getDefaultInstance(getApplicationContext());
var cleverTapDefaultInstance: CleverTapAPI? = null
cleverTapDefaultInstance = CleverTapAPI.getDefaultInstance(applicationContext)

Verify Integration

To check if the integration was performed correctly, you can run the application.

After the application is launched on the emulator or Android device, navigate to your CleverTap dashboard > Boards > Mobile App. You will see a new active user if you successfully integrated the CleverTap SDK.

Identify Users

A user profile is automatically created in CleverTap for each user launching your application.

Initially, the user profile starts as anonymous, which means the profile does not contain any identifiable information about the user. You can enrich the profile with pre-defined attributes from the CleverTap data model, such as name and email. You can also add custom attributes that you define to extend the CleverTap data model.

Sending user profile information to CleverTap using our Android SDK requires two steps:

  1. You have to build a HashMap with the profile properties.
  2. You have to call the SDK's OnUserLogin method and pass the HashMap you created as a parameter.
// each of the below mentioned fields are optional
HashMap<String, Object> profileUpdate = new HashMap<String, Object>();
profileUpdate.put("Name", "Jack Montana");    // String
profileUpdate.put("Identity", 61026032);      // String or number
profileUpdate.put("Email", "[email protected]"); // Email address of the user
profileUpdate.put("Phone", "+14155551234");   // Phone (with the country code, starting with +)
profileUpdate.put("Gender", "M");             // Can be either M or F
profileUpdate.put("DOB", new Date());         // Date of Birth. Set the Date object to the appropriate value first
// optional fields. controls whether the user will be sent email, push etc.
profileUpdate.put("MSG-email", false);        // Disable email notifications
profileUpdate.put("MSG-push", true);          // Enable push notifications
profileUpdate.put("MSG-sms", false);          // Disable SMS notifications
profileUpdate.put("MSG-whatsapp", true);      // Enable WhatsApp notifications
ArrayList<String> stuff = new ArrayList<String>();
stuff.add("bag");
stuff.add("shoes");
profileUpdate.put("MyStuff", stuff);                        //ArrayList of Strings
String[] otherStuff = {"Jeans","Perfume"};
profileUpdate.put("MyStuff", otherStuff);                   //String Array

clevertapDefaultInstance.onUserLogin(profileUpdate);
// each of the below mentioned fields are optional
val profileUpdate = HashMap<String, Any>()
profileUpdate["Name"] = "Jack Montana" // String
profileUpdate["Identity"] = 61026032 // String or number
profileUpdate["Email"] = "[email protected]" // Email address of the user
profileUpdate["Phone"] = "+14155551234" // Phone (with the country code, starting with +)
profileUpdate["Gender"] = "M" // Can be either M or F
profileUpdate["DOB"] = Date() // Date of Birth. Set the Date object to the appropriate value first
// optional fields. controls whether the user will be sent email, push etc.
// optional fields. controls whether the user will be sent email, push etc.
profileUpdate["MSG-email"] = false // Disable email notifications
profileUpdate["MSG-push"] = true // Enable push notifications
profileUpdate["MSG-sms"] = false // Disable SMS notifications
profileUpdate["MSG-whatsapp"] = true // Enable WhatsApp notifications
val stuff = ArrayList<String>()
stuff.add("bag")
stuff.add("shoes")
profileUpdate["MyStuff"] = stuff //ArrayList of Strings
val otherStuff = arrayOf("Jeans", "Perfume")
profileUpdate["MyStuff"] = otherStuff //String Array
CleverTapAPI.getDefaultInstance(applicationContext)?.onUserLogin(profileUpdate)

When the OnUserLogin method is called, the user profile information will be sent to CleverTap.

To see how this information displays within the CleverTap dashboard, perform the following:

  1. Navigate to Segments > Find People.
  2. In the By Identity box, enter the email you set on the user profile record, then click the Find button.

If CleverTap finds a user profile with this email, you will be taken to that user record. On that page, you will see the name and email as pre-defined fields and Customer type and Age as custom fields.

Track Custom Events

Once you integrate the CleverTap SDK, we automatically track events, such as App Launch and Notification Viewed. In addition to the default events tracked by CleverTap, you can also track custom events.

To send custom events to CleverTap using our Android SDK, you have to call the pushEvent method with the name of the custom event you want to track.

clevertapDefaultInstance.pushEvent("Product viewed");
clevertapDefaultInstance?.pushEvent("Product viewed")

To view the same user profile in CleverTap from the last section, click on the Activity button within the user profile record. This shows a list of activities associated with the user profile.

If the custom event was successfully sent from your application to CleverTap, you would see it in this list.

Next Steps

By completing this guide, you automatically track user events like app launches and associate that information with profiles for each of your users. Also, learn how to add information to a user profile and track custom events. You now have integrated CleverTap into your Android application

In the following sections, you will learn more advanced options for tracking custom events and enriching user profiles.


Did this page help you?