Docs

Using Piwik PRO SDK

It is recommended to use TrackHelper class. It has methods for all common actions, which can be chained in a way that facilitates the correct order and use. Combine it with IDE autocompletion and using the SDK will be more convenient.

For tracking each event with TrackHelper, you will need to pass Tracker instance. The way of getting the correct Tracker instance depends on the configuration option (see Getting started):

  1. Your Android Application class extend PiwikApplication class
Tracker tracker = ((PiwikApplication) getApplication()).getTracker();
val tracker: Tracker = (application as PiwikApplication).tracker
  1. You manage the Tracker yourself
Tracker tracker = ((YourApplication) getApplication()).getTracker();
val tracker: Tracker = (application as YourApplication).tracker

In further examples we will assume usage of the first option.

Data anonymization

Anonymization is the feature that allows tracking a user's activity for aggregated data analysis even if the user doesn't consent to track the data. If a user does not agree to be tracked, he will not be identified as the same person across multiple sessions.

Personal data will not be tracked during the session (user ID, email and device ID). If the anonymization is enabled, a new visitor ID will be created each time the application starts.

Anonymization is enabled by default.

You can turn the anonymization on and off using the setAnonymizationState method:

((PiwikApplication) getApplication()).getTracker().setAnonymizationState(false);
(application as PiwikApplication).tracker.setAnonymizationState(false)

You can also check the anonymization status using the isAnonymizationOn method:

((PiwikApplication) getApplication()).getTracker().isAnonymizationOn();
(application as PiwikApplication).tracker.isAnonymizationOn()

Tracking screen views

Requires Analytics

During a valid tracking session, you can track screen views which represent the content the user is viewing in the application. To send a visit on the screen, set the screen path and title on the tracker. This path is internally translated by the SDK to an HTTP URL as the Piwik PRO server uses URLs for tracking views. Additionally, Piwik PRO SDK uses prefixes which are inserted in a generated URL for various types of action(s). For tracking screen views it will use a prefix screen by default, however, automatic prefixing can be disabled with the tracker.setPrefixing(false) option.

public class YourActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Tracker tracker = ((PiwikApplication) getApplication()).getTracker();
        TrackHelper.track().screen("your_activity_path").with(tracker);
    }
}
class YourActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val tracker: Tracker = (application as PiwikApplication).tracker
        TrackHelper.track().screen("your_activity_path").with(tracker)
    }
}
  • A path (required) - each screen should be mapped to the URL path

Warning: The title method is deprecated and will soon be removed. We recommend not to use it.

  • A title (optional) - the title of the action being tracked.

To automatically use the activity-stack as a path and activity title as a name, use the overloaded screen method:

public class YourActivity extends Activity {
   ...
   TrackHelper.track().screen(YourActivity).with(tracker);
   ...
}
class YourActivity : Activity() {
   ...
   TrackHelper.track().screen(YourActivity::class.java).with(tracker)
   ...
}
  • An activity (required) - current instance of android Activity class.

In order to bind the tracker to your applications, use the screens method. This method will automatically track all open application activities(views) keeping the activity-stack as a path and activity title as the name:

TrackHelper.track().screens(getApplication()).with(tracker);
TrackHelper.track().screens(application).with(tracker)

Alternatively, it is also possible to define a list of views that will be sent with a single event:

TrackHelper.track().screens(Arrays.asList("android_test/test1", "android_test/test2")).with(tracker);
TrackHelper.track().screens(listOf("android_test/test1", "android_test/test2")).with(tracker)

Tracking custom events

Requires Analytics

To collect data about the user's interaction with the interactive components of the application, like a button presses or the use of a particular item in the game - use event method.

TrackHelper.track().event("category", "action").path("/main/actionScreen").name("label").value(1000f).with(tracker);
TrackHelper.track().event("category", "action").path("/main/actionScreen").name("label").value(1000f).with(tracker)

The track method allows the specification of the following parameters:

  • A category (required) - this String defines the event category. You may define event categories based on the class of user actions (e.g. clicks, gestures, voice commands), or you may define them based on the features available in your application (e.g. play, pause, fast forward, etc.).
  • An action (required) - this String defines the specific event action within the category specified. In the example, we are effectively saying that the category of the event is user clicks, and the action is a button click.
  • A name (optional) - this String defines a label associated with the event. For example, if you have multiple button controls on a screen, you may use the label to specify the specific view control identifier that was clicked.
  • A value (optional) - this Float defines a numerical value associated with the event. For example, if you were tracking "Buy" button clicks, you may log the number of items being purchased or their total cost.
  • A path (optional) - the path under which this event occurred.

