Documentation > Android

Getting Started

Install the SDK

Option A – Install using Android Studio / Gradle (recommended)

Starting with v3.0.0, the SDK supports Firebase Cloud Messaging (FCM) as an alternative to Google Cloud Messaging (GCM).

If using FCM:

Add dependencies for CleverTap, Firebase Messaging and Android Support Library v4 in your app/build.gradle file.

dependencies {
    compile 'com.clevertap.android:clevertap-android-sdk:3.1.7'
    compile 'com.google.firebase:firebase-messaging:11.4.0'
    compile 'com.google.android.gms:play-services-base:11.4.0'
    compile 'com.android.support:support-v4:23.1.1'
}

// at the end of the build.gradle file
apply plugin: 'com.google.gms.google-services'
copy Copied

Also, add the FCM generated google-services.json file to your project.

If using GCM:

Add dependencies for CleverTap, Google Play Services and Android Support Library v4 in your app/build.gradle file.

dependencies {
    compile 'com.clevertap.android:clevertap-android-sdk:3.1.7'
    compile 'com.google.android.gms:play-services-gcm:11.0.4'
    compile 'com.google.android.gms:play-services-base:11.4.0'
    compile 'com.android.support:support-v4:23.1.1'
}
copy Copied

Once you have updated your build.gradle file, sync your project in ToolsAndroidSync Project With Gradle Files

Option B – Install Manually

There’s a dependency on the Android v4 support library, minimum rev 23.1.1. The minimum Android SDK level supported is 14 (4.0 – Ice Cream Sandwich).

Modify AndroidManifest.xml

Add CleverTap credentials

Add CleverTap account ID and Token to your AndroidManifest.xml, within the <application></application> tags. Your CleverTap ID and Token are available under DashboardSettings


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

copy Copied

If you’d rather set your account credentials in code, see here.

If your account data is to be hosted on the India Data centre explicitly, please contact your CleverTap Account Manager for additional details regarding integration

Set the LifeCycle Callback

This will enable you to track notification opens, deep link performance and display in-app notifications.

<application
    android:label="@string/app_name"
    android:icon="@drawable/ic_launcher"
    android:name="com.clevertap.android.sdk.Application">

copy Copied

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

Add Permissions

<!-- 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"/>
copy Copied

Add the Referral Tracking Receiver

Add the following between the <application></application> tags. This will enable you to capture UTM parameters for app installs

<receiver
    android:name="com.clevertap.android.sdk.InstallReferrerBroadcastReceiver"
    android:exported="true">
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER"/>
        </intent-filter>
</receiver>
copy Copied

Enabling Push Notifications

The easiest way to send push notifications is to use the default implementation by CleverTap. However, if you have your own implementation, or use another push provider see this section – Custom Handling Push Notifications

Starting with v3.0.0, the SDK supports FCM as an alternative to GCM.

If using FCM:

Inside the <application></application> tags, register the following services.

<service
    android:name="com.clevertap.android.sdk.FcmTokenListenerService">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
    </intent-filter>
</service>

<service
    android:name="com.clevertap.android.sdk.FcmMessageListenerService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"/>
    </intent-filter>
</service>
copy Copied

If using GCM:

Add the following GCM Permissions, replacing com.your.package below with your application’s package name.

<uses-permission
    android:name="com.google.android.c2dm.permission.RECEIVE"/>
<uses-permission 
    android:name="android.permission.WAKE_LOCK" /> <!--if using CleverTap SDK v3.0.0+-->
<permission
    android:name="com.your.package.permission.C2D_MESSAGE"
    android:protectionLevel="signature"/>
<uses-permission
    android:name="com.your.package.permission.C2D_MESSAGE"/>

copy Copied

If using CleverTap SDK v3.0.0 or higher:

Inside the <application></application> tags, register the following receiver and services, and specify your GCM project number, replacing com.your.package with your application’s package name:

<!-- replace below value with your GCM project number. Separate multiple sender IDs with a comma -->
<meta-data android:name="GCM_SENDER_ID" android:value="id:1234567890"/> 

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version"/>

<!-- replace com.your.package below with your package name-->
<receiver
    android:name="com.google.android.gms.gcm.GcmReceiver"
    android:exported="true"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
        <category android:name="com.your.package" />
    </intent-filter>
</receiver>

