Integrate your Android App with Listrak platform to send Mobile App Push Notifications. 💡 Before you begin, work with your Account Manager to gain access to Push Channel in your Listrak account.
Follow these 4 steps to complete the Android App Integration:
STEP 1: Create the Listrak Integration
Navigate to Integrations > Integrations Integration Management.
Click on New Integration.
Select the Mobile App API card and click Integrate.
Click Setup Integration.
Give the integration a name.
Select the Mobile App
Save a new integration and copy the Client ID and Client Secret for later use in the integration steps.
⚠️ This step only needs to be done once, so if this was completed during the iOS App Integration process, move to the next step.
STEP 2: Add SDK as a dependency to Android App
For your reference, you can find the SDK hosted here/on github
In the project level build.gradle add the SDK repo URL under allprojects → repositories
build.gradle (project)
allprojects {
repositories {
...
// Add this line
maven { url "https://github.com/listrak/Listrak-Android-SDK/raw/main/" }
}
}
2. In the app level build.gradle add the implementation to the dependencies section for the version of the SDK you are using. For example to use version 1.0.0 of the SDK you would add:
build.gradle (app)
implementation 'com.listrak:ListrakSDK.Android:1.0.0'
3. Build your project and the SDK should be added as a dependency and ready for use.
STEP 3: Integrate SDK
An application class is a base class for maintaining global application state. Create a new class by following the below steps. If you've already created one, please start at step 3b.
INITIALIZE THE SDK
Add a new class,
ApplicationClass.java
to your projectThis class should extend
Application
and overrideonCreate()
it should look like this:
ApplicationClass.java
public class ApplicationClass extends Application {
@Override
public void onCreate() {
super.onCreate();
}
}
3. In AndroidManifest.xml
a. Add
android:name=".ApplicationClass"
to the<application>
tagb. Add the service below, within the application node; be sure to set the category to the package name for the application, define within the
<manifest>
tag
<service
android:name="com.listrak.android.sdk.NotificationClickService">
<intent-filter>
<action android:name="com.listrak.intent.NOTIFICATION_CLICK" />
<category android:name="YOUR-PACKAGE-NAME"/>
</intent-filter>
</service>
4. Create a global variable for the ListrakClient in the application class; import listraksdk_android.listrak.android.ListrakClient
private static ListrakClient client;
5. In the onCreate()
method of your application class, initialize the ListrakClient; pass in clientID and clientSecret to the ListrakCredentials
object; import listraksdk_android.listrak.android.ListrakCredentials
client = new ListrakClient(new ListrakCredentials("clientID", "clientSecret"));
a. If you would like to verify your clientID and clientSecret, request a token by making a POST request to our token endpoint at
https://auth.listrak/OAuth2/Token
. The request should have aContentType
ofx-www-form-urlencoded
, and the request body should include agrant_type
ofclient_credentials
, yourclient_id
, and yourclient_secret
b. To verify that you will be able to pass data to Listrak, make a
GET request
to our endpoint athttps://mobilesdk.listrak.com/v1/Get
; you will need to include the token using the Bearer scheme; specifically, you should set your Authorization header value toBearer (Your token value)
in the request
6. Add a getter method for the ListrakClient, so you can access it throughout your app
public static ListrakClient getListrakClient(){
return client;
}
This is how your application class should look:
ApplicationClass.java
import listraksdk_android.listrak.android.ListrakClient;
import listraksdk_android.listrak.android.ListrakCredentials;
public class ApplicationClass extends Application {
private static ListrakClient client;
@Override
public void onCreate() {
super.onCreate();
//Initialize ListrakSDK
client = new ListrakClient(new ListrakCredentials("clientID", "clientSecret"));
client.registerDeviceInformation();
}
public static ListrakClient getListrakClient(){
return client;
}
}
7. Add <uses-permission android:name="android.permission.INTERNET" />
to AndroidManifest.xml
8. Add implementation 'com.google.firebase:firebase-messaging:11.8.0'
to the app's build.gradle
SET UP EVENT TRACKING
App open and app exit
Add this dependency in the app's build.gradle:
implementation 'android.arch.lifecycle:extensions:1.1.1'
Add an
AppLifecycleObserver.java
as a new class:
AppLifecycleObserver.java
import android.arch.lifecycle.Lifecycle;
import android.arch.lifecycle.LifecycleObserver;
import android.arch.lifecycle.OnLifecycleEvent;
import listraksdk_android.listrak.android.ListrakClient;
public final class AppLifecycleObserver implements LifecycleObserver
{
private ListrakClient client;
public AppLifecycleObserver(ListrakClient c){
client = c;
}
@OnLifecycleEvent(Lifecycle.Event.ON_START)
public final void onEnterForeground() {
client.onEnterForeground();
}
@OnLifecycleEvent(Lifecycle.Event.ON_STOP)
public final void onEnterBackground() {
client.onEnterBackground();
}
}
3. Setup the Lifecycle observer in the OnCreate
method of the Application class
ApplicationClass.java
import android.arch.lifecycle.ProcessLifecycleOwner;
public class ApplicationClass extends Application implements LifecycleObserver {
@Override
public void onCreate() {
super.onCreate();
//Initialize ListrakSDK
ListrakClient client = new ListrakClient(new ListrakCredentials("clientID", "clientSecret"));
//Setup tracking for app open and exit
ProcessLifecycleOwner.get().getLifecycle().addObserver(new AppLifecycleObserver(client));
}
}
PROFILE FIELDS
The setProfileFields
method accepts - Email, First Name, Last Name, Phone Number, Birthday, and Postal Code. The first parameter of this method is the SegmentationAction enum
, which can be accessed with Enums.segmentationActionUpdate()
or Enums.segmentationActionOverwrite()
(note that you will need to import listraksdk_android.listrak.android.Enums
).
Update will update all the fields that have values and leave the existing value for any field that you passed over as null
Overwrite will set all the fields to the values you passed over, so if there was data for a field previously, but you pass over null for that field, it will now be set to null
If you don't wish to include the phone number, you must set it to 0 instead of null
PhoneNumber is of type Long, all the rest are of type String
Birthday is expected to be a string with the format MM/DD/YYYY or MM-DD-YYYY
TIP: You may need to use the getter method set up in Step 2, Initialize the SDK, #6 to access the ListrakClient
Some examples are:
ApplicationClass.getListrakClient().setProfileFields(Enums.segmentationActi onUpdate(), email, firstName, lastName, phoneNumber, birthday, postalCode);
ApplicationClass.getListrakClient().setProfileFields(Enums.segmentationActi onOverwrite(), email, firstName, lastName, 0, null, null);
To verify that Listrak is receiving data, you can install and open the app and the Total App Installs should increase on the Home Dashboard.
SETUP FIREBASE/PUSH NOTIFICATIONS
1. Navigate to Android Studio
2. Go to Tools
3. Then Firebase
4. Navigate to Cloud Messaging
5. Click Setup Firebase Cloud Messaging

