Eventvisor

Getting started

Quick start

This guide will get you up and running with a basic setup of Eventvisor.

Prerequisites

NOTE: Eventvisor SDKs are meant to be platform agnostic. Node.js is only required for the CLI for managing projects.

Initialize a new project

Run the following command to initialize a new project:

Command
$ mkdir my-project && cd my-project
$ npx @eventvisor/cli init

This is ideally meant to be a completely separate repository from your application code, so they can be deployed independently.

Learn more in projects page about more advanced uses cases, including monorepo setup.

Installation

Once initialized, install the dependencies:

Command
$ npm install

Configuring your project

Once installed, you can configure the Eventvisor project by editing the eventvisor.config.js file.

A very minimal configuration file would look like this:

eventvisor.config.js
module.exports = {
  tags: [
    'web',
    'mobile',
    'backend',
  ],
}

Tags help you generate targeted smaller datafiles (static JSON files) which your applications can load and consume with Eventvisor SDKs.

This allows you to have a single Eventvisor project that can be used by multiple applications, and each application can load only the data it needs.

Learn more in Configuration page.

Defining attributes

Attributes are contextual information about the environment that your application is running in. These attributes can be about the user, the device, the application itself, etc which do not change too frequently.

For now, we can we define two simple attributes.

First deviceId:

attributes/deviceId.yml
description: Device ID
tags:
  - web
type: string

And also userId:

attributes/userId.yml
description: User ID (if user is logged in)
tags:
  - web
type: string

The name of the attribute is the file name (without the extension).

The schema for attributes is defined using a subset of JSON Schema that you can read more about here.

Learn more in Attributes page.

Defining events

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

For now, we can we define a simple event called pageView:

events/pageView.yml
description: Page view
tags:
  - web
properties:
  url:
    type: string
required:
  - url

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

Example payload in JSON format would look like this:

{
  "url": "https://www.example.com"
}

Learn more in Events page.

Define a destination

Destinations are where our tracked events are sent to, and transports are the means how they reach there.

Transports can be your browser's console, your favourite analytics service like GA4, or your own custom backend service.

Assuming our target application is a web application, we can define a destination called browser which will log the tracked events to the browser's console:

destinations/browser.yml
description: Print to browser console
tags:
  - web
transport: console

We will learn more later about how transports are setup via modules in the application layer.

Transforms

We can also use transforms to manipulate the body of the event before it is handed over to the transport:

destinations/browser.yml
# ...
transforms:
  # remove a certain property
  - type: remove
    target: payload.sensitiveProperty

Learn about more advanced use cases of transforms in destinations page.

Conditions

If we wish to filter the events before they are transported to a particular destination, we can also add conditions to it:

destinations/browser.yml
# ...
conditions:
  - source: eventName
    operator: equals
    value: pageView

Above will make sure only the pageView event is transported to the browser's console, and not other tracked events.

Learn more in conditions and sources pages.

Sampling

Sometimes you may want to ingest only a certain percentage of the tracked events to your desired destination. You can do that by adding a sampling rule to the destination:

destinations/browser.yml
# ...
sample:
  by: attributes.userId
  percentage: 10

It is recommended to use a consistent value like userId attribute to sample the events, because this will allow maintaining a consistent sampling strategy across different devices and sessions (think web, iOS, and Android apps) for the same user.

Learn about more advanced sampling rules in sampling page.

Linting

It's not surprising that managing all these files can lead to syntax errors and other structural issues. To help with that, Eventvisor provides a linter that will help you catch these issues early:

Command
$ npx eventvisor lint

Learn more in Linting page.

Building datafiles

Datafiles are static JSON files that are generated from your Eventvisor project. Each tag as defined in your project's configuration file will produce its own separate datafile, allowing applications to load them individually on demand.

You can build them by running the following command:

Command
$ npx eventvisor build

The output will be available in the datafiles directory:

Directory structure
datafiles/
├── eventvisor-tag-web.json
├── eventvisor-tag-mobile.json
└── eventvisor-tag-backend.json

Learn more in building datafiles page.

Deploy datafiles

Eventvisor itself does not have any opinion on how you make these datafiles available to your applications. You can use your own server, or a CDN, or even deploy them long with your application code.

Because controlling how events flow from applications via remote configuration is highly beneficial, it is recommended that you use a CDN to serve them, allowing you to decouple your application code deployment from your Eventvisor project's datafile deployments.

You can learn more about deployment strategies in deployment page.

Consume datafiles using SDKs

Once you have built the datafiles, you can consume them using Eventvisor SDKs.

At the moment there's only JavaScript SDK supporting browser and Node.js applications. More SDKs will follow in near future as the project matures.

Install SDK

In your application (either web or Node.js), install the SDK and the console module together:

Command
$ npm install --save @eventvisor/sdk @eventvisor/module-console

Modules are additional packages that can be installed on demand to expand the capabilities of the SDK.

Initialize SDK

Once your desired datafile is fetched, you can initialize the SDK along with the module(s) you want to use:

your-app/index.js
import { createInstance } from "@eventvisor/sdk";
import { createConsoleModule } from "@eventvisor/module-console";
// fetch datafile, or
// have it hardcoded in the application
const DATAFILE_URL = "https://cdn.yoursite.com/eventvisor-tag-web.json";
const datafile = await fetch(DATAFILE_URL).then(res => res.json());
// initialize
const eventvisor = createInstance({
  datafile: datafile,
  modules: [
    createConsoleModule(),
  ],
});

Set attributes

Now that we have the SDK instance ready, we can start setting attributes:

eventvisor.setAttribute("deviceId", "device-123");
eventvisor.setAttribute("userId", "user-456");

Track events

Now the more interesting part for tracking events:

eventvisor.track("pageView", {
  path: "/home",
});

Doing above will show us a warning in the console, because the payload of this event does not honour the schema that we defined for it earlier.

We can try doing it the correct way now:

eventvisor.track("pageView", {
  url: "https://www.yoursite.com/home",
});

Now you should see the tracked event in your application's console immediately.

If you indeed see it, it means you have successfully set up Eventvisor and you are ready to start tracking your events.

Next steps

This was a very simple setup, but there's a lot more that you can do with Eventvisor.

Several concepts that can help you make the most out of Eventvisor below:

Next
Attributes