Event parameters and enrichment

Event parameters are additional pieces of information about a customer activity the event describes. For example, a page.visit event can be described by parameters such as:

IP (IP address from which a user visited the website)
UTM source (the UTM source from which a user was referred to the website)
device (the device from which a user accessed the website)
and more

For a product.buy (an event that describes a purchase of a product) the list of parameters can be long and include:

name (name of the product)
finalUnitPrice (the final price of the product)
currency (the currency of the product)
quantity (the quantity of a product)
og:url (a page address towards which all shares, likes, and so on, will be counted)
and more

Events and their parameters can be used to prepare analyses of various kinds, for example, users can create a metric that counts visits to particular subdomains or they can create an aggregate that calculates the value of abandoned cart for a specific customer.

Adding parameters to events

Important: If you send an event by using the SDK/API, its parameters (the params object) are saved to the database and added to the event’s definition automatically. By default, they are visible in analytics. In such a case, you don’t need to add the parameters according to the instructions in this article. If needed, you can edit the parameters to add names, descriptions, or enable event enrichment.

Go to Data Management > Events.
In the list of events, find the event where you want to add parameters and hover over it.
On the right side of the screen, click Add property.
In the Source parameter field, enter the name of the parameter as it is sent by the SDKs/API.
In the Property name field, enter a human-readable label for display in the Synerise portal.
Optionally, in the Description field, you can add an explanation about the purpose of this parameter.
From the Property type dropdown list, select the format of the property value as sent by the SDKs/API.
If you want to enrich the event with data from a catalog, select the catalog from the Link to drop-down list.
To complete the process, click Save.
Result: The property is saved on the list of events.

Changing property visibility in analytics

By default, each parameter is visible in analytics.

You can enable or disable the visibility of a parameter in the analytics:

In the list of events, find the event where the parameter is defined and hover over it.
Next to the Add property button, click the downward arrow button.
Result: A list of parameters appears.
In the list of parameters, hover over the visibility icon of a parameter.
Switch the toggle that appears.

Enriching events with data from catalogs

You can add data from catalogs to an event automatically. This can be used, for example, to automatically add product data to a product-related event without sending that data with the event every time.

The data is added to an event from a catalog when the value of the source parameter matches a value in the catalog’s key. The data of the object identified by that key is added to the event.

Tip: The name of the property linked to the catalog does not need to be related to the name of the column that stores the keys. Only one such column exists and the enrichment mechanism detects it automatically.

While defining the trigger of an in-app message, you must use only the original parameters of the event which is selected as the trigger. Parameters that are added by enrichment aren’t supported.

WARNING: Due to the caching, you may need to wait up to one hour until the parameter you want to enrich the event with is added.

Requirements

Create a definition of an event whose information you will enrich. This event must have at least one event parameter.
To see if the event definition exists, go to Data Management > Events.
Create a catalog which contains data you want to enrich event information with. You can include as many columns as you need, but for the enrichment process, you’ll be limited to using only 5 columns.

Enrichment limits

You can enrich up to 8 events per workspace.
You can enrich an event with data from maximum 2 catalogs.
See the “Conflict resolution” section in this article to see what happens when the parameter names from 2 catalogs overlap.
You can use up to 5 parameters from a catalog to enrich events.

Procedure

Go to Data Management > Events.
On the list of events, find an event you want to enrich with data from a catalog.
Hover a mouse cursor over the event name.
Result: A Manage enrichment button appears.

The Manage enrichment button on the list
Click Manage enrichment.
Result: A pop-up with enrichment settings appears.

Selecting a catalog for enrichment
In the Linked catalogs section, from the Catalog list, select a catalog whose data you want to use to enrich event information.
Result: The Catalog primary key and Event parameter fields appear.

Catalog item key and Event parameter fields
In this step, from the Event parameter dropdown list, match the event parameter with the primary key of the catalog. By clicking the eye icon next to Primary key, you can preview values from the primary key column.
When the value of the selected parameter is the same as the value in the primary key column of the catalog, the event will be enriched with data available in the corresponding row of the catalog.
Result: The List of parameters section appears.
To add the next catalog for data enrichment, click Add catalog and repeat steps 5 and 6.
If you want to enrich an event with information from two catalogs at the same time, the event must include the event parameters linked to the primary key of each catalog if the catalogs don’t have the same primary key.
In the List of parameters and Show as JSON sections, you can see the lists:
- Enriching parameters tab: event parameters with which the event will be enriched,
- Default event parameters tab: event parameters before enriching,
- All parameters tab: all event parameters after enriching.
Complete Manage enrichment configuration form
If you want to:
- add a prefix to the event parameters coming from enrichment,
- select or exclude catalog parameters from enriching,
- rename the enriched event parameters,
  click Manage list.
If you want to differentiate event parameters added through enrichment in the event information, you can add a prefix to them. To do so, select the Add a prefix to the name option and provide the prefix.
As a result, the system adds [prefix value]. to the name of the event parameters from enrichment in the event information. For example, you define movies as the prefix and the catalog with which you enrich the event information contains the genre column. As a result of enrichment, the event information will contain the movies.genre parameter.
In the List of catalog properties section, you are shown the list of available parameters in the catalog. By default, the first 5 parameters are sent to enrich the event.
To change the selection of attributes which will enrich the event:
1. Enable Show bulk actions.
2. To select a catalog parameter for enrichment, next to the parameter name in the Catalog parameter name column, select the checkbox.
3. Set the icon between the columns to ; this way, this parameter will be used for event enrichment.
4. To exclude the parameter from enrichment, set the icon between columns to
To change the name under which the parameter will be displayed in the event information, in the Event parameter name column, replace the name of the parameter with a new one.
The name in the catalog will remain the same.
To resolve parameter name conflicts, click Check for name conflicts and follow the instructions on the interface.
Confirm the changes by clicking Save in the upper right corner.
Save the enrichment settings for the event by clicking Apply.

Example result

When the event parameter value mapped to the catalog’s primary key column matches a value in this catalog column, the event information will be enriched with values from the corresponding row in the catalog. The enriched parameters will be available in the params object.

For example, if you want to enrich a video.watched event (which is a custom event) with data about the video that a customer watched, you can send the following event when that video is played, using the data from the example catalog below.

The example catalog with video information

Using the below tabs, check the event before and after enriching with data from the example catalog. The parameters added as a result of enrichment are prefixed by a string defined in the the Add a prefix to the name option in enrichment settings or . if you left this option unconfigured.

{
  "action": "video.watched",
  ...
  "params": {
    "videoID": "2"
  }
}

Conflict resolution

Conflicts may appear while using two catalogs for event enrichment and both of them contain columns with the same name. You can resolve the conflicts by clicking the Check for name conflicts option and replacing the overlapping catalog’s column name.

If you don’t rename the overlapping parameters, then the names from the catalog in the A tab will be applied during event enrichment. If the parameter from the catalog A is empty, then the value from catalog B for the corresponding parameter is used.