For more resources, please visit:

Tracking exceptions

Requires Analytics

Caught exceptions are errors in your app for which you've defined an exception handling code, such as the occasional timeout of a network connection during a request for data. Exceptions are tracked on the server in a similar way as screen views.

If you provide caught exception to the exception method, URL will contain the package name, activity path, method name and line number where crash occurred. Measure a caught exception by setting the exception field values on the tracker and sending the hit, as with this example:

try {
   // perform action
} catch(Exception ex) {
   TrackHelper.track().exception(ex).description("Content download error").with(tracker);
}
try {
   // perform action
} catch (ex: Exception) {
   TrackHelper.track().exception(ex).description("Content download error").with(tracker)
}
  • An exception (optional) - Caught exception instance.
  • A description (optional) - additional information about the issue.

Bear in mind that Piwik is not a crash tracker therefore use this sparingly.

Tracking social interactions

Requires Analytics

Social interactions such as likes, shares and comments in various social networks can be tracked as below.

TrackHelper.track().socialInteraction("Like", "Facebook").with(tracker);
TrackHelper.track().socialInteraction("Like", "Facebook").with(tracker)
  • An interaction (required) - defines the social interaction, e.g. "Like".
  • A network (required) - defines social network associated with interaction, e.g. "Facebook"

Tracking deep links and campaigns

Requires Analytics

Tracking campaigns URLs configured with the online Campaign URL Builder tool, allow you to measure how different campaigns (for example with Facebook ads or direct emails) bring traffic to your application. For this purpose you may use a deep link with the campaign parameters. You can track these URLs from the application via the campaign method:

TrackHelper.track().campaign("https://www.example.com?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore");
TrackHelper.track().campaign("https://www.example.com?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore")
  • A URL (required) - the campaign URL. The URL must contain campaign name and keyword parameters.

The information contained in the campaign URL or the deep link will be tracked when the first screen event is triggered.

Tracking downloads

Requires Analytics

You can track the installations initiated by your application.

TrackHelper.track().sendDownload("http://your.server.com/bonusmap.zip").with(getTracker());
TrackHelper.track().sendDownload("http://your.server.com/bonusmap.zip").with(tracker)
  • A URL (required) - the URL of the downloaded content.

No prefixes are used for tracking downloads, but each event of this type use an additional parameter download whose value equals to specified URL. On the analytics panel, all downloads can be viewed in the corresponding section.

Tracking application installs

Requires Analytics

You can also track installations of your application. This event is sent to the server only once per application installation.

TrackHelper.track().sendApplicationDownload().with(getTracker());
TrackHelper.track().sendApplicationDownload().with(tracker)

Application installation is only tracked during the first launch. In the case of the application being installed but not run, the app installation will not be tracked.

Tracking outlinks

Requires Analytics

For tracking outlinks to external websites or other apps opened from your application use the outlink method:

TrackHelper.track().outlink("yourScheme://address.app").with(getTracker());
TrackHelper.track().outlink("yourScheme://address.app").with(tracker)
  • A outlink (required) - defines the outlink target.

Tracking search operations

Requires Analytics

Tracking search operations allow the measurement of popular keywords used for various search operations performed inside your application. It can be done via the search method:

TrackHelper.track().search("Space").category("Movies").count(3).with(getTracker());
TrackHelper.track().search("Space").category("Movies").count(3).with(tracker)
  • A keyword (required) - the searched query that was used in the app.
  • A category (optional) - specify a search category.
  • A count (optional) - we recommend setting the search count to the number of search results displayed on the results page. When keywords are tracked with a count of 0, they will appear in the "No Result Search Keyword" report.

Tracking content impressions and interactions

Requires Analytics

You can track an impression of an ad in your application as below.

TrackHelper.track().impression("Android content impression").piece("banner").target("https://www.dn.se/").with(getTracker());
TrackHelper.track().impression("Android content impression").piece("banner").target("https://www.dn.se/").with(tracker)

When the user interacts with the ad by tapping on it, you can also track it with a similar method:

