Resources

Support

Recent Posts

Archive

Android

This guide will show you how to how to track custom events, enrich user profiles, and send push notifications with the CleverTap SDK in your Android app.

If you haven’t already completed the Android quickstart guide, please complete that first before following this guide. The quickstart guide will show you how to install the CleverTap SDK, track your first user event, and see this information within the CleverTap dashboard.

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.

// each of the below mentioned fields are optional// if set, these populate demographic information in the DashboardHashMap<String, Object>profileUpdate=newHashMap<String, Object>();
profileUpdate.put("Name", "Jack Montana"); // StringprofileUpdate.put("Identity", 61026032); // String or numberprofileUpdate.put("Email", "jack@gmail.com"); // Email address of the userprofileUpdate.put("Phone", "+14155551234"); // Phone (with the country code, starting with +)profileUpdate.put("Gender", "M"); // Can be either M or FprofileUpdate.put("Employed", "Y"); // Can be either Y or NprofileUpdate.put("Education", "Graduate"); // Can be either Graduate, College or SchoolprofileUpdate.put("Married", "Y"); // Can be either Y or NprofileUpdate.put("DOB", newDate()); // Date of Birth. Set the Date object to the appropriate value firstprofileUpdate.put("Age", 28); // Not required if DOB is setprofileUpdate.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 notificationsprofileUpdate.put("MSG-push", true); // Enable push notificationsprofileUpdate.put("MSG-sms", false); // Disable SMS notificationsArrayList<String>stuff=newArrayList<String>();
stuff.add("bag");
stuff.add("shoes");
profileUpdate.put("MyStuff", stuff); //ArrayList of StringsString[] otherStuff= {"Jeans","Perfume"};
profileUpdate.put("MyStuff", otherStuff); //String ArraycleverTap.profile.push(profileUpdate);

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

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.

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.

