@w3f/utm-element
Version:
Web components and functions for UTM parameters data manipulation.
252 lines (187 loc) • 8.24 kB
Markdown
[](https://dl.circleci.com/status-badge/redirect/gh/w3f-webops/utm-element/tree/main)
> 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](https://www.npmjs.com/package/@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:
```html
<!-- 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
```html
<!-- 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).
```html
<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:
```html
<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:
- https://developers.google.com/web/fundamentals/web-components/customelements
- https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#customized_built-in_elements
### API
To target the UTM element, HTML element, you can use:
```javascript
// 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.
```html
<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](https://legacydocs.hubspot.com/docs/methods/forms/advanced_form_options).
> Note that a `<utm-element/>` must be present on the page for this to work.
```html
<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`
```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`
```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:
1. bump the version in `package.json`, commit and push these changes to github
2. on github's interface, create a new "release" with a **tag** named `v<package_json.version>`, example `v0.0.1`.
3. this will trigger circle-ci that will eventually publish to npm if the build succeeds (and authentication tokens are
correct in CI)
# How to remove `utm_` parameters generally in my browser
Try `au-revoir-utm` browser extension: https://github.com/Rik/au-revoir-utm
- firefox: https://addons.mozilla.org/en-US/firefox/addon/au-revoir-utm/
- chrome: https://chrome.google.com/webstore/detail/au-revoir-utm/jaibjcnlipcgpfbmedodbcddcoflhmho