Setting up tracking in Web views

In the Installation section, you installed the WebView tracker in your JavaScript Web app that is accessed in the mobile Web views. After that, you learned how to configure and use the mobile trackers to track events and subscribe to events from Web views. This section explains how to use the WebView tracker to track events inside Web views.

Event tracking API

The tracker provides a set of functions to manually track events. The functions range from single purpose ones, such as trackScreenView, to the more complex but flexible trackSelfDescribingEvent, which can be used to track any kind of user behaviour. We strongly recommend using trackSelfDescribingEvent for your tracking, as it allows you to design custom event types to match your business requirements. This post on our blog, “Re-thinking the structure of event data” might be informative here.

You can import the functions from the @snowplow/webview-tracker package:

import { trackSelfDescribingEvent, trackScreenView } from '@snowplow/webview-tracker';

The following functions are available:

All the methods share common features and parameters. Every type of event can have an optional context added. See the end of this section to learn about adding context entities to events. It’s important to understand how event context works, as it is one of the most powerful Snowplow features. Adding event context entities is a way to add depth, richness and value to all of your events.

All of the trackXYZ() methods accept two arguments:

For instance, the following tracks a structured event (explained below) using a tracker initialized with the namespace ns1:

trackStructEvent(
    {
        category: 'shop',
        action: 'add-to-basket'
    },
    ['ns1']
);

Track self-describing events with trackSelfDescribingEvent

Use the trackSelfDescribingEvent function to track a custom event. This is the most advanced and powerful tracking method, which requires a certain amount of planning and infrastructure.

Self-describing events are based around “self-describing” (self-referential) JSONs, which are a specific kind of JSON schema. A unique schema can be designed for each type of event that you want to track. This allows you to track the specific things that are important to you, in a way that is defined by you.

This is particularly useful when:

• You want to track event types which are proprietary/specific to your business
• You want to track events which have unpredictable or frequently changing properties

A self-describing JSON has two keys, schema and data. The schema value should point to a valid self-describing JSON schema. They are called self-describing because the schema will specify the fields allowed in the data value. Read more about how schemas are used with Snowplow here.

Example using the default tracker:

trackSelfDescribingEvent({
    event: {
        schema: 'iglu:com.example_company/save_game/jsonschema/1-0-2',
        data: {
            'saveId': '4321',
            'level': 23,
            'difficultyLevel': 'HARD',
            'dlContent': true
        }
    }
});

Track structured events with Structured

This method provides a halfway-house between tracking fully user-defined self-describing events and out-of-the box predefined events. This event type can be used to track many types of user activity, as it is somewhat customizable. “Struct” events closely mirror the structure of Google Analytics events, with “category”, “action”, “label”, and “value” properties.

As these fields are fairly arbitrary, we recommend following the advice in this table on how to define structured events. It’s important to be consistent throughout the business about how each field is used.

Example:

trackStructEvent({
    category: 'shop',
    action: 'add-to-basket',
    label: 'Add To Basket',
    property: 'pcs',
    value: 2.00,
});

Track screen views with trackScreenView

Use ScreenView to track a user viewing a screen (or similar) within your app. This is the page view equivalent for apps that are not webpages. Screen view events are used in the Snowplow mobile data model.

This method creates an unstruct event, by creating and tracking a self-describing event. The schema ID for this is “iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0”, and the data field will contain the parameters which you provide. That schema is hosted on the schema repository Iglu Central, and so will always be available to your pipeline.

Example:

trackScreenView({
    id: '2c295365-eae9-4243-a3ee-5c4b7baccc8f',
    name: 'home',
    type: 'full',
    transitionType: 'none'
});

Track Web page views with trackPageView

The PageViewEvent may be used to track page views on the Web. The event is designed to track web page views and automatically captures page title, referrer and URL.

Page view events are the basic building blocks for the Snowplow web data model. For mobile apps we recommend using the mobile data model and tracking screen view events instead.

trackPageView();

Adding data to your events using context entities

Event context is an incredibly powerful aspect of Snowplow tracking, which allows you to create very rich data. It is based on the same self-describing JSON schemas as the self-describing events. Using event context, you can add any details you like to your events, as long as you can describe them in a self-describing JSON schema.

Each schema will describe a single “entity”. All of an event’s entities together form the event context. The event context will be sent as one field of the event, finally ending up in one column (context) in your data storage. There is no limit to how many entities can be attached to one event.

Note that context can be added to any event type, not just self-describing events. This means that even a simple event type like a page view can hold complex and extensive information – reducing the chances of data loss and the amount of modelling (JOINs etc.) needed in modelling, while increasing the value of each event, and the sophistication of the possible use cases.

The entities you provide are validated against their schemas as the event is processed (during the enrich phase). If there is a mistake or mismatch, the event is processed as a Bad Event.

Once defined, an entity can be attached to any kind of event. This is also an important point; it means your tracking is as DRY as possible. Using the same “user” or “image” or “search result” (etc.) entities throughout your tracking reduces error, and again makes the data easier to model.

Example:

trackStructEvent(
    {
        category: 'shop',
        action: 'add-to-basket',
        label: 'Add To Basket',
        property: 'pcs',
        value: 2.00,
        context: [
            {
                schema: 'iglu:com.my_company/movie_poster/jsonschema/1-0-0',
                data: {
                    movie_name: 'Solaris',
                    poster_country: 'JP',
                    poster_date: '1978-01-01'
                }
            },
            {
                schema: 'iglu:com.my_company/customer/jsonschema/1-0-0',
                data: {
                    p_buy: 0.23,
                    segment: 'young_adult'
                }
            }
        ]
    },
    ['ns1']
);