TrackHelper.track().interaction("Android content impression", "click").piece("banner").target("https://www.dn.se/").with(getTracker());
TrackHelper.track().interaction("Android content impression", "click").piece("banner").target("https://www.dn.se/").with(tracker)
  • A contentName (required) - the name of the content, e.g. "Ad Foo Bar".
  • A interaction (required) - type of interaction, e.g. click.
  • A piece (optional) - the actual content. For instance, the path to an image, video, audio or any text.
  • A target (optional) - the target of the content. For instance the URL of a landing page.

Tracking goals

Requires Analytics

By default, goals are defined as "matching" parts of the screen path or screen title. If you want to trigger a conversion manually or track some user interaction, call the method goal. Read more about what a goal is in the Help Center.

TrackHelper.track().goal("27ecc5e3-8ae0-40c3-964b-5bd8ee3da059").revenue(revenue).with(tracker);
TrackHelper.track().goal("27ecc5e3-8ae0-40c3-964b-5bd8ee3da059").revenue(revenue).with(tracker)
  • A goal (required) - a tracking request will trigger a conversion for the goal of the website being tracked with this ID.
  • Revenue (optional) - a monetary value that has been generated as revenue by goal conversion.

Create, view or manage goals is available in the Analytics tab, "Goals" left menu, "Manage goals" section.

Tracking e-commerce product detail view

Tracks action of viewing product page.

EcommerceProducts products = new EcommerceProducts();
HashMap<Integer, String> customDimensions = new HashMap<Integer, String>();
customDimensions.put(1, "coupon-2020");
customDimensions.put(2, "20%");
products.addProduct(new EcommerceProducts.Product("craft-311")
                .name("Unicorn Iron on Patch")
                .category(new String[]{"Crafts & Sewing", "Toys"})
                .price("49.90")
                .quantity(3)
                .brand("DMZ")
                .variant("blue")
                .customDimensions(customDimensions));
TrackHelper.track().ecommerceProductDetailView(products).with(tracker);
val products = EcommerceProducts()
val customDimensions = HashMap<Int, String>()
customDimensions[1] = "coupon-2020"
customDimensions[2] = "20%"
products.addProduct(EcommerceProducts.Product("craft-311")
    .name("Unicorn Iron on Patch")
    .category(arrayOf("Crafts & Sewing", "Toys"))
    .price("49.90")
    .quantity(3)
    .brand("DMZ")
    .variant("blue")
    .customDimensions(customDimensions))
TrackHelper.track().ecommerceProductDetailView(products).with(tracker)
  • A products (required) - list of product representations. Expected attributes of each product:
  • sku (required) - product stock-keeping unit
  • name (optional) - product name (default: "")
  • category (optional) - product category or an array of up to 5 categories (default: "")
  • price (optional) - product price (default: 0)
  • quantity (optional) - product quantity (default: 1)
  • brand (optional) - product brand (default: "")
  • variant (optional) - product variant (default: "")
  • customDimensions (optional) - product custom dimensions. Max 20 product custom dimensions, 20 is max ID. (default: )

Tracking e-commerce add to cart

Tracks action of adding products to a cart.

EcommerceProducts products = new EcommerceProducts();
HashMap<Integer, String> customDimensions = new HashMap<Integer, String>();
customDimensions.put(1, "coupon-2020");
customDimensions.put(2, "20%");
products.addProduct(new EcommerceProducts.Product("craft-311")
                .name("Unicorn Iron on Patch")
                .category(new String[]{"Crafts & Sewing", "Toys"})
                .price("49.90")
                .quantity(3)
                .brand("DMZ")
                .variant("blue")
                .customDimensions(customDimensions));
TrackHelper.track().ecommerceAddToCart(products).with(tracker);
val products = EcommerceProducts()
val customDimensions = HashMap<Int, String>()
customDimensions[1] = "coupon-2020"
customDimensions[2] = "20%"
products.addProduct(EcommerceProducts.Product("craft-311")
    .name("Unicorn Iron on Patch")
    .category(arrayOf("Crafts & Sewing", "Toys"))
    .price("49.90")
    .quantity(3)
    .brand("DMZ")
    .variant("blue")
    .customDimensions(customDimensions))