<service
    android:name="com.clevertap.android.sdk.GcmMessageListenerService"
    android:exported="false" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    </intent-filter>
</service>

<service android:name="com.clevertap.android.sdk.GcmTokenListenerService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.android.gms.iid.InstanceID"/>
    </intent-filter>
</service>
copy Copied

Opening a notification using CleverTap’s implementation will cause your app to be launched. If you’re sending a deep link, then the link will be opened

Here is a quick guide on how to find your GCM Sender ID

Set the Small Notification Icon

With the launch of Android 5 (Lollipop), the notification icons are rendered differently in the notification bar at the top. By default, our SDK uses the app’s icon for both, the notification icon as well as the notification bar icon.

However, since Android 5, all non-alpha channels are ignored while drawing the main notification icon. See the official Android documentation here for more details.

To set a custom notification icon (only for small icon), add the following meta data entry in your AndroidManifest.xml

<meta-data
    android:name="CLEVERTAP_NOTIFICATION_ICON"
    android:value="ic_stat_red_star"/> <!-- name of your file in the drawable directory without the file extension. -->

copy Copied

Don’t use @drawable/ic_stat_red_star. It will not work

Enabling In-App Notifications

In-App notifications are pop-ups that you can show to your users while they are in your application. To support in-app notifications, register the following activity in your AndroidManifest.xml:


<activity
    android:name="com.clevertap.android.sdk.InAppNotificationActivity"
    android:theme="@android:style/Theme.Translucent.NoTitleBar"
    android:configChanges="orientation|keyboardHidden"/>

<meta-data
    android:name="CLEVERTAP_INAPP_EXCLUDE"
    android:value="YourSplashActivity1, YourSplashActivity2" /> 
copy Copied

Mention the Activities on which you don’t want In-App notifications to show in the android:value of the meta-data tag

Getting an instance of the SDK

Once you’ve registered the application lifecycle callback, the basic integration is complete and CleverTap system events can be recorded. (Click here to see the events recorded automatically)

To be able to send custom events, and push profile properties, you may get an instance of the SDK as follows:

CleverTapAPI cleverTap;
try {
  cleverTap = CleverTapAPI.getInstance(getApplicationContext());
} catch (CleverTapMetaDataNotFoundException e) {
  // thrown if you haven't specified your CleverTap Account ID or Token in your AndroidManifest.xml
} catch (CleverTapPermissionsNotSatisfied e) {
  // thrown if you haven’t requested the required permissions in your AndroidManifest.xml
}

copy Copied

Intro to User Profiles

CleverTap stores the user’s demographic data (gender, age, location), app and website interactions, campaign visits and transaction history to give you a complete picture for every user.

A User Profile is automatically created for every user launching your mobile application – whether logged in or not.

Initially, the User Profile starts out as “Anonymous” – which means that the profile does not yet contain any identifiable information about the user. You can choose to enrich the profile with attributes like name, age, customer id, etc.

CleverTap provides pre-defined profile properties such as name, phone, gender, age etc to represent well know properties associated with a profile. It is strongly recommended to use these standard property names. A list of all pre-defined property names is available here. In addition, we also support arbitrary single and multi value profile properties. Examples of updating these type of properties is documented below.

Select Platform
// each of the below mentioned fields are optional
// if set, these populate demographic information in the Dashboard
HashMap<String, Object> profileUpdate = new HashMap<String, Object>();
profileUpdate.put("Name", "Jack Montana");                  // String
profileUpdate.put("Identity", 61026032);                    // String or number
profileUpdate.put("Email", "jack@gmail.com");               // 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("Employed", "Y");                         // Can be either Y or N
profileUpdate.put("Education", "Graduate");                 // Can be either Graduate, College or School
profileUpdate.put("Married", "Y");                          // Can be either Y or N
profileUpdate.put("DOB", new Date());                       // Date of Birth. Set the Date object to the appropriate value first
profileUpdate.put("Age", 28);                               // Not required if DOB is set
profileUpdate.put("Tz", "Asia/Kolkata");                    //an abbreviation such as "PST", a full name such as "America/Los_Angeles", 
                                                            //or a custom ID such as "GMT-8:00"
profileUpdate.put("Photo", "www.foobar.com/image.jpeg");    // URL to the Image

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

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

cleverTap.profile.push(profileUpdate);

