Choreograph Create Pixel

This library lets you apply best practises to Create pixel development and implementation.

Features

• [x] Supports scraper, segment and post-click pixels
• [x] Supports dynamic page content updates
• [x] Prevents scraping browser-translated content
• [x] Continuous URL validation
• [x] User interaction triggers
• [x] Console debugger

Scraper pixel

Type: scraper

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

Types: viewed, basketed and purchased

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

Types: attribution and conversion

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) 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

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.

<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(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(segments only) | String, Array or Function | Scrapes the product's SKU for segments. | Required | | scrape.*(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. | 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(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".