Effects

Effects are side-effects that can be handled in your application via modules that are triggered by certain events and conditions.

Examples#

Examples of side-effects can be:

• Injecting a marketing or tracking script in the page after getting user's cookie consent (GDPR)

Concerns#

It is understandable that you may have concerns about the security of your application for mechanisms like this, and also unnecessary bloat from a tool that does too much.

But Eventvisor on its own is oblivious to what your side-effects are, and it is up to you entirely to ensure when to trigger them and how to handle them.

The core SDK does nothing extra, and it is only with additional modules that you install in your application(s) that can help achieve these complex use cases.

Defining effects#

If we choose to define a new effect called marketing-pixel, we can create a new file called marketing-pixel.yml in the effects directory:

description: Marketing pixel
tags:
  - web

The file name (without the extension) will be the name of the effect.

Description#

The description property is purely for documentation purposes:

# ...
description: Marketing pixel

Tags#

Tags are used to generate targeted datafiles for your applications:

# ...
tags:
  - web

Triggers#

There are several ways to trigger an effect:

On tracked events#

If you wish to listen to any event being tracked, you can do:

# ...
on:
  - event_tracked

If you want to be specific about the events:

# ...
on:
  event_tracked:
    - pageView

On set attributes#

Listening to any attribute being set:

# ...
on:
  - attribute_set

If you want to be specific about the attributes:

# ...
on:
  attribute_set:
    - myAttribute

Combined triggers#

You can of course combine both types of triggers together as well:

# ...
on:
  event_tracked:
    - pageView
  attribute_set:
    - myAttribute
    - attribute_set

State#

An effect can maintain its own internal state, and we can start with initial state like below:

# ...
state:
  injected: false

Conditions#

Conditions work as a filter before proceeding to the steps below.

We previously defined a state with an object { injected: false }. So we may want to check if it is still false before proceeding with actually injecting the script. Because we don't want to inject the script multiple times.

# ...
conditions:
  - state: injected
    operator: equals
    value: false

Learn more in conditions page for complex use cases.

Steps#

Steps are where the real work is done. If your effect was triggered, and it has fulfilled the conditions as well, then the steps will be executed in a synchronous manner.

Handler#

Each step can have a handler, which is coming from a module that will be installed in your application.

If your handler requires any extra parameters to be passed to the module, you can add them under params property.

# ...
steps:
  # inject the script
  - handler: pixel # this is the module we will install later
    params:
      snippet: |
        <script>
          console.log("Marketing script injected");
        </script>
      selector: body
  # update the state
  - transforms:
      - type: set
        target: injected
        value: true

Transforms#

Similar to attributes, events and destinations, each step can have transforms property too. But in the case of effects, it is for transforming its internal state only and not the event or attribute's payload.

Learn more in handlers page.

Conditions#

If you need step-specific conditions, you can add a conditions property to the individual step itself.

Continue on error#

By default, if a certain step fails to be handled, the effect will stop processing the remaining steps if any.

If you wish to continue even upon failure, you can add continueOnError: true to the step.

Persistence#

Internal state of an effect is persisted only in memory by default, throughout the lifecycle of the SDK instance.

If you wish to maintain the state beyond that, imagine a full application restart, you can use a storage layer.

If you are aiming for browser-based applications, the browser's localStorage is a good choice via module-localstorage.

# ...
persist: localstorage

Learn more in persistence page.

Setting up the SDK#

In your application, install the Eventvisor SDK along with your desired module(s):

$ npm install --save \
    @eventvisor/sdk \
    @eventvisor/module-pixel \
    @eventvisor/module-localstorage

And now in your application, initialize the SDK along with the module:

import { createInstance } from "@eventvisor/sdk";
import { createPixelModule } from "@eventvisor/module-pixel";
import { createLocalStorageModule } from "@eventvisor/module-localstorage";
const eventvisor = createInstance({
  datafile: { ... },
  modules: [
    createPixelModule(),
    createLocalStorageModule(),
  ],
});

Now when you load your application and track the pageView event the first time, you should see the marketing pixel injected into the page.

Archiving#

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

# ...
archived: true