Object Oriented Tracking

You can track pages regardless of whether auto-tracking is enabled or disabled. If auto-tracking is disabled, only the screens explicitly marked for tracking with the following methods will be tracked.

You will find tracked pages under Navigation > Pages > Pages.

Methods

Example

private fun trackCustomPage() {

	// Specify page properties
	val params = mapOf(20 to "cp20 page parameter value")
	val categories = mapOf(10 to "cg10 page category value")
	val searchTerm = "the search term value"
	val pageParameters =
		PageParameters(parameters = params, pageCategory = categories, search = searchTerm)

	// Create PageViewEvent
	val pageEvent = PageViewEvent(name = "the custom name of page")
	pageEvent.pageParameters = pageParameters

	// Send request to server
	Webtrekk.getInstance().trackPage(pageEvent)
}

public void onClick(View view) {
	// Specify page properties
	Map<Integer, String> params = new HashMap<>();
		params.put(20, "cp20 page parameter value");

	Map<Integer, String> categories = new HashMap<>();
		categories.put(10, "cg10 page category value");

	String searchTerm = "the search term value";
	PageParameters pageParameters =
		new PageParameters(params, searchTerm, categories);

	// Create PageViewEvent
	PageViewEvent pageEvent = new PageViewEvent("The custom name of page");
		pageEvent.setPageParameters(pageParameters);

	// Send request to server
	Webtrekk.getInstance().trackPage(pageEvent);

Event or action tracking can be performed with or without auto-tracking. You can also track custom events, even if auto-tracking is enabled, since trackCustomEvent()  does not depend on the activity/fragment context.

You will find tracked events under Navigation > Events.

Methods

Example

private fun trackAction() {
	
	// Specify event parameters
    val eventParameters = mapOf(20 to "ck20 parameter value")

	// Create the action event
	val event = ActionEvent("name of the event")
	event.eventParameters = eventParameters

	// Send the event to the server
	Webtrekk.getInstance().trackAction(event)
}

 public void onClick(View view) {
                
	// Specify event parameters
	Map<Integer, String> eventParam = new HashMap<>();
		eventParam.put(1, "event param 1");

	EventParameters eventParameters = new EventParameters();
		eventParameters.setCustomParameters(eventParam);

	// Create the action event
	ActionEvent actionEvent = new ActionEvent("custom action name");
		actionEvent.setEventParameters(eventParameters);
               
	// Send request to server
	Webtrekk.getInstance().trackAction(actionEvent);
}

You can analyze detailed product interactions in your app. This includes tracking when products are viewed, added to the cart, and purchased. You can also analyze abandoned shopping carts and track the completion of orders with comprehensive information.

Supported Product Statuses

The status of a product is required to ensure that tracking and e-commerce use cases function correctly. The Mapp Android SDK supports the following statuses:

• VIEWED: (Default) Tracks when a user views a product.

• ADDED_TO_BASKET: Tracks when a user adds a product to the shopping cart.

• DELETED_FROM_BASKET: Tracks when a product is removed from the shopping cart.

• PURCHASED: Tracks when a product is purchased.

• ADDED_TO_WISHLIST: Tracks when a product is added to a wishlist.

• DELETED_FROM_WISHLIST: Tracks when a product is removed from a wishlist.

• CHECKOUT: Tracks the checkout process when a user starts the checkout.

Key Information for Product and Order Tracking:

• You can add detailed information to products and orders using e-commerce parameters. Parameter constants only work for query-based tracking.

• The status of a product must be set correctly to ensure that all tracking works as expected for Mapp Intelligence e-commerce use cases.

Example

// Track products viewed
private fun trackEcommerceViewProduct() {

	// Create product object
	val product = ProductParameters()
		product.name = "Product1"
		product.categories = mapOf(Pair(1, "ca1 product category parameter value"), Pair(2, "ca2 product category parameter value"))
		product.cost = 13

	// Create e-commerce object
	val ecommerceParameters = ECommerceParameters(
		customParameters = mapOf(
			1 to "cb1 e-commerce parameter value",
			2 to "cb2 e-commerce parameter value"
		)
	)

	// Set status to viewed and add product information
	ecommerceParameters.status = ECommerceParameters.Status.VIEWED
		ecommerceParameters.products = listOf(product)

	// Create PageViewEvent or ActionEvent
	val pageEvent = PageViewEvent(name = "TrackProductView")
		pageEvent.eCommerceParameters = ecommerceParameters

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent)
}