TrackHelper.track().ecommerceAddToCart(products).with(tracker)
  • A products (required) - list of product representations. Expected attributes of each product:
  • sku (required) - product stock-keeping unit
  • name (optional) - product name (default: "")
  • category (optional) - product category or an array of up to 5 categories (default: "")
  • price (optional) - product price (default: 0)
  • quantity (optional) - product quantity (default: 1)
  • brand (optional) - product brand (default: "")
  • variant (optional) - product variant (default: "")
  • customDimensions (optional) - product custom dimensions. Max 20 product custom dimensions, 20 is max ID. (default: )

Tracking e-commerce remove from cart

Tracks action of removing a product from a cart.

EcommerceProducts products = new EcommerceProducts();
HashMap<Integer, String> customDimensions = new HashMap<Integer, String>();
customDimensions.put(1, "coupon-2020");
customDimensions.put(2, "20%");
products.addProduct(new EcommerceProducts.Product("craft-311")
                .name("Unicorn Iron on Patch")
                .category(new String[]{"Crafts & Sewing", "Toys"})
                .price("49.90")
                .quantity(3)
                .brand("DMZ")
                .variant("blue")
                .customDimensions(customDimensions));
TrackHelper.track().ecommerceRemoveFromCart(products).with(tracker);
val products = EcommerceProducts()
val customDimensions = HashMap<Int, String>()
customDimensions[1] = "coupon-2020"
customDimensions[2] = "20%"
products.addProduct(EcommerceProducts.Product("craft-311")
    .name("Unicorn Iron on Patch")
    .category(arrayOf("Crafts & Sewing", "Toys"))
    .price("49.90")
    .quantity(3)
    .brand("DMZ")
    .variant("blue")
    .customDimensions(customDimensions))
TrackHelper.track().ecommerceRemoveFromCart(products).with(tracker)
  • A products (required) - list of product representations. Expected attributes of each product:
  • sku (required) - product stock-keeping unit
  • name (optional) - product name (default: "")
  • category (optional) - product category or an array of up to 5 categories (default: "")
  • price (optional) - product price (default: 0)
  • quantity (optional) - product quantity (default: 1)
  • brand (optional) - product brand (default: "")
  • variant (optional) - product variant (default: "")
  • customDimensions (optional) - product custom dimensions. Max 20 product custom dimensions, 20 is max ID. (default: )

Tracking e-commerce cart update

Tracks current state of a cart.

EcommerceProducts products = new EcommerceProducts();
HashMap<Integer, String> customDimensions = new HashMap<Integer, String>();
customDimensions.put(1, "coupon-2020");
customDimensions.put(2, "20%");
products.addProduct(new EcommerceProducts.Product("craft-311")
                .name("Unicorn Iron on Patch")
                .category(new String[]{"Crafts & Sewing", "Toys"})
                .price("49.90")
                .quantity(3)
                .brand("DMZ")
                .variant("blue")
                .customDimensions(customDimensions));
TrackHelper.track().ecommerceCartUpdate(products, "60000.78").with(tracker);
val products = EcommerceProducts()
val customDimensions = HashMap<Int, String>()
customDimensions[1] = "coupon-2020"
customDimensions[2] = "20%"
products.addProduct(EcommerceProducts.Product("craft-311")
    .name("Unicorn Iron on Patch")
    .category(arrayOf("Crafts & Sewing", "Toys"))
    .price("49.90")
    .quantity(3)
    .brand("DMZ")
    .variant("blue")
    .customDimensions(customDimensions))
TrackHelper.track().ecommerceCartUpdate(products, "60000.78").with(tracker)
  • A products (required) - list of product representations. Expected attributes of each product:
  • sku (required) - product stock-keeping unit
  • name (optional) - product name (default: "")
  • category (optional) - product category or an array of up to 5 categories (default: "")
  • price (optional) - product price (default: 0)
  • quantity (optional) - product quantity (default: 1)
  • brand (optional) - product brand (default: "")
  • variant (optional) - product variant (default: "")
  • customDimensions (optional) - product custom dimensions. Max 20 product custom dimensions, 20 is max ID. (default: )
  • grandTotal (required) - the total value of items in a cart

Tracking e-commerce order

Tracks conversion.

