Object Oriented Tracking

Object-oriented tracking is the recommended manual tracking approach for the Android SDK. Use it when you want explicit control over pages, events, products, campaigns, users, or media interactions without building raw tracking parameter maps yourself.

Recommended Approach

Use object-oriented tracking for new Android SDK v5 implementations. It is the clearest way to work with the public SDK API and avoids manual parameter mapping in most cases.

This page focuses on the strongly typed event model. If you are looking for the legacy parameter-based approach, use Query Parameter Tracking (Legacy) instead.

Methods Overview

Pages

Use PageViewEvent when you want to send a page request explicitly. A page event can include page parameters, session parameters, user categories, e-commerce parameters, campaign parameters, and custom parameters.

private fun trackCustomPage() {
    val pageParameters = PageParameters(
        parameters = mapOf(20 to "cp20 page parameter value"),
        pageCategory = mapOf(10 to "cg10 page category value"),
        search = "search term"
    )

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

    Webtrekk.getInstance().trackPage(pageEvent)
}

Events

Use ActionEvent for custom event tracking. An action event can include event parameters, session parameters, user categories, e-commerce parameters, campaign parameters, and custom parameters.

private fun trackAction() {
    val eventParameters = EventParameters(
        customParameters = mapOf(20 to "ck20 parameter value")
    )

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

    Webtrekk.getInstance().trackAction(event)
}

Note: ActionEvent.eventParameters expects an EventParameters object, not a raw Map<Int, String>.

Products and Orders

Use ECommerceParameters to send product and order information. Assign the e-commerce object to a PageViewEvent or an ActionEvent.

Product and order values are defined by you. The SDK does not enforce a currency, unit, or price basis (net or gross) — send the values that match your account configuration. For the full definition of how e-commerce values are processed and analyzed, see Orders and Products.

Product properties

Set product data through ProductParameters. Assign one or more products to ECommerceParameters.products.

Order properties

Set order data through ECommerceParameters.

E-commerce status values

The status property defines the context of the e-commerce interaction. It accepts the following values:

If you do not set status, no e-commerce status is sent (NONE_STATUS).

private fun trackPurchase() {
    val product = ProductParameters().apply {
        name = "Product1"
        categories = mapOf(1 to "ProductCat1", 2 to "ProductCat2")
        cost = 13
        quantity = 2
    }

    val ecommerceParameters = ECommerceParameters(
        customParameters = mapOf(1 to "Custom E-Commerce Parameter")
    )
    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 = 36
    ecommerceParameters.status = ECommerceParameters.Status.PURCHASED

    val pageEvent = PageViewEvent(name = "TrackProductConfirmed")
    pageEvent.eCommerceParameters = ecommerceParameters

    Webtrekk.getInstance().trackPage(pageEvent)
}

Campaigns

Use CampaignParameters to attach campaign information to a page or action request. Campaign tracking attributes a request to a marketing campaign, such as a newsletter or an ad.

The action property defines how the campaign contact is counted. It accepts two values:

If you do not set action, the campaign is tracked as a click.

private fun trackCampaign() {
    val campaignParameters = CampaignParameters("email.newsletter.nov2020.thursday")
    campaignParameters.mediaCode = "abc"
    campaignParameters.oncePerSession = true
    campaignParameters.action = CampaignParameters.CampaignAction.CLICK
    campaignParameters.customParameters = mapOf(12 to "campaign parameter value")

    val pageEvent = PageViewEvent(name = "TestCampaign")
    pageEvent.campaignParameters = campaignParameters

    Webtrekk.getInstance().trackPage(pageEvent)
}

Users

Use UserCategories to send predefined and custom user information with a page or action request.

private fun trackUserData() {
    val userCategories = UserCategories()
    userCategories.customCategories = mapOf(1 to "user category value 1")
    userCategories.birthday = UserCategories.Birthday(day = 12, month = 1, year = 1993)
    userCategories.customerId = "CustomerID"
    userCategories.gender = UserCategories.Gender.FEMALE
    userCategories.city = "Paris"
    userCategories.country = "France"

    val pageEvent = PageViewEvent(name = "the custom name of page")
    pageEvent.userCategories = userCategories

    Webtrekk.getInstance().trackPage(pageEvent)
}

Media Tracking

Use MediaEvent together with MediaParameters to track media interactions. A media event can include required media properties and optional event parameters, session parameters, e-commerce parameters, and custom parameters.

private fun trackMedia() {
    val mediaParameters = MediaParameters(
        name = "TestVideo",
        action = MediaParameters.Action.INIT.code(),
        position = 12,
        duration = 120
    )
    mediaParameters.customCategories = mapOf(20 to "media category value")

    val eventParameters = EventParameters(
        customParameters = mapOf(20 to "sporthighlights")
    )

    val mediaEvent = MediaEvent(
        pageName = "en.sports.football",
        parameters = mediaParameters
    )
    mediaEvent.eventParameters = eventParameters

    Webtrekk.getInstance().trackMedia(mediaEvent)
}

For query-parameter-based tracking and the legacy overloads, see Manual Tracking and Query Parameter Tracking (Legacy).