Object Oriented Tracking

Pages

Page tracking is possible with both auto-tracking enabled and disabled. If auto-tracking is disabled, only the screens that are specifically marked for tracking with the given methods are tracked.

Methods

Method

Description

trackPage(
page: PageViewEvent
)

When using object-oriented tracking, you can create objects based on your use cases (e.g. page object containing all significant data of your page, product and order objects containing the data of your products and order, etc.) and the SDK converts it automatically into the Mapp Intelligence data model specification when sending the request to the server. We recommend object-oriented tracking for all customers who are not familiar with the Mapp Intelligence data model or implementing both the iOS SDKv5 and Android SDKv5.

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)
}

CODE

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);

CODE

Events

Event or action tracking is possible with both auto-tracking enabled or disabled. Measured actions are listed in the tool under Navigation > Events.

You can also track custom events. The tracking of custom events is possible while automatic tracking is enabled because trackCustomEvent() is not taking the activity/ fragment context.

Methods

Method	Description
trackAction( action: ActionEvent )	This option is recommended if you are not familiar with the Mapp Intelligence data model and API.

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)
}

JAVA

 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);
}

JAVA

Products and Orders

In Mapp Intelligence you can analyze in detail which products in your app are viewed, placed in the shopping cart, and bought. Aggregated evaluations are possible across product categories. Intelligence automatically derives abandoned shopping carts from the information transmitted. Comprehensive information must be provided on the underlying order for product purchases, e.g. a unique order number. Like orders, any additional information can be added to products using e-commerce parameters. Parameter constants only work for query-based tracking.

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)
}

CODE

// 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);
}

CODE

Goals

When using website goals, all central goals are quickly available for analyzing and filtering. Furthermore, the calculation of the customer journey is based on website goals. Thus, you can analyze for each website goal, which campaigns participated in the goal achievement. Goals can be sent as page or event requests.

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 .

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)
}

JAVA

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);
}

CODE

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;

Campaigns

Campaign tracking is configured in Mapp Q3 (Configuration > Marketing Configuration). Without this configuration, no campaign information will be collected.

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)
}

CODE

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);
}

CODE

Sessions

It is possible to enrich data to a particular session with additional parameters. Depending on the settings in your account, either the first or the last value of the parameter is taken into account for your 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)
}

CODE

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);
}

CODE

Pre-Defined Session Parameter

The prerequisite for tracking the default values (App version, App update, and App first open) is that you first create the necessary session parameters in Mapp Q3. Using pre-defined parameters, you do not need to create the parameters in your mobile application, just activate them in Mapp Q3 instead. This section describes how to create the appropriate parameters.

The following parameters are pre-defined in the SDK:

Parameter	Parameter ID	Description	Data Type	Amount Parameter Values	Calculation
App updated	815	When the end-user updates the app to a new version, it is tracked via this predefined session parameter.	Figure	Single value	The last value wins. This means only the last value of the transmitted parameter is counted per session.
App version	804	This parameter analyzes whether users are utilizing the latest version of your app.	Text	Single value	The last value wins. This means only the last value of the transmitted parameter is counted per session.
App first open	821	This parameter is tracked when the user opens the app for the first time after installing the mobile application from the Web or App Store.	Text	Single value	First value wins. This means only the first value of the transmitted parameter is counted per session.

To configure the session parameter, proceed as follows:

Log in to your Mapp Q3 account.
Go to Configuration > Custom Parameters > Session parameters
Then click Create a new custom parameter. The specification dialog for the session parameter opens.

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.

Click Save to save your settings.

Customers

