Managing event definitions

The activity of your website’s visitors is saved in Synerise as events. For example, opening the page is saved as the page.visit event.
Sometimes, events also define the activities directed to the user, such as sending an email (message.sent) or a web push notification (webpush.send).
The application can generate these events thanks to the implementation of a tracking code and/or mobile SDK.

The events are identified by their action property, which takes a <domain>.<occurrence> format.

You can add custom event definitions in the following ways:

  • Through the interface (described in this article)
  • Through the API by using the Custom event method. When you use that method to send an action which is not known in the system, a definition is created automatically from the new data.

By default, the custom events you add have a 30-day retention period.

Requirements


You must have permissions to access the Data Management module and perform operations there.

Adding event definitions


In the Web application

  1. Go to Data Management icon Data Management > Events.

  2. Click Add new event.
    Result: A pop-up appears. Depending on the size of your screen, the Settings and Display tab selector may appear as three horizontal dots below the New Event header.

  3. On the Settings tab (default), fill in the fields:

    • Name is the system name of an event, usually in an context.action format, for example page.visit.
      • This name can’t be changed later.
      • It must be 2-32 characters long.
      • Diacritic characters aren’t allowed.
      • The following special characters are allowed: -, _, .
    • Display name is a human-readable name shown in the Data Management > Events menu and in Analytics.
    • Description is shown in the Data Management > Events menu.
    • The JS SDK event settings determine how the JS SDK can use the event. Make sure you have already configured a certificate to validate authentication tokens. For more details, see Event authentication settings.
    Display name and description from the Settings tab shown in the event definition list after saving the settings
    Display name and description from the Settings tab shown in the event definition list after saving the settings
  4. Optional: On the Display tab, fill in the fields:

    • Title is a short event title shown in a Profile’s event history.
    • Details is a longer description shown in a Profile’s event history.
    Title and details from the Display tab shown in a Profile's event history
    Title and details from the Display tab shown in a Profile's event history
    Tip: In Title and Details, you can use Jinjava to refer to the event’s parameters or add logic. See instructions and examples.
  5. To complete the process, click Save.
    You can now add parameters to this event definition.

By sending an event to the API

When you send a previously unknown event to the /v4/events API, the event’s definition and parameters are automatically added to the Data Management > Events view.
Such an event has no display name, description, title, or details, and is visible in analytics.
The event’s parameters are also added, without any descriptions, and are available in analytics.
You can edit the event definition and parameters to fill in the additional data.

Editing event definitions

You can update an existing event. Some settings cannot be edited.

Important: The changes may take up to an hour to apply.
  1. Go to Data Management icon Data Management > Events.
  2. In the list of events, find the event you want to edit.
  3. Click the Three dot icon.
  4. From the list, select Edit.
  5. In the window that appears, edit the data in the same way as when adding the definition.

Changing event visibility in analytics

By default, each event is visible in analytics.

You can enable or disable the visibility of an event in the analytics:

  1. In the list of events, hover over the visibility icon of an event.
  2. Switch the toggle that appears.

Adding parameters

See Event parameters and enrichment.

Removing event definitions

  1. Go to Data Management icon Data Management > Events.
  2. In the list of events, find the event you want to edit.
  3. Click the Three dot icon.
  4. From the list, select Remove.
  5. In the dialog that appears, confirm by clicking OK.

Using variables for displaying event data in Profiles

If you want insert dynamic values or even logic into an event’s summary on a Profile’s card, you can use Jinjava.

Inserting event parameters

Additional parameters which can be used as variables are stored in the params object in the event’s data. They are accessed with the {{ params.paramName }} syntax.

You can also access the system parameters outside of the params object, for example {{ action }}. The label parameter is an exception and is always treated as an empty value.

Example

You can use the params.message property of the event from the figure below to display a dynamic Title and Details.

In this example, a world.greet event with a custom message parameter is saved to the Profile’s history:

Raw data view of an event
Raw data of an event. The highlighted "message" parameter is a custom parameter used in the examples further in this article.

In the event definition for world.greet, the following Jinjava is added:

Example of Jinjava in the configuration of an event definition
Example of Jinjava in the configuration of an event definition

On a Profile card, the variables are processed and displayed in the event summary:

Example of processed Jinjava in a Profile's history
Example of processed Jinjava in a Profile's history

Advanced usage

You can use Jinjava elements from the following articles:

Example

If a parameter does not exist or is an empty string, you can insert a placeholder value.

Important: If the parameter is null, its value is processed as the string "null".

In this example, the dogname parameter does not exist in an event’s data.
In the event definition for world.greet, the following Jinjava is added:

Example of Jinjava IF/ELSE statement in the configuration of an event definition
Example of Jinjava IF/ELSE statement in the configuration of an event definition

On a Profile card, the variables are processed and displayed in the event summary:

Example of the above IF/ELSE statement's result in a Profile card. The IF condition was not met and the ELSE result is displayed
Example of the above IF/ELSE statement's result in a Profile card
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker