Pixel JavaScript API¶
The AdRoll Pixel provides a JavaScript API that allows you to track custom events and pass product information directly from your website. This complements the automatic page view tracking that the pixel provides by default.
On this page
Overview¶
The Pixel v2 JavaScript API is available through the global adroll object. You can use this API to:
Track custom user events
Pass product information for dynamic ads
Capture conversion data with custom attributes
The API is designed to work alongside the standard pixel installation and does not require any additional setup beyond placing the pixel code on your site.
Prerequisites¶
Before using the JavaScript API, ensure you have:
Installed the AdRoll Pixel on your website header
Verified the pixel is firing correctly using PixelPal or the Pixel Assistant
Tracking Events¶
Use the track() method to send custom events to AdRoll. This method allows you to pass product attributes like price, quantity, and category along with the event.
Basic Event Tracking¶
adroll.track("pageView");
Event with Product Data¶
adroll.track("addToCart", {
product_id: "SKU-12345",
product_group: "electronics",
price: 99.99,
quantity: 1,
category: "smartphones"
});
Supported Events¶
The following event names are supported and recommended for use with User Event Audiences:
B2C Events¶
pageViewGeneral page view event
homeViewHomepage view
productSearchProduct search performed
addToCartProduct added to shopping cart
purchasePurchase completed
B2B/ABM Events¶
highValuePageHigh-value page visit (e.g., pricing page, key feature page)
gatedContentGated content accessed (e.g., whitepaper, ebook)
demoRequestProduct demonstration requested
signupPlanSignup for a specific plan or subscription
signupTrialFree trial signup
contactSalesContact initiated with sales team
liveChatLive chat session engaged
formFillForm completed (general forms not covered by specific events)
Event Attributes¶
When tracking events, you can include the following product attributes:
product_idUnique identifier for the product (e.g., SKU)
product_groupProduct category or group identifier
product_actionAction performed on the product
categoryProduct category name
priceProduct price (numeric value)
quantityQuantity of the product (numeric value)
Example: E-commerce Tracking¶
Product Page View¶
adroll.track("pageView", {
product_id: "PROD-789",
product_group: "apparel",
category: "t-shirts",
price: 24.99
});
Add to Cart¶
adroll.track("addToCart", {
product_id: "PROD-789",
product_group: "apparel",
category: "t-shirts",
price: 24.99,
quantity: 2
});
Purchase Conversion¶
adroll.track("purchase", {
product_id: "PROD-789",
product_group: "apparel",
category: "t-shirts",
price: 24.99,
quantity: 2
});
Retrieving the First-Party Cookie¶
You can retrieve the AdRoll first-party cookie value using a callback function. This is useful for server-to-server event tracking.
adroll.get_first_party_cookie(function(cookie) {
console.log("AdRoll first-party cookie:", cookie);
// Send cookie to your server for S2S tracking
});
For more information on using the first-party cookie with server-to-server events, see Server-to-Server (S2S) API Overview.
Best Practices¶
Use Supported Event Names¶
Always use the supported event names (pageView, homeView, productSearch, addToCart, purchase, etc.) when creating User Event Audiences. This ensures your audiences are properly configured.
Product IDs¶
Use consistent product identifiers across all events. This allows AdRoll to properly track product engagement and power dynamic ad campaigns.
Test Your Implementation¶
Use PixelPal to verify that your custom events are firing correctly and that product data is being captured.