Identifying customers or users is important to improve analyses of user behavior in your app, e.g. to identify returning visitors. It is also possible to further categorize customers to improve Intelligence results.

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

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.city = "Paris"
	userCategories.country = "France"
	userCategories.customerId = "CustomerID"
	userCategories.gender = UserCategories.Gender.FEMALE //possible values: FEMALE, MALE, UNKNOWN
	userCategories.emailAddress = "email address"
	userCategories.emailReceiverId = "email receiver ID"
	userCategories.firstName = "first name"
	userCategories.lastName = "last name"
	userCategories.newsletterSubscribed = true //boolean
	userCategories.phoneNumber = "phone number"
	userCategories.street = "street name"
	userCategories.streetNumber = "street number"
	userCategories.zipCode = "zip code"

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

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

CODE

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.setCity("Paris");
	urmObject.setCountry("France");
	urmObject.setCustomerId("CustomerID");
	urmObject.setGender(UserCategories.Gender.FEMALE); //possible values: FEMALE, MALE, UNKNOWN
	urmObject.setEmailAddress("email address");
	urmObject.setEmailReceiverId("email receiver ID");
	urmObject.setFirstName("first name");
	urmObject.setLastName("last name");
	urmObject.setNewsletterSubscribed(true); //boolean
	urmObject.setPhoneNumber("phone number");
	urmObject.setStreet("street name");
	urmObject.setStreetNumber("street number");
	urmObject.setZipCode("zip code");

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

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

CODE

Media Tracking

You can use our media tracking API to track user behavior on your media files.

Methods

Method

Description

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

Media name is required and should be unique on each video.

Tracking params contain all parameters, media, or custom.

Example

private fun trackMedia() {
	
	// Create the necessary media parameters
	val mediaProperties = MediaParameters("TestVideo", action = "play", position = 12, duration = 120)
	
	// Create optional custom media categorie
	mediaProperties.customCategories = mapOf(1 to "media category value 1")

	// Create optional event parameter (ck)
	val eventParameters = EventParameters(mapOf(Pair(20, "ck20ParamValue")))
	
	// Create MediaEvent
	val mediaEvent = MediaEvent(pageName = "Test", parameters = mediaProperties)
	mediaEvent.eventParameters=eventParameters;
	
	// Send request
	Webtrekk.getInstance().trackMedia(mediaEvent)
}

CODE

public void onClick(View view) {

	// Create optional custom media categories
	Map<Integer, String> mediaParam = new HashMap<>();
	mediaParam.put(1,"media category value 1");

	// Create optional event parameters (ck)
	Map<Integer, String> mediaEventParam = new HashMap<>();
    mediaEventParam.put(20, "ck20ParamValue");

    EventParameters eventParameters = new EventParameters(mediaEventParam);

	// Create media object
	MediaParameters mediaParameters = new MediaParameters("media name", "play", 12, 120);
	mediaParameters.setCustomCategories(mediaParam);

	// Create MediaEvent
	MediaEvent mediaEvent = new MediaEvent("page name", mediaParameters);
	mediaEvent.setEventParameters(eventParameters);

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

CODE

API Constraints

Start a media session

The API expects an initial "play" or "init" call to start a media session. Without an init or play call, the session cannot start and tracking of further interaction with the video is not possible.

Seek

If a seek action is sent, the position sent in the seek request needs to be the position at the start of the seek action. Additionally, after each seek request, either a play or pause request (depending on the status before starting to seek) needs to be sent, including the current position of the video.

Examples

Example 1: A user is watching a video on the play and starts to seek 8 seconds into the video. The seek function forwards the user to the position at 20 seconds and continues playing from there. The order and values for the media action and media position need to be sent as follows:

Send a request with media action set to play
Send the seek request with the following values:
1. mk="seek"
2. mt1="8"
Once at the position after seek, send a play request with the following values:
1. mk="play"
2. mt1=20

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

Example 2: The user stops the video at 8 seconds into the video. The user starts to seek at the same position. The seek function forwards the user to the position at 20 seconds and is still on pause at the end of seek. The order and values for the media action and media position need to be sent as follows:

Send a request with a media action set to pause.
Send the seek request with the following values:
1. mk="seek"
2. mt1="8"
Once at the position after seek, send a pause request with the following values:
1. mk="pause"
2. mt1=20

Cookie Notice