Configuration: Enrich event data
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.
- Example shows the whole process of using placeholders, replacing them with concrete values and finally looking at the data sent to the tracking service.
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.
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.
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}}“
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}}“
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:
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:
Advantages for your evaluation:
- You know the number of downloads per issue.
- You could create download statistics per issue.
- Is that issue purchasable?
- etc.
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"