EcommerceProducts products = new EcommerceProducts();
HashMap<Integer, String> customDimensions = new HashMap<Integer, String>();
customDimensions.put(1, "coupon-2020");
customDimensions.put(2, "20%");
products.addProduct(new EcommerceProducts.Product("craft-311")
                .name("Unicorn Iron on Patch")
                .category(new String[]{"Crafts & Sewing", "Toys"})
                .price("49.90")
                .quantity(3)
                .brand("DMZ")
                .variant("blue")
                .customDimensions(customDimensions));
TrackHelper.track().ecommerceOrder("order-3415", "180.00", products).subTotal("120.00").tax("39.60").shipping("60.00").discount("18.00").with(tracker);
val products = EcommerceProducts()
val customDimensions = HashMap<Int, String>()
customDimensions[1] = "coupon-2020"
customDimensions[2] = "20%"
products.addProduct(EcommerceProducts.Product("craft-311")
    .name("Unicorn Iron on Patch")
    .category(arrayOf("Crafts & Sewing", "Toys"))
    .price("49.90")
    .quantity(3)
    .brand("DMZ")
    .variant("blue")
    .customDimensions(customDimensions))
TrackHelper.track().ecommerceOrder("order-3415", "180.00", products).subTotal("120.00").tax("39.60").shipping("60.00").discount("18.00").with(tracker)
  • A products (required) - list of product representations. Expected attributes of each product:
  • sku (required) - product stock-keeping unit
  • name (optional) - product name (default: "")
  • category (optional) - product category or an array of up to 5 categories (default: "")
  • price (optional) - product price (default: 0)
  • quantity (optional) - product quantity (default: 1)
  • brand (optional) - product brand (default: "")
  • variant (optional) - product variant (default: "")
  • customDimensions (optional) - product custom dimensions. Max 20 product custom dimensions, 20 is max ID. (default: )
  • orderId (required) - unique identifier of an order
  • grandTotal (required) - the total value of items in a cart
  • subTotal (optional) - total value of items in a cart without shipping
  • tax (optional) - total tax amount
  • shipping (optional) - total shipping cost
  • discount (optional) - total discount

Tracking ecommerce transactions

Requires Analytics

Warning: Deprecated since version 1.2.0: Older ecommerce API deprecated in favor of e-commerce V2. New API allows to track more actions (e.g. ecommerceAddToCart) and is easier to use.

If your organization depends on online sales, you need detailed analysis to transform raw e-commerce stats into actionable insights. Revenue, orders, conversion rates, and a host of other product statistics can be analyzed by integrating Piwik with your e-commerce solution.

SDK provides the order method that can be used for tracking the orders (including the order items). Sample usage:

Tracker tracker = ((PiwikApplication) getApplication()).getTracker();
EcommerceItems items = new EcommerceItems();
// EcommerceItems.Item("<sku>").name("<product>").category("<category>").price(<cents>).quantity(<number>)
items.addItem(new EcommerceItems.Item("0123456789012").name("Polo T-shirt").category("Men's T-shirts").price(3000).quantity(2));
items.addItem(new EcommerceItems.Item("0129876543210").name("Leather shoes").category("Shoes").price(40000).quantity(1));

TrackHelper.track().order("orderId",124144).subTotal(33110).tax(9890).shipping(1000).discount(0).items(items).with(tracker);
val tracker: Tracker = (application as PiwikApplication).tracker
val items = EcommerceItems()
// EcommerceItems.Item("<sku>").name("<product>").category("<category>").price(<cents>).quantity(<number>)
items.addItem(EcommerceItems.Item("0123456789012").name("Polo T-shirt").category("Men's T-shirts").price(3000).quantity(2))
items.addItem(EcommerceItems.Item("0129876543210").name("Leather shoes").category("Shoes").price(40000).quantity(1))

TrackHelper.track().order("orderId", 124144).subTotal(33110).tax(9890).shipping(1000).discount(0).items(items).with(tracker)
  • orderId (required) - a unique String identifying the order
  • grandTotal (required) - Total amount of the order, in cents
  • subTotal (optional) - the subTotal (net price) for the order, in cents
  • tax (optional) - the tax for the order, in cents
  • shipping (optional) - the shipping for the order, in cents
  • discount (optional) - the discount for the order, in cents
  • items (optional) - the items included in the order, use the EcommerceItems class to instantiate items

Tracking custom variables

The feature will soon be disabled. We recommend using custom dimensions instead.

Requires Analytics