copy Copied
HashMap<String, Object> profileUpdate = new HashMap<String, Object>();
profileUpdate.put("Customer Type", "Silver");
profileUpdate.put("Prefered Language", "English");

cleverTap.profile.push(profileUpdate);

/**
 * Data types
 * The value of a property can be of type Date (java.util.Date), an Integer, a Long, a Double,
 * a Float, a Character, a String, or a Boolean.
 */
copy Copied
// To set a multi-value property
ArrayList<String> stuff = new ArrayList<String>();
stuff.add("bag");
stuff.add("shoes");
cleverTap.profile.setMultiValuesForKey("mystuff", stuff);

// To add an additional value(s) to a multi-value property
cleverTap.profile.addMultiValueForKey("mystuff", "coat");
// or
ArrayList<String> newStuff = new ArrayList<String>();
newStuff.add("socks");
newStuff.add("scarf");
cleverTap.profile.addMultiValuesForKey("mystuff", newStuff);


//To remove a value(s) from a multi-value property
cleverTap.profile.removeMultiValueForKey("mystuff", "bag");
// or
ArrayList<String> oldStuff = new ArrayList<String>();
oldStuff.add("shoes");
oldStuff.add("coat");
cleverTap.profile.removeMultiValuesForKey("mystuff", oldStuff);

//To remove the value of a property (scalar or multi-value)
cleverTap.profile.removeValueForKey("mystuff");
copy Copied

CleverTap provides easy ways to enrich the user profile with data from sources like Facebook or Google Plus. You can also store custom attributes in a user profile. These attributes can later be used to segment users.

For complete User Profile documentation, see: Working with User Profiles

Intro to User Events

A User Event is an action a user takes in your mobile application. CleverTap records the event on the User Profile, using an Event Name and optional associated key:value-based Event Properties. You can then segment users, target and personalize messaging based on both the Event Name and specific Event Properties.

An example of recording a User Event called Product Viewed:

// event without properties
cleverTap.event.push("Product viewed");
copy Copied

An example of recording a User Event called Product Viewed with Properties:

// event with properties
HashMap<String, Object> prodViewedAction = new HashMap<String, Object>();
prodViewedAction.put("Product Name", "Casio Chronograph Watch");
prodViewedAction.put("Category", "Mens Accessories");
prodViewedAction.put("Price", 59.99);
prodViewedAction.put("Date", new java.util.Date());

cleverTap.event.push("Product viewed", prodViewedAction);

/**
 * Data types
 * The value of a property can be of type Date (java.util.Date), an Integer, a Long, a Double,
 * a Float, a Character, a String, or a Boolean.
 *
 * Date object
 * When a property value is of type Date, the date and time are both recorded to the second.
 * This can be later used for targeting scenarios.
 * For e.g. if you are recording the time of the flight as an event property,
 * you can send a message to the user just before their flight takes off.
 */
copy Copied

Events help you understand how your users interact with your app. CleverTap tracks certain common User Events automatically, while giving you the flexibility to record business specific events.

For a complete guide to recording Events, see: Working with Events; to capture customer transactions, see : Recording Customer Purchases

Using Proguard

To be able to use ProGuard with the CleverTap SDK, you’ll need to add the following rule:

# For CleverTap SDK
-dontwarn com.clevertap.android.sdk.**
copy Copied

Debugging

By default, CleverTap logs are set to CleverTap.Loglevel.INFO. During development, we recommend that you set the SDK to DEBUG mode, in order to log warnings or other important messages to the Android logging system. This can be done by setting the debug level to CleverTap.Loglevel.DEBUG. If you want to disable CleverTap logs for production environment, you can set the debug level to CleverTap.Loglevel.OFF.

CleverTapAPI.setDebugLevel(CleverTapAPI.LogLevel.INFO);    //Default Log level

CleverTapAPI.setDebugLevel(CleverTapAPI.LogLevel.DEBUG);   //Set Log level to DEBUG log warnings or other important messages

CleverTapAPI.setDebugLevel(CleverTapAPI.LogLevel.OFF);     //Switch off logs for Production environment
copy Copied

Next Steps

Go ahead, pat yourself on the back – the basic CleverTap integration is complete!

You can now track app launches, uninstalls, visit frequency, and session details. You can also send push notification, and show in-app notifications to your users.

Here is what we recommend you to do next: