choreograph-create-pixel v1.4.1
Choreograph Create Pixel
This library lets you apply best practises to Create pixel development and implementation.
Features
- Supports scraper, segment and post-click pixels
- Supports dynamic page content updates
- Prevents scraping browser-translated content
- Continuous URL validation
- User interaction triggers
- Console debugger
Scraper pixels
Type: scraper
Scraper pixels are 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 shown 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 attributed to a website conversion. The attribution pixel collects the creative's impression ID from the URL (ccpid
query parameter) on the landing page, and the conversion pixel logs this ID as a performance metric in Create when a user performed a conversion, like a purchase.
Quickstart
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
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
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
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
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
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
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"
.
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago