DocumentationDeveloper PortalAPI EndpointsProduct Updates
Developer Portal
Contact Us

Track events on your app

This article provides steps on how you can use our Android SDK to track events on your app.

Suggest Edits

📘

Wait. Are you ready for this part?

In this article, we'll show you methods that are available in the SDK to track events on your app. However, this cannot work until you have the SDK in your project and you can use it in your app. If not, then we suggest that you do those things first and then come back here to track events in your app.

It's absolutely not complicated. We promise. And, like earlier, we'll wait. No pressure. ☺️

Our SDK, along with the API, provides features that you can use to track events on your app, such as:

  • User checks in on the app
  • Identify the customer
  • Customer adds a product to the cart
  • Customer checks out the product
  • Customer buys a product

The SDK can:

You can also send a custom JSON to our platform.

Events that you can track on your Android app using the methods in the SDK

The list above represents some of the events that occur on your app that the SDK can track. Use the methods described below to track such events.

Custom events

Use the trackEvent method to track custom events with custom attributes in your app.

Here's how to use it:

HashMap<String, Object> params = new HashMap<>();
params.put("name", "Ross Geller");
params.put("profession", "paleontologist");
//..add more values if required..//

Blueshift.getInstance(mContext).trackEvent("your_custom_event_name", params, true);

Identify a customer

Use the identify method to identify the customer who signs in to your app. The primary identifier used to identify a customer is deviceId (Google recommends that you use the Android Advertising ID). The deviceId is set during the SDK initialization, and it is automatically sent to Blueshift. In addition to sending the device ID, we recommend that you set the email and customer ID of the customer if you can. This would ensure that if a customer resets the device ID, we can still attribute events to — and generate recommendations for — the customer.

Here's how to use it:

// Identify event with device id as the primary identifier
Blueshift
        .getInstance(mContext)
        .identifyUserByDeviceId(deviceId, null, false);

Screen view

Use the trackScreenView method to send the page_load event that tracks the screen a customer sees.

Here's how to use it:

// with instance of activity
Blueshift
        .getInstance(mContext)
        .trackScreenView(this, true);

// with custom screen name
Blueshift
        .getInstance(mContext)
        .trackScreenView("product page", true);

Product view

Use the trackProductView method to track views of a particular product on your app. It can take common attributes like sku and category_id. In addition, you can pass additional parameters such as HashMap.

Here's how to use it:

String sku = product.getSku();
int categoryId = product.getCategoryId();

