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.

An event can also use a reusable Schema at its root or within individual properties:

description: Customer updated
tags: [backend]
schema: customer

Description#

The description property is purely for documentation purposes:

# ...
description: Page view event

Tags#

Tags are reusable metadata. Targets can select tagged events and include their dependencies in generated datafiles:

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

Type#

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

# ...
type: object

The linter rejects non-object event schemas. When an event shape changes incompatibly, define a new event key instead of changing the meaning of an existing key in place.

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:

• fatal
• 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, a tracked event is routed to every destination available in the loaded Target datafile. The Target controls which events, destinations, and dependencies are present. Event rules can then adjust routing at runtime.

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

Skip validation#

Every tracked event is validated against the schema defined in the event definition, which helps catch errors early and ensure the data is consistent and reliable.

Validation checks are best run in pre-production environments, and you can skip validation by adding skipValidation: true to the event definition:

# ...
skipValidation: true

Validation can also be controlled with additional conditions:

# ...
skipValidation:
  conditions:
    - attribute: environment
      operator: equals
      value: production

Validation failure policy#

Invalid events are dropped by default. During gradual adoption, choose another policy for the project or one event:

onValidationFailure: deliverWithWarning

deliverWithWarning sends the original payload and adds validation details to transport metadata. A quarantine policy sends a stable envelope only to a designated destination and bypasses ordinary event destinations and effects:

onValidationFailure:
  action: quarantine
  destination: invalidEvents

The envelope contains eventName, the original payload, validationErrors, and the datafile revision. Quarantine definitions are validated during linting. Use a new event key for an incompatible event shape instead of introducing an event-version field.

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