@w3f/utm-element NPM

About UTM parameters: https://en.wikipedia.org/wiki/UTM_parameters

`utm-element`

An html/js custom element (web-component) and set of javascript functions, to store and retrieve UTM parameters data from URLs (and pass them to new URLs).

@w3f/utm-element public npm registry package
https://unpkg.com/@w3f/utm-element/
https://www.jsdelivr.com/package/npm/@w3f/utm-element
https://github.com/w3f-webops/utm-element

Usage

The easiest way to get started, is to look at the ./index.html file, for an example usage.

Insert the element <utm-element></utm-element>, in the pages where the UTM parameters in the URL should be manipulated.

You can:

<!-- insert our custom element -->
<utm-element></utm-element>

<!-- import and define the custom element -->
<script type="module">
  /* import the element's definition */
  /* import {UtmElement} from 'https://unpkg.com/@w3f/utm-element/index.js' */
  import {UtmElement} from '@w3f/utm-element'

  /* reference the custom element, so HTML inherits the js functionnalities */
  customElements.define('utm-element', UtmElement)
</script>

Or alternativelly, we do not insert our custom element in HTML, but with Javascript

<!-- import, define and insert (in DOM) the cutom element -->
<script type="module">
  import {UtmElement} from 'https://unpkg.com/@w3f/utm-element/index.js'

  /* define the UTM element,
  so it can be used in the DOM (append to <body>) */
  (function() {
    customElements.define('utm-element', UtmElement)
    const $utmElement = document.createElement('utm-element')
    document.querySelector('body').append($utmElement)
  })()
</script>

`is="utm-link"`

There is a convenience component, that will extend an existing anchor (ex <a href="">Test</a>) element.

One advantage of the is="" component instanciation, is that itcan only be used on an <a> DOM element; so if the javascript is not loaded (to define the element), the anchor will still work normally (but wont append the UTM params).

<script type="module">
    // import the element's definition
    import {
      defineUtmElement,
      insertUtmElement,
      defineLinkElement,
    } from './index.js'

    defineUtmElement()
    insertUtmElement()

    /* define after the utm-element (is defined and injected),
       or we won't have access to its data */
    defineLinkElement()
</script>

Now we can then use the link in our HTML like so:

<a is="utm-link" href="https://example.org">example.org</a>

This link will have its default href updated to the same one, appended of the utm query params avalaible in utm-element.

It cannot be instanciated with <utm-link href=""></utm-link>, as it needs to be an anchor element, to be able to inherit its HTML DOM element properties.

Docs:

API

To target the UTM element, HTML element, you can use:

// assign the DOM element to a variable
const $utmElement = document.querySelector('utm-element')

// retrieves the list of UTM params and their values
const utmData = $utmElement.getUtm()

// save UTM data, a list of objects with the keys:
// key: the UTM param to be stored/injected
// value: the value of the UTM param
const newUtmData = [
  {
    key: "ref",
    value: "example.org"
  },
  {
    key: "utm_test",
    value: "example_value"
  }
]
$utmElement.setUtm(newUtmData)

// append all UTM params to a url
const urlToTransform = 'https://example.com/'
const urlTransformed = $utmElement.setUtmOnUrl(urlToTransform)
// 'https://example.com/?ref=example.org&utm_test=example_value'

With a hubspot form (v2)

Sometimes we want to get the UTM parameter of a user that entered the site (across page change and refresh), into a hubspot form (newsletter etc.).

Because hubspot tracks the extact URL from which a form has been submitted, it can also get the query params (and therefore UTM query params) the URL was submitted with.

With the folowing astuce, before the form is submitted by the user, we retrieve the UTM parameters, that were present when the user entered the site, and re-inject them to the current hubspot form hidden fields.

<script charset="utf-8" type="text/javascript" src="//js.hsforms.net/forms/v2.js"></script>
<script type="module">
/* import the element's definition from cdn */
import {
 hubspotOnFormReady
} from 'https://unpkg.com/@w3f/utm-element/index.js'

hbspt.forms.create({
 portalId: 'abcd',
 formId: '1234',
 onFormReady: hubspotOnFormReady
});
</script>

More hooks are available, see hubspot forms docs.

Note that a <utm-element/> must be present on the page for this to work.

<script type="module">
  /* import the element's definition from cdn */
  import {
    defineUtmElement,
    insertUtmElement
  } from 'https://unpkg.com/@w3f/utm-element/index.js'

  /* define the UTM element, to be use as DOM element */
  defineUtmElement()

  /* append the utm-element to the <body> in the dom */
  insertUtmElement()
</script>

In the hubspot form GUI, there should be matching hidden fields for this form. The “Internal Name” (all lowercase to match the URL parameter name in the URL) of the hubspot property, for each UTM parameters expected to be received, if you want them to be saved in hubspot's interface.

Withing gatsby/react (and hubspot)

In gatsby-browser.js

import { UtmElement } from '@w3f/utm-element';
if (global.window) {
  customElements.define('utm-element', UtmElement);
}

Insert the <utm-element></utm-element>, in src/html.js, or in the pages/place you'd need it to be accessible.

In a custom components/MyHubpostForm.js

import MyHubspotForm from 'react-hubspot-form';
import { hubspotOnFormReady } from '@w3f/utm-element/index.js';

export default function MyHubspotForm() {
  const $formRef = useRef(null);
  return (
    <HubspotForm
      ref={$formRef}
      portalId="abcd"
      formId="1234"
      onSubmit={() => console.log('Submit!')}
      onReady={(event) => {
        // our functions expect an hubspot v2 event,
        // an array, from which the 1st element is the form
        const res = hubspotOnFormReady([$formRef.current.el])
        console.log('Ready and setup with utm!', res)
      }}
    />
  );
}

react and web-components (`class` vs `className`)

One common confusion is that Web Components use “class” instead of “className”.

Source: https://reactjs.org/docs/web-components.html#using-web-components-in-react

So when using is="utm-link on an anchor <a href="" is="utm-link"></a>, don't forget to use class, otherwise styles and HTML classes won't be applied.

Development

cd utm-element, move into this project
npm install, to install the project dependencies
npm develop, to start the local development server

Build

There is no build system, for development or production.

All files are publish to npm without minification or compilation.

Publish a new version to npm package registry

You will need to:

bump the version in package.json, commit and push these changes to github
on github's interface, create a new "release" with a tag named v<package_json.version>, example v0.0.1.
this will trigger circle-ci that will eventually publish to npm if the build succeeds (and authentication tokens are correct in CI)