// event with propertiesHashMap<String, Object>prodViewedAction=newHashMap<String, Object>();
prodViewedAction.put("Product Name", "Casio Chronograph Watch");
prodViewedAction.put("Category", "Mens Accessories");
prodViewedAction.put("Price", 59.99);
prodViewedAction.put("Date", newjava.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.*/

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.

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 the Custom Handling Push Notifications section

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.

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

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

ProGuard

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 levelCleverTapAPI.setDebugLevel(CleverTapAPI.LogLevel.DEBUG); //Set Log level to DEBUG log warnings or other important messagesCleverTapAPI.setDebugLevel(CleverTapAPI.LogLevel.OFF); //Switch off logs for Production environment

Push Notifications for Android O

Android has modified the way push notifications can be sent to an app in its latest version Oreo. Starting with CleverTap SDK 3.1.7, we support Android Oreo’s latest features like Notification Channels and Notification Badges.

Step 1: PrerequisitesSince Notification channels and badges are the features of the latest Android version, you as a developer will have to update your SDK and Build Tools to the latest versions. The latest SDK tools version is 26.0.2 and the latest Build Tools version is 26.0.1. You will have to make sure that in your build.gradle file, the compileSdkVersion is 26 and buildToolsVersion is 26.0.1

Step 2: Creating Notification Channel GroupsOnce you have the CleverTap Android SDK integrated successfully, you can create a notification channel group. Notification channel groups allow you to manage multiple notification channels with identical names within a single app, which can be useful if your app supports multiple accounts. You can create a notification group using the following line of code –

Step 3: Creating Notification Channels with Notification GroupsOnce you have created a notification channel group you can use the group Id to create notification channels for that specific group. You can create a notification channel specifying the group id using the following line of code.

You can create more than one channel using the above line of code, just make sure that the channel ID differs in every Notification Channel. Also, this Channel ID will be used to send Push Notifications using the CleverTap dashboard.

Step 5: Deleting Notification ChannelsYou can delete the notification channels created previously in your app. There is no error thrown when you try to delete a notification channel which doesn’t exist. You can delete the notification channels using the following line of code.

Step 6: Deleting Notification GroupsCleverTap SDK also allows you to remove the notification groups you have created previously. Please note that you will need to delete all the channels associated with a group prior to deleting a group. You can delete a notification group using the following line of code.

Step 7: Sending Notifications via DashboardTo send Push Notifications, login to the CleverTap Dashboard and on the left navigation menu click on Messages. Then click on +Message button on the top right to select Mobile Push. Now, set up your Push Notification campaign by selecting when you want to send out your notification, who do you want to send it out to (in this case it will be Android users) and what kind of push notification you want to send out. Once you reach the what section, select the Single Message option. Select the checkbox which says Send Message to Android O.

Fill in the Channel with the channel id you used to create the notification channel in your app. This field is mandatory as Android O requires a valid channel to send notifications. Badge Icon can be set as the app icon or the small icon used to denote push notifications. The default is app icon. Badge ID is the number you want to set the Notification Badge with, by default it auto-increments. Both Badge Icon and Badge ID are optional.

Custom Android Push Notifications Handling

Step 1. Using Your Custom ImplementationIf you have your custom implementation for managing Android push notifications, you can inform CleverTap about the user’s GCM/FCM registration ID.

Please follow the instructions below if you are using GCM. If you are using FCM skip that to that section further below.

Step 2: Using Multiple Android Push Notification ProvidersCleverTap plays well with other Android push notification providers. You can configure your app to work with multiple push notification providers.

If you are using GCM, please follow the instructions below. If you are using FCM, please follow the instructions included further below.

In the below example, we use Parse as the other provider. The idea is to create your own GCM broadcast receiver, and then notify both CleverTap and Parse upon receiving a push message.

Step 3: Structure of CleverTap GCM Payload

Here is the structure of the payload with a CleverTap GCM push notification.

Key

Type

Description

wzrk_pn

N/A

If present, this notification is sent from CleverTap.

wzrk_id

string

Open rate tracking ID (can be empty or it might not be present).

wzrk_bp

string

If present, the value will be a URL of an image, that needs to be displayed in the notification.

wzrk_sound

boolean or string

If present, it signifies that the default or custom Android notification sound must be played.

nt

string

Notification Title, if absent or empty, fallback to the app name.

nm

string

Notification Body, if absent or empty, ignore this notification.

wzrk_dl

string

If present, this is a deep link that must be followed at the time of notification open.

wzrk_d

N/A

If present, ignore this notification.

ico

string

If present and not empty, it contains the URL of an image, that must be used as the small notification icon.

wzrk_pivot

string

If present and not empty, it contains the URL of an image, it signifies the type of variant in A/B campaigns.

If the field nm is empty, ignore the notification. CleverTap sends out a dummy notification with the nm field empty to test for app uninstalls. In addition to the above, attach all keys starting with wzrk_ to your notification extras (For example, wzrk_id is used to track notification opens).

Advanced Android Push Notification Options

Apart from Title and Message, you have the below mentioned options to add to your Android push notification. Please note that each of these are optional.

Image URLIf an image link is specified, a large image is added to your push notification.

Recommended resolution: 600×300

Max size: 40 kb

Supported file formats are .jpg and .png

Large Icon URLIf a large icon link is specified, the large icon will be appended to the push notification. Based on the device, the large icon will be displayed either far left or far right.

Max resolution – 72×72

Max size – 1 kb

Deep Link/External URLDeep link helps you open a particular activity in your app on click of the notification. If left empty, the notification on click will open the launcher activity of the app. If you wish to use external URLs, then please whitelist the IPs or provide http/https before the URL so that they can be handled properly by the SDK.

Action ButtonsYou can add upto 3 call to action buttons for every push notification. For every action button, you have the following options:

Title: contains the Call to Action text (mandatory)

Deep link: the deep link that should open on click of that button

Action ID: a user defined string (applicable to apps custom handling their android push notifications: This string will be available as an extra on the notification click intent for you to identify the action button clicked) This is a mandatory field.

Icon Resource Identifier: A drawable icon in your app’s resources folder to display the icon along with the notification for Android devices below OS version Nougat. Android Nougat does not display icons by default to give more room for buttons.

If the user clicks on the main body of the notification, the app will open and the notification will disappear. If the user clicks on one of the action buttons, then by default android will not remove the notification from the tray. We provide two user options for this.

The first option is to handle closing the notification yourself (applies to apps that are custom handling the push notification). To accomplish this, the click intent has the notification Id in its extras. So to close, please add the following code in the activity that would get called.

Sound FilesYou can choose to have no notification sound, the default OS sound or use a custom sound. It has to be present in the resources folder of your app. Please see the Android sound guide to learn how to add a sound file to your android app. Android only supports .mp3, .ogg and .wav files.

Setting PriorityRelative priority for this notification. Priority is an indication of how much of the user’s valuable attention should be consumed by this notification.

MAXIMUM: Use for critical and urgent notifications that alert the user to a condition that is time-critical or needs to be resolved before they can continue with a particular task. A notification with priority set to maximum will be a heads up notification, and will always be at the top in the notification tray.

HIGH: Use primarily for important communication, such as message or chat events with content that is particularly interesting for the user. High-priority notifications trigger the heads-up notification display. A notification with priority set to high will be a heads up notification.

DEFAULT: Use for all notifications that don’t fall into any of the other priorities. A notification with default priority will simply show up in the notification tray and its order in the notification tray is subject to presence of other notifications.

Changing Account Credentials

If you’d not want to insert your account credentials in your app’s AndroidManifest.xml, or would like to change your account ID programmatically, you need to create a custom Application class (if you don’t have one already) with the following content.