Events

Events are structured data, which can be either a log or an analytics event in your application that will be tracked using Eventvisor SDKs.

Examples#

Depending on the type of your application, examples of events can be:

• pageView
• buttonClick
• search
• purchase
• ...etc

Defining events#

If we choose to define a new event called pageView, we can create a new file called pageView.yml in the events directory:

description: Page view event
tags:
  - web
type: object
properties:
  url:
    type: string
  title:
    type: string
required:
  - url

Above, we defined an event called pageView with a JSON Schema that expects url and title properties, out of which url is a required property.

Description#

The description property is purely for documentation purposes:

# ...
description: Page view event

Tags#

Tags are used to generate targeted datafiles for your applications:

# ...
tags:
  - web
  - mobile
  - backend

Type#

Unlike attributes, events are always expected to be of type object:

# ...
type: object

Properties#

These are the properties of the event being defined, based on JSON Schema:

# ...
properties:
  url:
    type: string

Required#

Based on JSON Schema, we can mark some properties as required.

If tracked events in your application don't have all the required properties in the payload, we will get a validation error in the console:

# ...
required:
  - url

Level#

Events can define their own levels, which helps transports to categorize the events based on their severity:

# ...
level: error

Possible values are:

• error
• warning
• log
• info
• debug

Conditions#

Conditions, when defined at event definition level, will act as a filter before the event is handed over to the destination(s).

If we wanted to only track pageView events for certain paths, we could add conditions like this:

# ...
conditions:
  - payload: url
    operator: endsWith
    value: /home

You can learn more in sources and conditions pages.

Transforms#

Transforms defined at event definition level helps manipulate the event payload before it is handed over to the destination(s).

If we wanted to add a new property on the fly to the tracked event, we could add transforms like this:

# ...
transforms:
  - type: set
    target: someNewProperty
    value: value here

Validation is applied only for the original payload that is tracked using SDKs in applications. But from our transformation layer in the definition, we are in control to manipulate it further as we wish.

You can learn in depth about them in transforms page.

Sample#

Ingesting all the events is not always the best idea. Sometimes you may want to sample a certain percentage of the events or only track a subset of them based on certain conditions.

Defining sampling rules is how you can achieve that:

# ...
sample:
  by: attributes.deviceId
  percentage: 10 # 10% of the unique devices

You can learn about more advanced use cases in sampling page.

Destinations#

By default, all tracked events are routed to all destinations as available in the generated datafile based on the tags.

You may want to further control how each event ends up being routed to different destinations in a more granular way.

Assuming we have already these destinations defined:

• browser (browser's console)
• ga4 (GA4)

Disable destination#

We can control how our desired event ends up being routed to each destination:

# ...
destinations:
  browser: false
  ga4: true # defaults to `true` anyways unless overridden

Conditional destination#

Additional conditions can be applied to control the destination routing:

# ...
destinations:
  browser: false
  ga4:
    conditions:
      - attribute: platform
        operator: equals
        value: web

Sampling destination#

If you wish to sample the individual event before it is handed over to the specific destination, you can do:

# ...
destinations:
  browser: false
  ga4:
    sample:
      by: attributes.deviceId
      percentage: 10

Tracking events#

Events are meant to be tracked in your application using provided Eventvisor SDKs.

If we take JavaScript SDK as an example, we can track events like this:

eventvisor.track("pageView", {
  url: location.href,
  title: document.title,
});

Based on the configuration of the project, the tracked event will get validated against the schema and be handed over to the relevant destinations if all conditions are met.

Deprecating#

You can deprecate an event by adding deprecated: true to the event definition:

# ...
deprecated: true

If deprecated, it will still continue to work as expected, but the SDKs will show a warning in the console notifying the developers to take action.

Archiving#

You can archive an event by adding archived: true to the event definition:

# ...
archived: true