A custom variable is a custom name-value pair that you can assign to your users or screen views, and then visualize the reports of how many visits, conversions, etc. for each custom variable. A custom variable is defined by a name - for example, "User status" - and a value - for example, "LoggedIn" or "Anonymous". It is required for names and values to be encoded in UTF-8.

Each custom variable has a scope. There are two types of custom variables scope - visit scope and screen scope. The visit scope can be used for any tracking action, and the screen scope can only be applied to tracking screen views.

To set the custom variable of the screen scope, use the variable method in the tracking chain:

TrackHelper.track()
       .variable(1, "filter", "price")
       .variable(2, "language", "en");

TrackHelper.track()
       .screen("/custom_vars")
       .title("Custom Vars")
       .with(getTracker());
TrackHelper.track()
       .variable(1, "filter", "price")
       .variable(2, "language", "en")

TrackHelper.track()
       .screen("/custom_vars")
       .title("Custom Vars")
       .with(tracker)

When screen custom variable is set and the screen event is called, the screen custom variable will be removed from the list of screen custom variables. The above code can also be written in the following way.

TrackHelper.track()
       .variable(1, "filter", "price")
       .variable(2, "language", "en")
       .screen("/custom_vars")
       .title("Custom Vars")
       .with(getTracker());
TrackHelper.track()
       .variable(1, "filter", "price")
       .variable(2, "language", "en")
       .screen("/custom_vars")
       .title("Custom Vars")
       .with(tracker)

To use the custom variable of the visit scope, use the visitVariables method in the tracking chain:

TrackHelper.track()
       .visitVariables(1, "filter", "price")
       .visitVariables(2, "language", "en");
TrackHelper.track()
       .event("category", "action")
       .with(tracker);
TrackHelper.track()
       .visitVariables(1, "filter", "price")
       .visitVariables(2, "language", "en")
TrackHelper.track()
       .event("category", "action")
       .with(tracker)

In contrast to the screen custom variables, the visit custom variable will not be removed when the event is called.

Please note that the Default custom variables option is enabled by default. With this option turned on, use the custom variables with indexes greater than 3 or the visit scope custom variables with indexes 1-3.

In case you don't need the default custom variable, you can disable it. See the Default custom variables section in Advanced usage.

Custom variable is defined by three parameters:

  • An index (required) - a given custom variable name must always be stored in the same "index" per session. For example, if you choose to store the variable name = "Gender" in index = 1 and you record another custom variable in index = 1, then the "Gender" variable will be deleted and replaced with a new custom variable stored in index 1.
  • A name (required) - this String defines the name of a specific Custom Variable such as "User type" (Limited to 200 characters).
  • A value (required) - this String defines the value of a specific Custom Variable such as "Customer" (Limited to 200 characters).

Tracking custom dimensions

Requires Analytics

To track a custom name-value pair assigned to your users or screen views, use Custom Dimensions. Note that the custom value data is not sent by itself, but only with other tracking actions such as screen views, events or other tracking action:

TrackHelper.track()
       .dimension(1, "visit")
       .dimension(2, "dashboard")
       .screen("Home screen")
       .with(tracker);
TrackHelper.track()
       .dimension(1, "visit")
       .dimension(2, "dashboard")
       .screen("Home screen")
       .with(tracker)

1 and 2 are our dimension slots and visit, dashboard are the dimension values for the tracked screen view.

TrackHelper.track()
       .dimension(1, "visit")
       .dimension(2, "billing");
TrackHelper.track()
       .event("category", "action")
       .with(tracker);
TrackHelper.track()
       .dimension(1, "visit")
       .dimension(2, "billing")
TrackHelper.track()
       .event("category", "action")
       .with(tracker)

1 and 2 are our dimension slots and visit, billing are the dimension values for the tracked event. The length of the custom dimension value can be 1024 characters.

Once the event is triggered, the dimensions are deleted and will not be sent with the next event. If you want to send dimensions with the next event, you must set them again.

Tracking user profile attributes

Requires Audience Manager

Warning: Audience Manager is deprecated and will be replaced by Customer Data Platform module. Learn more.

