3rd party integrations
...
Purple Tracking
Tracking Configuration

Configuration: Enrich event data

10min

Summary

This article is about the enrichment of your event data. That can be done by using placeholders and by adding parameters to your event configuration. This article is structured as follows:

  • Placeholders describes what placeholders are and how to find out which ones are available for your event.
  • Placeholder template engine describes how placeholders are used within your "tracking_config.json" and how these values are replaced.
  • Templates and parameter describes where to add placeholders in your event configuration
  • Example shows the whole process of using placeholders, replacing them with concrete values and finally looking at the data sent to the tracking service.

Placeholders

Templates and parameters may contain placeholders within the value part and are referenced in the „tracking_config.json“ by using the following syntax:

{{PLACEHOLDER_NAME}}

Placeholder names are always UPPERCASED and separated by underscores. Example: ISSUE_ID A list of all available placeholders can be found in chapter Placeholder.

Please note, however, that not all placeholders are available for every event. Based on the documentation of a specific event, the available placeholders are always linked within the "Placeholder" tab. If none are available, this is marked accordingly.

Placeholder template engine

The placeholder template engine replaces the placeholder with its associated value, which is only available and known at app runtime. This means, for example, that the values of content are only available for tracking when an app user has an issue or article opened. The replacement of the placeholders is done before the event data is sent to the backend of the tracking service. You can add placeholders in the value area of templates and parameters, which are described below.

Templates and parameter

Template

The first place placeholders can be used is within a template. Most events only make sense if placeholders are used in the templates. However, these can only be used in the value area of the template.

As a reminder, the structure of a template within the „tracking_config.json“ is as follows:

"template_key": "value of template

Short example:

The template may be action“ : „issue_opened“


and enriched by a placeholder action“ : „issue_opened_{{ISSUE_ID}}

Parameter

Some tracking services supports to send additional data with your event to the tracking service back end which is done by parameters which is a list of key/value pairs. It is useful to add parameters to your events. It is recommend to define your USE-CASES first. Then select the corresponding event(s) and have a look of the available placeholders. Finally derive a list of useful parameters and add them to the event configuration.

As a reminder, the structure of a parameter within the „tracking_config.json“ is as follows:

"parameter_key": "value of parameter

Short example:

The parameter may be issue_id“ : „static parameter value may be useless

and enriched by a placeholder issue_id“ : „{{ISSUE_ID}}

Example

In the example you will find two variants of a "tracking_config.json" at the end, one with some events completely without data enrichment and one with data enrichment. For example, let's take the following event:

ISSUE_DOWNLOADED


Without data enrichment, later evaluation of events in the respective front end of your tracking service is more than difficult.

The "ISSUE_DOWNLOADED" event as shown does not provide any information about which issue was downloaded. All you see is that x app users have downloaded y issues.

It therefore makes sense to enrich your events with additional data. The above event could look like this:

ISSUE_DOWNLOADED


Advantages for your evaluation:

  • You know the number of downloads per issue.
  • You could create download statistics per issue.
  • Is that issue purchasable?
  • etc.

Purple's recommendation for naming parameter names

When naming parameters, we recommend using the name of the placeholder in lowercase as the parameter name.

Example

If you are interested in the issue name and want to use the placeholder "ISSUE_NAME", then create a parameter with the key "issue_name".

The parameter could therefore look like this:

"issue_name" : "{{ISSUE_NAME}}" The transmission to your tracking service will then take place as follows for a “May 2023” edition:

"issue_name" : "May 2023"

tracking_config.json