Pages

Page tracking is possible with both auto-tracking enabled and disabled. If auto-tracking is disabled, only the screens 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.). When sending the request to the server, the SDK converts it automatically into the Mapp Intelligence data model specification. We recommend object-oriented tracking for all customers unfamiliar with the Mapp Intelligence data model or implementing 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 unfamiliar 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. 

The status of a product is needed to ensure tracking and e-commerce use cases can be run. Our Android SDK supports the following statuses:

  • ADDED_TO_BASKET: Indicates that an item was added to the user's cart/basket
  • PURCHASED: Indicates that an item was bought.
  • VIEWED: Indicates that a user viewed an item.
  • DELETED_FROM_BASKET: Indicates that an item was removed from the user's shopping cart.
  • ADDED_TO_WISHLIST: Indicates that the user added an item to their wishlist.
  • DELETED_FROM_WISHLIST: Indicated that the user deleted an item from their wishlist.
  • CHECKOUT: Indicates a checkout.

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 each website goal to see 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, the parameter's first or last value 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

Predefined 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 predefined parameters, you do not need to create the parameters in your mobile application; activate them in Mapp Q3 instead. This section describes how to create the appropriate parameters.

The following parameters are predefined in the SDK:

ParameterParameter IDDescriptionData TypeAmount Parameter ValuesCalculation
App updated815When the end-user updates the app to a new version, it is tracked via this predefined session parameter.FigureSingle valueThe last value wins. This means only the last value of the transmitted parameter is counted per session.
App version804This parameter analyzes whether users are utilizing the latest version of your app.TextSingle valueThe last value wins. This means only the last value of the transmitted parameter is counted per session.
App first open821This parameter is tracked when the user opens the app for the first time after installing the mobile application from the Web or App Store.TextSingle valueThe 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:

  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:

    ParameterDescription
    TitleMandatory. Enter the name of the session parameter.
    DescriptionOptional. 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 IDThe ID is set automatically by the system.
  5. Click Save to save your settings.


 Customers

Identifying customers or users is essential 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

MethodDescription
          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 begin, and tracking further interaction with the video is impossible.


Seek

If a seek action is sent, the position sent in the seek request must be the position at the start of the seek action. Additionally, after each seek request, 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:

  1. Send a request with media action set to play
  2. Send the seek request with the following values:
    1. mk="seek"
    2. mt1="8"
  3. 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 suppress that to be aligned with the API expectation manually.


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

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