The Audience Manager stores visitors' profiles which have data from a variety of sources. One of them can be a mobile application. It is possible to enrich the profiles with more attributes by passing any key-value pair e.g. gender: male, favourite food: Italian, etc. It is recommended to set additional user identifiers such as email or User ID which will allow the enrichment of existing profiles or merging of profiles rather than creating a new profile. For example, if the user visited the website, performed some actions, filled in a form with his email (his data was tracked and profile created in Audience Manager) and started using a mobile application, the existing profile will be enriched only if the email was set. Otherwise, a new profile will be created.

For sending profile attributes use audienceManagerSetProfileAttribute method:

getTracker().setUserMail("[email protected]");
...
TrackHelper.track().audienceManagerSetProfileAttribute("food", "pizza").add("color", "green").with(getTracker());
tracker.userMail = "[email protected]"
...
TrackHelper.track().audienceManagerSetProfileAttribute("food", "pizza").add("color", "green").with(tracker)
  • A name (required) - defines the profile attribute name (non-null string).
  • A value (required) - defines the profile attribute value (non null string).
  • An add (chain method) - used to specify more attributes to the user within the same event.

Aside from attributes, each event also sends parameters which are retrieved from the tracker instance:

  • WEBSITE_ID - always sent,
  • USER_ID - if it is set,
  • EMAIL - if it is set,
  • VISITOR_ID - always sent, ID of the mobile application user, generated by SDK
  • DEVICE_ID - if it is set

Profile attributes for the user that are tracked will be shown on the Audience Manager - Profile Browser tab.

Audience manager events are dispatched together with analytics events. Therefore, settings set in the tracker for analytics events processing (dispatch interval, cache size and age, etc.) will be same for audience manager events. Once the audience manager event is dispatched, it is no longer stored locally.

Reading user profile attributes

Requires Audience Manager

Warning: Audience Manager is deprecated and will be replaced by Customer Data Platform module. Learn more.

It is possible to read the attributes of a given profile, however, with some limitations. Due to security reasons (to avoid personal data leakage), it is possible to read only attributes that were enabled for API access (whitelisted) in the Attributes section in Audience Manager. To get user profile attributes use the audienceManagerGetProfileAttributes method:

getTracker().audienceManagerGetProfileAttributes(new Tracker.OnGetProfileAttributes() {
    @Override
    public void onAttributesReceived(Map<String, String> attributes) {
        // handle result
    }

    @Override
    public void onError(String errorData) {
        errorData = TextUtils.isEmpty(errorData) ? "Network error": errorData;
        // handle error
    }
});
tracker.audienceManagerGetProfileAttributes(object : Tracker.OnGetProfileAttributes {
    override fun onAttributesReceived(attributes: Map<String, String>) {
        // handle result
    }

    override fun onError(errorData: String) {
        val error = if (errorData.isEmpty()) "Network error" else errorData
        // handle error
    }
})
  • An OnGetProfileAttributes (required) - callback to handle request result (call is asynchronous), has two methods void onAttributesReceived(Map<String, String> attributes) and void onError(String errorData).
  • An attributes (output) - dictionary of key-value pairs, where each pair represents the attribute name (key) and value.
  • An errorData (output) - in case of error, only this method will be called. The method passes the error string.

Checking audience membership

Requires Audience Manager

Warning: Audience Manager is deprecated and will be replaced by Customer Data Platform module. Learn more.

Audiences are allowed to check whether or not the user belongs to a specific group of users defined in the data manager panel based on analytics data and audience manager profile attributes. You can check if the user belongs to a given audience, for example, to show a special offer. To check it, use the checkAudienceMembership method:

getTracker().checkAudienceMembership(audienceId, new Tracker.OnCheckAudienceMembership() {
    @Override
    public void onChecked(boolean isMember) {
        // handle result
    }

    @Override
    public void onError(String errorData) {
        // handle error
    }
});
tracker.checkAudienceMembership(audienceId, object : Tracker.OnCheckAudienceMembership {
    override fun onChecked(isMember: Boolean) {
        // handle result
    }

    override fun onError(errorData: String) {
        // handle error
    }
})
  • An audienceId (required) - ID of the audience (Audience Manager -> Audiences tab)
  • An OnCheckAudienceMembership (required) - callback to handle request result (call is asynchronous), has two methods void onChecked(boolean isMember) and void onError(String errorData)
  • An isMember (output) - a boolean value that indicates if user belongs to audience with given ID
  • An errorData (output) - in case of error, only this method will be called. The method passes the error string.

Updated 15 days ago