Marketing pixels

In software engineering terms, a pixel is a triggerable telemetry event that sends a small HTTP request to a vendor endpoint (Meta, Google, LinkedIn, etc.).

The delivery mechanism can vary, ranging from:

• Image tag: an <img> tag that is injected into the page, or
• Script tag: custom JavaScript code via <script> tag

Eventvisor's effects in combination with module-pixel can help manage marketing pixels in a highly governed and centralized way.

Challenges#

Often times, marketing teams are using tools like Google Tag Manager (GTM) which is capable of injecting any kind of third-party scripts into the page without any engineering oversight.

While it is understandable that marketing requirements need to be met, it is also important to have visibility into what is being injected into the page for both security, compliance, and overall stability of the application.

You do not want to be woken up at 3 AM because a new marketing pixel was injected into the page, that broke the entire application and the engineering team is scrambling to fix it without knowing why it happened.

Eventvisor's approach#

Eventvisor's effects can help manage marketing pixels in a centralized way.

Effects are an agnostic way of handling side-effects in your application, which can be anything as long as there's a module that can handle it.

In our case, we can choose to use module-pixel which is designed to inject a script or HTML element into the page.

Effect definition#

We can start by defining a new effect called marketing-pixel:

description: Marketing pixel
tags:
  - web
on:
  event_tracked:
    - page_view
steps:
  - handler: pixel
    params:
      snippet: |
        <script>
          console.log("Marketing pixel injected");
        </script>
      selector: body

We just defined a new effect that:

• gets triggered every time we track page_view event, and
• proceeds to apply a handler called pixel, which contains our snippet to inject into the page

Module setup#

To make sure our application can honour this effect, we need to set it up with the right module:

$ npm install --save @eventvisor/module-pixel

And initializing the SDK with it:

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

Learn more in module-pixel page.

Avoiding multiple injections#

If you are building a single-page application (SPA), it is possible you will be tracking the page_view event multiple times throughout the lifecycle of your SDK instance.

This will lead to multiple injections of the marketing pixel into the page, which we may want avoid.

Effect's internal state can come to the rescue here:

description: Marketing pixel
tags:
  - web
on:
  event_tracked:
    - page_view
# we start with an initial internal state
state:
  injected: false
# we only proceed with the steps, if the internal state is false
conditions:
  - state: injected
    operator: equals
    value: false
steps:
  - handler: pixel
    params:
      snippet: |
        <script>
          console.log("Marketing pixel injected");
        </script>
      selector: body
  # upon successful handling of pixel module,
  # we set the internal state to true
  - transforms:
      - type: set
        target: injected
        value: true

This way, we can avoid the steps being executed multiple times, when the effect is triggered multiple times.

Remembering upon page reload#

If you are interested in triggering it only once for the user session (even upon full page reload), you can use the persistence layer to achieve that:

# ...
persist: localstorage

And make sure your application has module-localstorage installed:

$ npm install --save @eventvisor/module-localstorage

And set up when initializing the SDK:

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

This will make sure the effect's internal state is persisted in browser's localStorage, and if the script was injected already once before, it will not be injected again.

Usage of variables#

Snippets can also make use of variables, which can reference sources, like:

<script>
  console.log("Marketing pixel injected from {{ payload.url }}");
</script>

The page_view event's url property will be available as {{ payload.url }} in the snippet.