Blueshift
        .getInstance(mContext)
        .trackProductView(sku, categoryId, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackProductView(sku, categoryId, optionalAttr, true);

Add to cart

Use the trackAddToCart method to track add-to-cart events. This can be called when either the add-to-cart button is clicked, or when the add-to-cart API call is made.

Here's how to use it:

String sku = product.getSku();
int quantity = product.getQuantity();

Blueshift
        .getInstance(mContext)
        .trackAddToCart(sku, quantity, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackAddToCart(sku, quantity, optionalAttr, true);

Cart checkout

Use the trackCheckoutCart method to track a check out of a cart. The first argument to the method is array of products in the cart, and this product model is included in the SDK. You can create an instance and set the values in it using your product instance.

Here's how to use it:

float revenue = cart.getRevenue();
float discount = cart.getDiscount();
String coupon = cart.AppliedCounpon();
// implements `buildProductArray()` to return required product array.
Product[] products = buildProductArray();

Blueshift
        .getInstance(mContext)
        .trackCheckoutCart(products, revenue, discount, coupon, true);

If you want your app to send additional parameters:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackCheckoutCart(
                products,
                revenue,
                discount,
                coupon,
                optionalAttr,
                true);

Purchase

Use the trackProductsPurchase to track a completed product purchase.

Here's how to use it:

String orderId = order.getOrderId();
Product[] products = order.getProducts();
float revenue = order.getRevenue();
float shippingCost = order.getShippingCost();
float discount = order.getDiscount();
String coupon = order.getAppliedCoupon();

Blueshift
        .getInstance(mContext)
        .trackProductsPurchase(
                orderId,
                products,
                revenue,
                shippingCost,
                discount,
                coupon, 
                true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackProductsPurchase(
                orderId,
                products,
                revenue,
                shippingCost,
                discount,
                coupon, 
                optionalAttr,
                true);

Cancelled purchase

Use the trackPurchaseCancel method to track the if a customer cancelled a completed order.

Here's how to use it:

String orderId = order.getOrderId();

Blueshift
        .getInstance(mContext)
        .trackPurchaseCancel(orderId, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackPurchaseCancel(orderId, optionalAttr, true);

Return a purchase

Use the trackPurchaseReturn method to track the return of a purchase. You can call this method once the purchase return API is called.

Here's how to use it:

String orderId = order.getOrderId();
// implement `getReturnedProducts` to return required products array.
Product[] products = order.getReturnedProducts();

Blueshift
        .getInstance(mContext)
        .trackPurchaseReturn(orderId, products, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackPurchaseReturn(orderId, products, optionalAttr, true);

Product search

Use the trackProductSearch method to track the search events inside host app. Call this method when a search is performed.

You can implement this method in 3 ways. Here's how to do it with optional filters and extra arguments:

Blueshift
        .getInstance(mContext)
        .trackProductSearch(
                skus,              // array of sku of products in result (String[])
                numberOfResults,   // number of results obtained (int)
                pageNumber,        // page number of the result (int)
                query,             // search query used (String)
                true);

Here's how to do it with optional filters:

Blueshift
        .getInstance(mContext)
        .trackProductSearch(
                skus,              // array of sku of products in result (String[])
                numberOfResults,   // number of results obtained (int)
                pageNumber,        // page number of the result (int)
                query,             // search query used (String)
                filters,           // filters applied in this search (HashMap<String,Object>)
                true);

Here's how to do it with optional additional parameters:

Blueshift
        .getInstance(mContext)
        .trackProductSearch(
                skus,              // array of sku of products in result (String[])
                numberOfResults,   // number of results obtained (int)
                pageNumber,        // page number of the result (int)
                query,             // search query used (String)
                filters,           // filters applied in this search (HashMap<String,Object>)
                optionalAttr,      // optional additional parameters (HashMap<String,Object>)
                true);

Subscribe to emails

Use the trackEmailListSubscription method to track if a customer has subscribed to an email list.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackEmailListSubscription(email, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackEmailListSubscription(email, optionalAttr, true);

Unsubscribe from emails

Use the trackEmailListUnsubscription method to track if a customer has unsubscribed from an email list.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackEmailListUnsubscription(email, true);

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackEmailListUnsubscription(email, optionalAttr, true);

Initialize a subscription

Use the trackSubscriptionInitialization method to track if a customer has started a subscription.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackSubscriptionInitialization(
                subscriptionState,   // subscription state
                cycleType,           // type of subscription period (Ex: weekly, yearly etc)
                cycleLength,         // length of subscription period
                subscriptionType,    // type of subscription (generally the title)
                price,               // cost of subscription for selected period
                startDate,           // subscription activation date (in millis)
                true);

If subscription state is subscriptionState.START or subscriptionState.UPGRADEevent, the SDK triggers subscription_upgrade. If the state is subscriptionState.DOWNGRADE, the SDK triggers subscription_downgrade.

If you want your app to pass additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackSubscriptionInitialization(
                subscriptionState,   // subscription state
                cycleType,           // type of subscription period (Ex: weekly, yearly etc)
                cycleLength,         // length of subscription period
                subscriptionType,    // type of subscription (generally the title)
                price,               // cost of subscription for selected period
                startDate,           // subscription activation date (in millis)
                optionalAttr,
                true);

Pause a subscription

Use the trackSubscriptionPause method to track if a customer has paused a subscription.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackSubscriptionPause(true)

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackSubscriptionPause(optionalAttr, true)

Resume a subscription

Use the trackSubscriptionUnpause method to track if a customer resumes a subscription.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackSubscriptionUnpause(true)

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackSubscriptionUnpause(optionalAttr, true)

Cancel a subscription

Use the trackSubscriptionCancel method to track if a customer cancels a subscription.

Here's how to use it:

Blueshift
        .getInstance(mContext)
        .trackSubscriptionCancel(true)

If you want your app to send additional parameters, here's how to do it:

HashMap optionalAttr = new HashMap<>();
// .. fill in optional attributes .. //

Blueshift
        .getInstance(mContext)
        .trackSubscriptionCancel(optionalAttr, true)

Events that the SDK tracks out-of-the-box

In addition, the SDK tracks the following events natively.

App open

The SDK can automatically fire an app_open event of every app start (from the killed state). This can be enabled using the below method.

configuration.setEnableAutoAppOpenFiring(true)

From v3.1.9 onwards, the default behavior is to fire one automatic app_open event in 24 hours. To change this time interval, please use the method below.

configuration.setAutoAppOpenInterval(seconds);

You can use the following method from the SDK in your code to track the app event manually:

Blueshift.getInstance(context).trackAppOpen(true);

You can use the following method to track the App Open event manually with additional parameters:

HashMap<String, Object> additionalParams = new HashMap<>();
/** fill values inside additionalParams **/

Blueshift.getInstance(context).trackAppOpen(additionalParams, canBatchThisEvent);

📘

Note

If you use the above two methods to track the app open event and if you enable the automatic tracking using the first method, the SDK fires the tracking method twice.

Notifications

These events enable accurate tracking and statistics around push notifications. If the application uses different frameworks or methods to render push notifications, implement the methods below to ensure accurate tracking of push notifications.

Notification view
This method is called when a push message is received and a notification is displayed to your customer. 

Blueshift.getInstance(context).trackNotificationView(message);

Notification click
This method is called when a customer taps on the notification or on the action button on the notification. 

Blueshift.getInstance(context).trackNotificationClick(message);

Notification - app open
This method is called when a customer taps on the notification to open a page in the application.

Blueshift.getInstance(context).trackNotificationPageOpen(message);

Notification - dismiss alert
This method is called when a customer taps on the dismiss button of a dialog type notification. 

Blueshift.getInstance(context).trackAlertDismiss(message, false);

App install & App update

App Install

When you launch your app for the very first time after installation, the Blueshift SDK recognizes this as a new app install and automatically fires an app_install event to Blueshift.

App Update

The Blueshift SDK keeps track of your app's version. When you open the app after a successful update, the SDK detects the change in version and fires an app_update event to Blueshift. Additionally, the SDK includes the previous app version as part of this event data, labeled as previous_app_version.

FAQs

  • What happens if my app is updated from a version that didn't have the Blueshift SDK integrated?

    • Since no previous version information is stored, the SDK won't be able to detect the version change. In this scenario, the event will be treated as an app install and an app_install event will be fired.

  • What happens if my app is updated from a version with an older version of the Blueshift SDK?

    • The Blueshift SDK will search for traces of the older version, such as configuration files. If these remnants are found, the SDK will recognize this as an app update and fire an app_update event.

Updated 5 months ago