6. Click Connect your app to Firebase
7. Select your Firebase project and click Connect to Firebase; this will add googleservices.json to your project
8. Click the Add FCM to your app button; this will add the firebase dependencies to your build.gradle
9. All push notifications must be assigned to a notification channel in Android 8.0 (Oreo) and higher; in your application class, pass your channel ID to Listrak with the setChannelID method; for example:
ApplicationClass.java
public void onCreate() {
super.onCreate();
//Initialize ListrakSDK here
client.setChannelID(createNotificationChannel("channel-id"));
}
private String createNotificationChannel(String channelID) {
NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
NotificationChannel channel = new NotificationChannel(channelID,
"Channel Name", NotificationManager.IMPORTANCE_DEFAULT);
notificationManager.createNotificationChannel(channel);
}
return channelID;
}
10. All push notifications must have an icon set. If you do not set this, your push notifications will not be delivered, and your app will crash. In your application class, pass your icon to Listrak with the SetIcon method; for example,
client.setIcon(R.drawable.ic_your_icon_here);
11. This is how your application class should look now:
ApplicationClass.java
import listraksdk_android.listrak.android.ListrakClient;
import listraksdk_android.listrak.android.ListrakCredentials;
public class ApplicationClass extends Application {
private static ListrakClient client;
@Override
public void onCreate() {
super.onCreate();
//Initialize ListrakSDK
client = new ListrakClient(new ListrakCredentials("clientID", "clientSecret"));
client.setChannelID(createNotificationChannel("channel-id"));
client.setIcon(R.drawable.ic_your_icon_here);
}
public static ListrakClient getListrakClient(){
return client;
}
private String createNotificationChannel(String channelID) {
NotificationManager notificationManager = (NotificationManager)
getSystemService(Context.NOTIFICATION_SERVICE);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
NotificationChannel channel = new NotificationChannel(channelID,
"Channel Name",
NotificationManager.IMPORTANCE_DEFAULT);
notificationManager.createNotificationChannel(channel);
}
return channelID;
}
}
PROGUARD RULES
If you are using Proguard, you will need to add these rules.
-keep class mono.embeddinator.** { *; }
-keep class android.support.v4.app.Notification** { *; }
-keep class listraksdk.** { *; }
-keep class listraksdk_android.** { *; }
-keep class mono.android.** { *; }
-keep class com.sun.jna.** { *; }
-keep class com.google.firebase.iid.FirebaseInstanceId { *; }
-keep class android.runtime.JavaProxyThrowable { *; }
-keep class android.arch.lifecycle.ProcessLifecycleOwnerInitializer { *; }
-keep class com.google.firebase.messaging.RemoteMessage { public *; }
-keep class android.runtime.UncaughtExceptionHandler { *; }
-keep class mono.MonoPackageManager { *; }
-dontwarn java.awt.**
CONVERSION TRACKING
In order for Listrak to track purchases made within the app, you will need to pass all the available data about the purchase to Listrak. Order number and order total are the only required fields for conversion tracking.
1. Create a ListrakOrder object; you will need to import listraksdk_android.ordertracking.ListrakOrder
ListrakOrder order = new ListrakOrder();
2. Set the OrderNumber and OrderTotal of the order object, along with any additional data you have
order.SetOrderNumber("123456");
order.SetOrderTotal(119.99);
3. To set the ShippingAddress and BillingAddress, use the ListrakAddress object. You will need to import listraksdk_android.listrak.ordertracking.ListrakAddress
for example:
ListrakAddress address = new ListrakAddress();
address.setAddress1("123 Main Street");
order.SetShippingAddress(address);
4. For every item in the order, create a ListrakItem object and add it to the order using the addItem method; you will need to import listraksdk_adroid.ordertracking.ListrakItem
for example:
ListrakItem item = new ListrakItem();
item.setSku("ABC-123");
order.AddItem(item);
5. When you have set all the data about the order, submit it to Listrak using the submitOrder method
order.submitOrder();
6. To verify that Listrak is receiving your order data, note that you will need to first click on a push notification and then place the order; the conversion information will appear on the broadcast report page for the push notification
Below is the list of the available methods on each object:
ListrakOrder
setOrderNumber (String s)
setOrderTotal (double v)
setEmail(String s)
setCustomerNumber(String s)
setHandlingTotal (double v)
setDiscountDescription(String s)
setDiscountTotal(double v)
setDiscountType (int i) **
**Values are available in listraksdk_android.Enums
prefixed with discountType
setTaxTotal(double v)
setcouponCode(String s)
setStatus(int i) **
**Values are available in listraksdk_android.listrak.android.Enums
prefixed with status
setShippingAddress(ListrakAddress listrakAddress)
setShippingMethod(String s)
setShippingTotal(double v)
setShipDate(String s) **
**Expected format is MM/DD/YYYY or MM-DD-YYYY
setTrackingNumber(String s)
setBillingAddress(ListrakAddress listrakAddress)
setItemTotal(double v)
setStoreNumber(String s)
setAssociateID(String s)
setMeta1(String s)
setMeta2(String s)
setMeta3(String s)
setMeta4(String s)
setMeta5(String s)
addItem(ListrakItem listrakItem)
submitOrder()
Listrak Address
setFirstName(String s)
setLastName(String s)
setAddress1(String s)
setAddress2(String s)
setAddress3(String s)
setCity(String s)
setState(String s)
setZipCode(String s)
setCountry(String s)
setPhone(String s)
ListrakItem
setOrderNumber(String s)
setSku(String s)
setPrice(double v)
setDiscountedPrice(double v)
setDiscountType(int i) **
**Values are available in listraksdk_android.listrak.android.Enums
prefixed with discountType
setDiscountDescription(String s)
setQuantity(int i)
setItemTotal(double v)
setStatus(int i) **
**Values are available in listraksdk_android.Enums
prefixed with status
setShippingMethod(String s)
setShipDate(String s) **
**Expected format is MM/DD/YYYY or MM-DD-YYYY
setTrackingNumber(String s)
setMeta1(String s)
setMeta2(String s)
setMeta3(String s)
setMeta4(String s)
setMeta5(String s)
Enums - Discount Type
discountTypeNotSet()
discountTypePriceOverride()
discountTypePriceRule()
discountTypePromotion()
discountTypeSeniorCitizen()
discountTypeMarkdown()
discountTypeCoupon()
discountTypeQuantityDiscount()
discountTypeRebate()
discountTypeCashDiscount()
discountTypeTradeDiscount()
discountTypeTradeInKind()
discountTypePromptPaymentDiscount()
discountTypeGeneralDiscount()
Enums - Status
statusNotSet()
statusMisc()
statusBackOrder()
statusPending()
statusHold()
statusProcessing()
statusShipped()
statusCompleted()
statusReturned()
statusCanceled()
statusUnknown()
statusClosed()
ADDITIONAL/OPTIONAL FEATURES
If you wish to allow a user to enable/disable notifications within your app, you can make a call to the method EnableDisableAppNotification()
This method takes 1 boolean parameter pass in true when you want to enable notifications and false when you want to disable them
TIP: You may need to use the getter method set up in Step 2, Initialize the SDK, #6 to access the ListrakClient
Here is an example:
//Enable
ApplicationClass.getListrakClient().EnableOrDisableAppNotification(true);
//Disable
ApplicationClass.getListrakClient().EnableOrDisableAppNotification(false);
Notes:
You will need to control the user’s status, to ensure your control displays the correct state
This state is not synchronized with the system setting; turning notifications off in either the system setting or with this method will always unsubscribe the user, however, enabling notifications with this method, while the system setting is still disabled, will not subscribe the user
Users must have the system setting enabled to receive notifications, regardless of what the app setting is. The exact use cases are as follows:
If the user had both the system setting and app setting enabled, then disabled just in system settings, they will be unsubscribed
If the user had both the system setting and app setting enabled, then disabled just in app settings, they will be unsubscribed
If the user had both the system setting and app setting disabled, and then enabled just in system settings, they will be subscribed
If the user had both the system setting and app setting disabled, and then enabled just in app settings, they will not be subscribed
STEP 4: Add Android Server Key to Listrak
After you've completed the above set up, the next step is to locate your server ID, which is used to connect this service to Listrak. Follow the below steps to locate your server key - this key authenticates with Google to deliver push notifications.
LOCATE THE SERVER KEY
Login to Firebase
Access the Firebase Developers Console
Select the Firebase project
Navigate to the Settings section
Copy the Server Key
Be sure to keep this server key in a safe and secure place. The next step is to add this server key into Listrak.
ADD ANDROID SERVER KEY TO LISTRAK
Log into Listrak; access the Push Settings by following the below steps:
Navigate to Settings > App Push Settings App Push Settings
Enter the Android Server Key
Click Add Key to complete the integration.
⚠️ All settings for push notifications are disabled until a iOS certificate and Android token is setup.
For more information on Mobile App Push Notifications, reach out to your Account Manager or Listrak Support!