Skip to main content

Integrating Snowplow trackers

work in progress

We're busy building, and this is one of those things that is a work in progress!

This guide will take you through how to collect customer data from your website using some tools from another great open source project Snowplow, specifically their web behaviour trackers. Openline can use these trackers to ingest clickstream data (such as page opens, clicks and other events) such that you can actively and securely load customer interaction data into customerOS.

Openline's customerOS should be compatible with all 3 types of Snowplow trackers:

  • Browser tracker v3 ✅
  • Javascript Tracker (v2 ❓ and v3 ❓)
  • Node.js Tracker v3 ❓

(Emoji indicates whether compatibility has been established)

Examples​

Snowplow Browser Tracker v3 on React (Docusaurus)​

To get started, follow the instructions here to install the browser tracker onto your React application.

Install the @snowplow/browser-tracker package using your preferred package manager:

npm install @snowplow/browser-tracker
yarn add @snowplow/browser-tracker
pnpm add @snowplow/browser-tracker

Once installed, add the component to your code, Openline's implementation to it's React-based Docusaurus site deployed on Vercel can be found here and as follows:

Tip

We recommend using a proxy to prevent events getting blocked by ad-blockers and browsers.

When implementing the newTracker function, it's recommended to proxy the domain to your server before sending to the collector. The reason for doing this is browsers and ad-blockers commonly prevent this traffic from being sent to a 3rd party location. To avoid this, we use Vercel Middleware to rewrite the internal URL of the domain and post path to the external URL and post path.

newTracker(openline-help-widget-dev, {{internal_domain}}, {
    appId: openline-help-widget,
    discoverRootDomain: true,
    cookieSecure: true,
    cookieSameSite: "None",
    eventMethod: "post",
    postPath: "/ai.openline.sp/tp2",
    platform: "web",
    bufferSize: 1,
    contexts: {
        webPage: true
    },
});

In the above example, we use Docusaurus' siteConfig parameters to replace {{internal_domain}} with the root domain found at siteConfig.url which then takes the postpath and redirects it using the following vercel.json file to rewrite it to send it to the correct address from the server, avoiding both ad-blockers and browser blocks. You could also easily just provide a static URL of your website.

{
    "rewrites": [
      {
        "source": "/ai.openline.sp/tp2",
        "destination": "https://lzdyxrxc-uat-ninja.openline.ai/ai.openline.sp/tp2"
      }
    ]
  }

What this achieves is all user tracking information will be sent to the Openline Vercel server before being proxied to the final destination outside of the site's root domain.

If you don't want to proxy via your server and are willing to run the risk of lost data, a basic non-proxied configuration would look like the following:

newTracker(openline-help-widget-dev, https://events.openline.ai, {
    appId: openline-help-widget,
    discoverRootDomain: true,
    cookieSecure: true,
    cookieSameSite: "None",
    eventMethod: "post",
    postPath: "/ai.openline.sp/tp2",
    platform: "web",
    bufferSize: 1,
    contexts: {
        webPage: true
    },
});

Openline Cloud parameters​

Of the fields above, the following settings should be created by Openline (this will be self-managed soon via Openline Settings). Reach out to us to get these setup for you!

  • trackerId
    • e.g. openline-website-tracker-production-9h8yztcjr4kvitsu
  • appId
    • e.g. openline-website-f6k4o8zqz7b1lpas
  • Url
    • https://events.openline.ai

Self-hosted parameters​

If you are self-hosting customerOS, the following should be updated specfically to your deployment:

  • trackerId
    • Name of the tracker
  • appId
    • Name of the application you are tracking users on
  • Url
    • The root URL to send your user events to
  • postPath
    • The path of the URL to send your user events to
info

It's highly recommended not to use words such as tracker or collector as this can get automatically blocked by browsers and ad-blockers.

Embedding on your site​

Now we have created the tracker function, this should be added and loaded on every page in your application in order to capture all user events.

With React this is done using the useEffect function, we are also tracking link clicks and sending a heartbeat in order to measure time spent on page:

import React, {useEffect} from 'react';
import {newTracker, enableActivityTracking, trackPageView} from '@snowplow/browser-tracker';
import {LinkClickTrackingPlugin, enableLinkClickTracking} from '@snowplow/browser-plugin-link-click-tracking';

export default function OpenlineTracker(props) {
    useEffect(() => {
        newTracker(openline-help-widget-dev, https://events.openline.ai, {
            appId: openline-help-widget,
            discoverRootDomain: true,
            cookieSecure: true,
            cookieSameSite: "None",
            eventMethod: "post",
            postPath: "/ai.openline.sp/tp2",
            platform: "web",
            bufferSize: 1,
            contexts: {
                webPage: true
            },
            plugins: [LinkClickTrackingPlugin()],
        });

        enableActivityTracking({
            minimumVisitLength: 30,
            heartbeatDelay: 30
        });

        enableLinkClickTracking({
            pseudoClicks: true,
            trackContent: true
        });

        trackPageView({}, openline-help-widget-dev);

    }, []);
    return (
        <></>
    )
}

Finally we add the tracker component to every page using the following code:

<OpenlineTracker/>

What can we collect?​

By default with the above settings, Openline will collect the following:

  • Page views
  • Clicks

With additional configuration, the following can be collected:

  • Custom events

What happens to this data?​

  • Openline collects this as atomic events, providing raw data to manipulate into useful aggregations and views
    • This data includes sessions, page views, clicks, visitors and metadata attached to these
  • Once the atomic events are collected, customerOS then processes this high fidelity data and collates it into more usable modelled tables that are queryable via customerOS's GraphQL
    • This allows us to connect visitor and user session data to customerOS users

What can I do with this data?​

  • Query it via customerOS's GraphQL API
  • View in Openline Contacts
    • Enriched application user data visible alongside your contact data
  • View in Openline Oasis
    • Enriched application user data visible alongside your conversations
  • Openline Analytics (soon)
How can we help?
How can we help?