// Track products added to basket
private fun trackEcommerceAddedToBasket() {

	// Create product object
	val product = ProductParameters()
	product.name = "Product1"
	product.categories = mapOf(Pair(1, "ca1 product category parameter value"), Pair(2, "ca2 product category parameter value"))
	product.cost = 13
	product.quantity = 2

	//Create e-commerce object
	val ecommerceParameters = ECommerceParameters(
		customParameters = mapOf(
			1 to "cb1 e-commerce parameter value",
			2 to "cb2 e-commerce parameter value"
		)
	)

	// Set product status to added_to_basket and add product information
	ecommerceParameters.status = ECommerceParameters.Status.ADDED_TO_BASKET
	ecommerceParameters.products = listOf(product)

	// Create PageViewEvent or ActionEvent
	val pageEvent = PageViewEvent(name = "TrackProductBasket")
	pageEvent.eCommerceParameters = ecommerceParameters

	// Send request		
	Webtrekk.getInstance().trackPage(pageEvent)
}

// Track order confirmation
private fun trackEcommerceConfirmation() {

	// Create product object
	val product = ProductParameters()
	product.name = "Product1"
	product.categories = mapOf(Pair(1, "ca1 product category parameter value"), Pair(2, "ca2 product category parameter value"))
	product.cost = 13
	product.quantity = 2

	// Create e-commerce object
	val ecommerceParameters = ECommerceParameters(
		customParameters = mapOf(
			1 to "cb1 e-commerce parameter value",
			2 to "cb2 e-commerce parameter value"
		)
	)
    
	// Add order information and set status to purchased
	ecommerceParameters.products = listOf(product)
	ecommerceParameters.currency = "EUR"
	ecommerceParameters.orderID = "1234nb5"
	ecommerceParameters.paymentMethod = "Credit Card"
	ecommerceParameters.shippingServiceProvider = "DHL"
	ecommerceParameters.shippingSpeed = "express"
	ecommerceParameters.shippingCost = 20
	ecommerceParameters.couponValue = 10
	ecommerceParameters.orderValue = 23
	ecommerceParameters.status = ECommerceParameters.Status.PURCHASED

	// Create PageViewEvent or ActionEvent
	val pageEvent = PageViewEvent(name = "TrackProductConfirmed")
		pageEvent.eCommerceParameters = ecommerceParameters

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent)
}

