choreograph-create-pixel
Version:
This library lets you apply best practises to Choreograph Create pixel development and implementation.
197 lines (140 loc) • 9.19 kB
Markdown
# Choreograph Create Pixel
This library lets you apply best practises to [Create](https://create.choreograph.com/) pixel development and implementation.
## Features
- [x] Supports [scraper](#scraper-pixels), [segment](#segment-pixels) and [post-click](#post-click-pixels) pixels
- [x] Supports dynamic page content updates
- [x] Prevents scraping browser-translated content
- [x] Continuous URL validation
- [x] User interaction triggers
- [x] [Console debugger](#debugging)
### Scraper pixel
<small>Type: `scraper`</small>
A scraper pixel is used to scrape (collect) data from websites, and store that data as products within an advertiser's product store.
### Segment pixels
<small>Types: `viewed`, `basketed` and `purchased`</small>
Products in ads are sorted by recommendation. Segment pixels determine this recommendation on a consumer level, by storing a **cookie** at different moments or events during the consumer's journey.
### Post-click pixels
<small>Types: `attribution` and `conversion`</small>
Post-click conversion attribution tracks which clicked creative variant from an ad attributed to a website conversion. The **attribution** pixel collects and stores (through [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)) the creative's impression ID from the landing URL's `ccpid` query parameter, and the **conversion** pixel logs this ID as a performance metric in Create whenever a user performed a conversion, like a purchase.
## Quick start
The following theoretical snippet includes all pixel types, can be embedded on every page of _example.com_, and will automatically determine which pixel to enable and disable through continuous URL validation.
### ES module
```js
import Pixel from "choreograph-create-pixel";
// Scraper pixel example
new Pixel({
advertiser: 0,
type: "scraper",
// Where on the website should this pixel be enabled?
url: /example\.com\/products\/\d/,
// Scrape functions are continuously re-evaluated for value changes
scrape: {
// Data layer example
sku: () => window.dataLayer[0].product.sku,
// DOM example
name: () => document.querySelector("#product-name").innerText,
// Helper example
url: Pixel.getUrl,
},
});
// Viewed segment pixel example
new Pixel({
advertiser: 0,
type: "viewed",
url: /example\.com\/products\/\d/,
// Segment pixels only require an SKU to be scraped
scrape: () => window.dataLayer[0].product.sku,
});
// Basketed segment pixel example
new Pixel({
advertiser: 0,
type: "basketed",
url: /example\.com/,
// [Optional] Trigger by DOM events, rather than scrape content updates
trigger: {
event: "click",
elements: "button.basket[data-sku]",
},
// The "element" parameter only becomes available when using a trigger
scrape: (element) => element.getAttribute("data-sku"),
});
// Purchased segment pixel example
new Pixel({
advertiser: 0,
type: "purchased",
url: /example\.com\/cart/,
trigger: {
event: "click",
elements: "button.checkout",
},
// Segment pixels support multiple SKUs
scrape: () => window.dataLayer[0].cart.map((product) => product.sku),
});
// Attribution post-click pixel example
new Pixel({
advertiser: 0,
type: "attribution",
// Uniquely label each set of post-click pixels
label: "example",
// Match this URL to the landing page of your campaign
url: /example\.com\/products\/\d/,
});
// Conversion post-click pixel example
new Pixel({
advertiser: 0,
type: "conversion",
label: "example",
// Match this URL to the conversion page of your campaign
url: /example\.com\/cart/,
trigger: {
event: "click",
elements: "button.checkout",
},
});
```
> ES modules require manual bundling and transpiling before they can be safely embedded on websites.
### CDN library
This alternative implementation method allows for direct embedding on pages without the need for bundling nor transpiling.
```html
<script src="https://cdn.jsdelivr.net/npm/choreograph-create-pixel@1"></script>
<script>
new ChoreographCreatePixel({
// ...
});
new ChoreographCreatePixel({
// ...
});
</script>
```
## Debugging
Enable browser console debugging by adding `?pixel_debug` or `#pixel_debug` to the page's URL.
## Configuration
| Property | Type | Description | Default |
| ------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `advertiser` | Number | You can retrieve the advertiser ID from the URL in Create: _manage.lemonpi.io/r/AGENCY_ID/advertiser/`ADVERTISER_ID`_. | _Required_ |
| `type` | String | Pixel type. One of: `"scraper"`, `"viewed"`, `"basketed"` or `"purchased"`. | _Required_ |
| `label`<br>_(post-click only)_ | String | Conversion label, used for aggregation in reporting. | _Required_ |
| `url` | RegExp | Only enables the pixel on page URLs that are matched by this pattern. | _Required_ |
| `scrape`<br>_(segments only)_ | String, Array or Function | Scrapes the product's SKU for segments. | _Required_ |
| `scrape.*`<br>_(scrapers only)_ | String, Number, Boolean or Function | Scrapes arbitrary product data. `*` should always match with existing field names in the advertiser's product store. | _Required_ |
| `trigger` | Object | Adds an event listener to enable the pixel only on a specific DOM event, instead of on scrape content updates. | `undefined` |
| `trigger.event` | String | DOM event type. [List of supported values.](https://www.w3schools.com/jsref/dom_obj_event.asp) | _Required_ |
| `trigger.elements` | String, Function | This query selector string, or function returning DOM element(s), is used to apply the event listener to. | _Required_ |
| `optional`<br>_(scrapers only)_ | Array | An array of field names (as used in `scrape.*`) that are allowed to have empty values. | `[]` |
| `before` | Function | A custom function that's executed just before the pixel is executed. | `(scrapedData, callback) => { callback(scrapedData); }` |
| `after` | Function | A custom function that's executed just after the pixel has been executed. | `(scrapedData) => {}` |
## Static methods (helpers)
### `.getUrl({ allowedQueryParameters, allowHash })`
Returns the bare page URL without query parameters or location hash. This is highly recommended to exclude (UTM) tagging, or other unwanted side effects.
| Property | Type | Description | Default |
| ------------------------ | ------- | ----------------------------------------------------------------- | ------- |
| `allowedQueryParameters` | Array | Explicitly allow query parameters in the URL. | `[]` |
| `allowHash` | Boolean | Explicitly allow including the location hash (`#foo`) in the URL. | `false` |
### `.getAllPathSegments()`
Retrieves all path segments from the URL as an array. E.g. _http://www.example.com/foo/bar_ returns `["foo", "bar"]`.
### `.getPathSegment(index)`
Retrieves a specific segment from the URL. E.g. `getPathSegment(0)` on _http://www.example.com/foo/bar_ returns `"foo"`.
### `.getAllQueryParameters()`
Retrieves all query string parameters from the URL as an object. E.g. _http://www.example.com/?foo=bar_ returns `{ foo: "bar" }`.
### `.getQueryParameter(key)`
Retrieves a specific query parameter from the URL. E.g. `getQueryParameter('foo')` on _http://www.example.com/?foo=bar_ returns `"bar"`.