Android App Integration

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 project
This class should extend Application and override onCreate() 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> tag
b. 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 a ContentType of x-www-form-urlencoded, and the request body should include a grant_type of client_credentials, your client_id, and your client_secret
b. To verify that you will be able to pass data to Listrak, make a GET request to our endpoint at https://mobilesdk.listrak.com/v1/Get; you will need to include the token using the Bearer scheme; specifically, you should set your Authorization header value to Bearer (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!