@builder.io/persist-attribution

Persist attribution info between visits.

This package is intended to be published to NPM and used with a JS delivery CDN, so it can be included in any of our sites with a simple script tag.

Developing

Run tests with:

yarn test

Publishing

(TODO)

Usage in sites

Include this script tag in your HTML:

<script src="//cdn.jsdelivr.net/npm/@builder.io/persist-attribution@latest/dist/persist-attribution.min.js" async defer></script>

You coul also change persist-attribution@latest with persist-attribution@0.1.3 (for example) to explicitly use version 0.1.3 of this script.

By default, that will:

• Persist as cookies most utm_* query params in the current window.location (configurable with data-persist-utms):
• Persist as cookie the visitor ID assigned to this session (cookie is only written if it doesn't exist) (configurable with data-persist-visitor-id):
• Persist as cookie the current value of document.referrer (configurable with data-persist-referrer):
• Persist as cookie the current value of document.referrer as "initial referrer" if the corresponding cookie is not send. (configurable with data-persist-initial-referrer):

All those options are enabled by default (true). There's another configurable option named data-send-page-view-events (disabled by default) that when enabled will send pageView events to our internal analytics endpoint. However it will only send events if there's a visitor ID (cookie) already present, so most likely you will need data-persist-visitor-id to be true as well.

For example, let's say we only care about pageView events (we don't care about utm_* stuff) we would tweak the script tag like:

<script
  src="//cdn.jsdelivr.net/npm/@builder.io/persist-attribution@latest/dist/persist-attribution.min.js"
  async
  defer

  id="persist-attribution-init"

  data-persist-visitor-id="true"
  data-send-page-view-events="true"

  data-persist-utms="false"
  data-persist-visitor-id="false"
  data-persist-referrer="false"
  data-persist-initial-referrer="false"
></script>

Note that id="persist-attribution-init" is required for configuration to work; the code will look for the HTML element with this ID and read the data-* attributes from it. If no element with this ID is found the default config will be used. Using an id attribute is necessary so we can define configuration using data-* attributes on the same element AND also being able to use async and defer.