// Track products viewed
public void onClick(View view) {
	
	// Create product object
	Map<Integer, String> productCategories = new HashMap<>();
	productCategories.put(1, "ca1 product category parameter value");
	productCategories.put(2, "ca2 product category parameter value");

	ProductParameters productParameters = new ProductParameters();
	productParameters.setCategories(productCategories);
	productParameters.setCost(13);
	productParameters.setName("product name");

	List products = new LinkedList();
	products.add(productParameters);

	// Create e-commerce object
	Map<Integer, String> customEcommerceParams = new HashMap<>();
	customEcommerceParams.put(1, "cb1 e-commerce parameter value");
	customEcommerceParams.put(2, "cb2 e-commerce parameter value");

	ECommerceParameters eCommerceParameters = new ECommerceParameters();
	eCommerceParameters.setProducts(products);
	eCommerceParameters.setCustomParameters(customEcommerceParams);

	// Set status to viewed
	eCommerceParameters.setStatus(ECommerceParameters.Status.VIEWED);

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("The object tracking page");
	pageEvent.setECommerceParameters(eCommerceParameters);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

// Track product added to basket
public void onClick(View view) {

	// Create product object
	Map<Integer, String> productCategories = new HashMap<>();
	productCategories.put(1, "ca1 product category parameter value");
	productCategories.put(2, "ca2 product category parameter value");

	ProductParameters productParameters = new ProductParameters();
	productParameters.setCategories(productCategories);
	productParameters.setCost(13);
	productParameters.setName("product name");
	productParameters.setQuantity(2);

	List products = new LinkedList();
	products.add(productParameters);

	// Create e-commerce object
	Map<Integer, String> customEcommerceParams = new HashMap<>();
	customEcommerceParams.put(1, "cb1 e-commerce parameter value");
	customEcommerceParams.put(2, "cb2 e-commerce parameter value");

	ECommerceParameters eCommerceParameters = new ECommerceParameters();
	eCommerceParameters.setProducts(products);
	eCommerceParameters.setCustomParameters(customEcommerceParams);

	// Set status to added_to_basket
	eCommerceParameters.setStatus(ECommerceParameters.Status.ADDED_TO_BASKET);

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("TrackProductBasket");
	pageEvent.setECommerceParameters(eCommerceParameters);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

// Track order confirmation
public void onClick(View view) {

	// Create product object
	Map<Integer, String> productCategories = new HashMap<>();
	productCategories.put(1, "ca1 product category parameter value");
	productCategories.put(2, "ca2 product category parameter value");

	ProductParameters productParameters = new ProductParameters();
	productParameters.setCategories(productCategories);
	productParameters.setCost(13);
	productParameters.setName("product name");
	productParameters.setQuantity(2);

	List products = new LinkedList();
	products.add(productParameters);

	// Create e-commerce object
	Map<Integer, String> customEcommerceParams = new HashMap<>();
	customEcommerceParams.put(1, "cb1 e-commerce parameter value");
	customEcommerceParams.put(2, "cb2 e-commerce parameter value");

	ECommerceParameters eCommerceParameters = new ECommerceParameters();
	eCommerceParameters.setProducts(products);
	eCommerceParameters.setCustomParameters(customEcommerceParams);

	// Add order information and set status to purchased
	eCommerceParameters.setStatus(ECommerceParameters.Status.PURCHASED);
	eCommerceParameters.setCurrency("EUR");
	eCommerceParameters.setOrderID("1234nb5");
	eCommerceParameters.setOrderValue(23);
	eCommerceParameters.setPaymentMethod("Credit Card");
	eCommerceParameters.setShippingCost(20);
	eCommerceParameters.setCouponValue(10);
	eCommerceParameters.setShippingServiceProvider("DHL");
	eCommerceParameters.setShippingSpeed("express");

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("TrackProductConfirmed");
	pageEvent.setECommerceParameters(eCommerceParameters);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

You can track goal achievements using page or event requests in Mapp Intelligence, allowing you to evaluate which campaigns led to conversions. Learn more about how to define goals in Mapp Q3 here.
Further information about the analysis and use of website goals in Mapp Intelligence can be found in the training chapter Analysis of Goal Achievement.

You will find tracked pages under Marketing > Website Goals.

Example

private fun trackEcommerceGoal() {

	// Create e-commerce object with your specified goal
	val ecommerceParameters = ECommerceParameters(
		customParameters = mapOf(
			1 to "your e-commerce goal"
		)
	)

	// Create PageViewEvent or ActionEvent
	val pageEvent = PageViewEvent(name = "your custom page name")
	pageEvent.eCommerceParameters = ecommerceParameters

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent)
}

public void onClick(View view) {

	// Create e-commerce object with your specified goal
	Map<Integer, String> customEcommerceParams = new HashMap<>();
	customEcommerceParams.put(1, "your e-commerce goal");

	ECommerceParameters eCommerceParameters = new ECommerceParameters();
	eCommerceParameters.setCustomParameters(customEcommerceParams);
                
	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("your custom page name");
	pageEvent.setECommerceParameters(eCommerceParameters);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

In case you see errors, ensure that you imported the necessary libraries:

import webtrekk.android.sdk.ParamType;
import webtrekk.android.sdk.Webtrekk;
import static webtrekk.android.sdk.ParamTypeKt.createCustomParam;

Campaign tracking allows you to track the effectiveness of marketing campaigns. This is configured in Mapp Q3 (Configuration > Marketing Configuration).

Further information about campaigns can be found in the training chapter Campaign Configuration.

Campaigns can be tracked in both page and event requests.

Example

campaign.setOnClickListener {

	// Create a campaign object
	val campaignProperties = CampaignParameters("email.newsletter.nov2020.thursday") //set the campaign ID
	campaignProperties.mediaCode = "abc" //set this if your media code differs from the default (wt_mc)
	campaignProperties.oncePerSession = true //set this if you want to track the campaign only once within a session.
	campaignProperties.action = CampaignParameters.CampaignAction.VIEW //default is CLICK. Set to VIEW if you want to measure how often a user viewed your campaign.
	campaignProperties.customParameters = mapOf(12 to "camParam1") //add additional campaign parameters if needed.

	// Create a PageViewEvent or ActionEvent
	val event = PageViewEvent(name = "TestCampaign")
	event.campaignParameters = campaignProperties
	
	// Send request
	Webtrekk.getInstance().trackPage(event)
}

public void onClick(View view) {

	// Create campaign object
	Map<Integer, String> campaignParams = new HashMap<>();
	campaignParams.put(1,"campaign param value 1");

	CampaignParameters campaignObject = new CampaignParameters("email.newsletter.nov2020.thursday"); //set the campaign ID
	campaignObject.setMediaCode("abc"); //set this if your media code differs from the default (wt_mc)
	campaignObject.setOncePerSession(true); //set this if you want to track the campaign only once within a session.
	campaignObject.setAction(CampaignParameters.CampaignAction.VIEW); //default is CLICK. Set to VIEW if you want to measure how often a user viewed your campaign.
	campaignObject.setCustomParameters(campaignParams); //add additional campaign parameters if needed.

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("your custom page name");
	pageEvent.setCampaignParameters(campaignObject);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

You can enrich sessions with additional parameters. Depending on the settings in your account, the first or last value of the parameter will be used for analyses.

Session parameters can be tracked in both page and event requests.

Example

private fun trackCustomPage() {

	// Create session properties
	val sessionParameters = SessionParameters(parameters = mapOf(1 to "your session parameter value 1"))

	// Create PageViewEvent or ActionEvent
	val pageEvent = PageViewEvent(name = "the custom name of page")
	pageEvent.sessionParameters = sessionParameters

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent)
}

public void onClick(View view) {

	//Create session object
	Map<Integer, String> customSessionParameters = new HashMap<>();
	customSessionParameters.put(1, "your session parameter value 1");

	SessionParameters sessionObject = new SessionParameters();
	sessionObject.setParameters(customSessionParameters);

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("your custom page name");
	pageEvent.setSessionParameters(sessionObject);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

Predefined Session Parameter

Some session parameters can be preconfigured, including App version, App updated, and App first open. These parameters can be activated without needing to be defined in your mobile app, simplifying session tracking.

The following parameters are predefined in the SDK:

To configure the session parameter, proceed as follows:

1. Log in to your Mapp Q3 account.

2. Go to Configuration > Custom Parameters > Session parameters

3. Then click Create a new custom parameter. The specification dialog for the session parameter opens.

4. Make the following configuration:

   Parameter	Description
   Title	Mandatory. Enter the name of the session parameter.
   Description	Optional. Enter a description for the session parameter.
   Active	Select via the radio button whether the session parameter is active or inactive. When disabled, no data is collected.
   Preconfigured	Under "Preconfigured," select one of the following parameters: App updated App version App first open Preset settings apply automatically.
   Parameter ID	The ID is set automatically by the system.

5. Click Save to save your settings.

User tracking allows you to categorize users to improve analyses in Mapp Intelligence. You can transmit both pre-defined and custom categories for each user.

User data can be tracked in both page and event requests.

Recommendation

Transmit hashed personal data should not be evaluated in terms of content (e.g. with the SHA256 hash). If you would like to collect this data for analytical reasons, we suggest that you transmit the data in encrypted form (see How to Implement Server-Side Encryption in Mapp Intelligence).

Example

private fun trackCustomPage() {

	// Create user object
	val userCategories = UserCategories()

	// Create custom user categories
	userCategories.customCategories = mapOf(1 to "user category value 1")

	// Specify pre-defined categories
	userCategories.birthday = UserCategories.Birthday(day = 12, month = 1, year = 1993)
	userCategories.customerId = "CustomerID"
	userCategories.gender = UserCategories.Gender.FEMALE //possible values: FEMALE, MALE, UNKNOWN
	userCategories.emailReceiverId = "email receiver ID"
	userCategories.newsletterSubscribed = true //boolean

	// Create PageViewEvent or ActionEvent	
	val pageEvent = PageViewEvent(name = "the custom name of page")
	pageEvent.userCategories = userCategories

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent)
}

public void onClick(View view) {

	// Create custom user categories
	Map<Integer, String> urmCat = new HashMap<>();
	urmCat.put(1,"URM category value 1");

	// Create user category object
	UserCategories urmObject = new UserCategories();
	urmObject.setCustomCategories(urmCat);
	
	// Specify pre-defined categories
	urmObject.setBirthday(new UserCategories.Birthday(12,1,1993)); //day, month, year
	urmObject.setCustomerId("CustomerID");
	urmObject.setGender(UserCategories.Gender.FEMALE); //possible values: FEMALE, MALE, UNKNOWN
	urmObject.setEmailReceiverId("email receiver ID");
	urmObject.setNewsletterSubscribed(true); //boolean

	// Create PageViewEvent or ActionEvent
	PageViewEvent pageEvent = new PageViewEvent("your custom page name");
	pageEvent.setUserCategories(urmObject);

	// Send request
	Webtrekk.getInstance().trackPage(pageEvent);
}

The Media Tracking API allows you to track user interactions with media files, such as videos or audio, in your app. You can track events such as media play, pause, seek actions, and more. Media tracking provides insights into how users engage with your media content, including metrics like duration watched, position within the media, and interaction frequency.

You will find tracked media under Navigation > Media > Media.

Methods

trackMedia(
    mediaName: String,
              trackingParams: Map<String, String> = emptyMap()
)

Example

private fun trackMedia() {

    // Create media parameters
    val mediaProperties = MediaParameters("football123", action = "play", position = 12, duration = 240)

    // Create optional custom media categories
    mediaProperties.customCategories = mapOf(1 to "sports")

    // Create optional event parameter (ck)
    val eventParameters = EventParameters(mapOf(Pair(20, "sporthighlights")))

    // Create MediaEvent
    val mediaEvent = MediaEvent(pageName = "en.sports.football", parameters = mediaProperties).apply {
        eventParameters = eventParameters
    }

    // Send request
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

private void trackMedia() {

    // Create media parameters
    MediaParameters mediaProperties = new MediaParameters("football123", "play", 12, 240);

    // Create optional custom media categories
    mediaProperties.setCustomCategories(Collections.singletonMap(1, "sports"));

    // Create optional event parameter (ck)
    EventParameters eventParameters = new EventParameters(Collections.singletonMap(20, "sporthighlights"));

    // Create MediaEvent
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    mediaEvent.setEventParameters(eventParameters);

    // Send request
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

Media Tracking API Constraints

To ensure proper media tracking, certain constraints and expectations must be met:

Start a Media Session

A media session begins with an initial “play” or “init” call. Without this call, further interactions such as “pause” or “seek” cannot be tracked correctly. Ensure that the first action sent is either a play or init request to start the session.

Seeking Behavior

• When sending a seek action, the position sent should reflect the point in time where the seek started.

• After sending a seek request, you need to send either a play or pause action to resume tracking from the current position.

Example 1: Tracking a Play and Seek Action

Scenario: The user starts a video at position 8 seconds, seeks forward to position 20 seconds, and continues playing.

// Track the initial play
private fun trackMediaPlay() {
    val mediaProperties = MediaParameters("football123", action = "play", position = 8, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

// Track the seek action
private fun trackMediaSeek() {
    val mediaProperties = MediaParameters("football123", action = "seek", position = 8, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

// Track the play action after seek
private fun trackMediaResume() {
    val mediaProperties = MediaParameters("football123", action = "play", position = 20, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

Java:

// Track the initial play
private void trackMediaPlay() {
    MediaParameters mediaProperties = new MediaParameters("football123", "play", 8, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

// Track the seek action
private void trackMediaSeek() {
    MediaParameters mediaProperties = new MediaParameters("football123", "seek", 8, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

// Track the play action after seek
private void trackMediaResume() {
    MediaParameters mediaProperties = new MediaParameters("football123", "play", 20, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

Please note that Exo2Player changes a state to pause automatically after each seeks. You need to suppress that to be aligned with the API expectation manually.

Example 2: Tracking a Pause and Seek Action:

Scenario: The user pauses the video at 8 seconds, seeks forward to 20 seconds, but does not resume playing.

// Track the initial pause
private fun trackMediaPause() {
    val mediaProperties = MediaParameters("football123", action = "pause", position = 8, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

// Track the seek action
private fun trackMediaSeek() {
    val mediaProperties = MediaParameters("football123", action = "seek", position = 8, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

// Track the pause after seek
private fun trackMediaPausedAfterSeek() {
    val mediaProperties = MediaParameters("football123", action = "pause", position = 20, duration = 240)
    val mediaEvent = MediaEvent("en.sports.football", parameters = mediaProperties)
    Webtrekk.getInstance().trackMedia(mediaEvent)
}

Java:

// Track the initial pause
private void trackMediaPause() {
    MediaParameters mediaProperties = new MediaParameters("football123", "pause", 8, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

// Track the seek action
private void trackMediaSeek() {
    MediaParameters mediaProperties = new MediaParameters("football123", "seek", 8, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}

// Track the pause after seek
private void trackMediaPausedAfterSeek() {
    MediaParameters mediaProperties = new MediaParameters("football123", "pause", 20, 240);
    MediaEvent mediaEvent = new MediaEvent("en.sports.football", mediaProperties);
    Webtrekk.getInstance().trackMedia(mediaEvent);
}