> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/attribution-and-affiliate/northbeam/northbeam-pixel.md). # Northbeam Pixel Northbeam Pixel is Northbeam's JavaScript tag for client-side attribution tracking. This destination loads the Northbeam pixel in the browser and forwards page view, identity and ecommerce events to Northbeam. For server-side order reporting, see [Northbeam server](/activate/event-streaming/destinations/attribution-and-affiliate/northbeam/northbeam-server.md). ## Getting started The Northbeam pixel loads automatically, so you don't install any script yourself. You need your Northbeam Data Client ID, the UUID that identifies your account. Find it in the Northbeam dashboard under **Settings > API Keys**. If you want to track product viewed, add to cart or checkout started, register a custom goal for each one with Northbeam first. See [Custom goals](#custom-goals). ## Settings * **Destination Name** (required): a name to tell this destination apart. * **Data Client ID** (required): the UUID that identifies your Northbeam account. * **Product Viewed Goal ID** (optional): the custom goal ID registered with Northbeam for `Product Viewed`. Defaults to `product_viewed`. * **Add to Cart Goal ID** (optional): the custom goal ID registered with Northbeam for `Product Added`. Defaults to `add_to_cart`. * **Checkout Started Goal ID** (optional): the custom goal ID registered with Northbeam for `Checkout Started`. Defaults to `checkout_initiated`. * **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md). ## Connect Add **Northbeam Pixel** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps. ## Event mapping | Chord event | Northbeam event | Notes | | --------------------------------------------------------------------- | ---------------------------------------------------------- | ----- | | `page` | `trackPageView()` | | | `identify` | `identify(email)` + `identifyCustomerId("custom", userId)` | | | [`Order Completed`](/collect-data/tracking-plan/order-completed.md) | `firePurchaseEvent(orderData)` | | | [`Product Viewed`](/collect-data/tracking-plan/product-viewed.md) | `fireCustomGoal(productViewedGoalId, {})` | | | [`Product Added`](/collect-data/tracking-plan/product-added.md) | `fireCustomGoal(addToCartGoalId, {})` | | | [`Checkout Started`](/collect-data/tracking-plan/checkout-started.md) | `fireCustomGoal(checkoutStartedGoalId, {})` | | | [`Email Captured`](/collect-data/tracking-plan/email-captured.md) | `fireEmailCaptureEvent(email, {})` | | ## Page events **Northbeam call:** `window.Northbeam.trackPageView()` Chord calls `trackPageViewInitial` when it loads the Northbeam script, to capture the first page view. For that reason Chord does not forward the first `page` event it sees. Every later `page` event, such as a single-page navigation, calls `trackPageView()`. No additional attributes are sent with page events. ## Identify events Updates the Northbeam identity graph for the current visitor. **Northbeam calls:** * `window.Northbeam.identify(email)` fires when an email is present. * `window.Northbeam.identifyCustomerId("custom", userId)` fires when `userId` is present. Both calls are made independently if their respective fields are available. | Chord source (priority order) | Northbeam field | Notes | | ---------------------------------------------------------------------------------------- | --------------- | ----- | | `properties.email` > `properties.emailAddress` > `context.traits.email` > `traits.email` | `email` | | | `userId` | `customerId` | | ## Order Completed Fires a purchase conversion event with full order and line item data. The event is skipped, with a console warning, if `properties.products` is empty or if no order ID is found. **Northbeam call:** `window.Northbeam.firePurchaseEvent(orderData)` | Chord source (priority order) | Northbeam field | Notes | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `properties.cart_id` > `properties.cartId` > `properties.order_id` > `properties.orderId` > `properties.id` | `id` | A cart ID wins over an order ID when both are present. The event is skipped if none is present. | | `properties.total` > `properties.value` > `properties.price` > sum of product `price × quantity` > `properties.revenue` | `totalPrice` | `properties.revenue` is used only when the event has no products and no `total`, `value` or `price`. If the event has products, the product sum is always used before it. Defaults to `0` | | `properties.shipping` | `shippingPrice` | Defaults to `0` | | `properties.tax` | `taxPrice` | Defaults to `0` | | `properties.coupon` | `coupons` | Empty string if absent | | `properties.currency` > `properties.meta.i18n.currency` | `currency` | Defaults to `"USD"` | | `product.product_id` → `product.sku` → `product.id` | `lineItems[].productId` | | | `product.variant_id` → `product.sku` → `product.product_id` | `lineItems[].variantId` | | | `product.name` | `lineItems[].productName` | | | `product.variant` → `product.name` | `lineItems[].variantName` | | | `product.price` | `lineItems[].price` | Defaults to `0` | | `product.quantity` | `lineItems[].quantity` | Defaults to `1` | ## Custom goals Northbeam tracks Product Viewed, Product Added and Checkout Started events as custom goals. Custom goals count event occurrences only. They do not carry revenue or product data. Goal names must be registered with the Northbeam team before they appear in your Northbeam dashboard. Set the goal IDs in the destination settings to match what you have registered with Northbeam: | Setting | Default value | Chord event | | ------------------------ | -------------------- | ------------------ | | Product Viewed Goal ID | `product_viewed` | `Product Viewed` | | Add to Cart Goal ID | `add_to_cart` | `Product Added` | | Checkout Started Goal ID | `checkout_initiated` | `Checkout Started` | **Northbeam call:** `window.Northbeam.fireCustomGoal(goalId, {})` ## Email Captured Fires when an `Email Captured` track event includes a user email address. This both records the email capture goal and links the email to the current visitor in Northbeam. **Northbeam call:** `window.Northbeam.fireEmailCaptureEvent(email, {})` The event is skipped if no email is present on the event. Chord reads the email in the same order as for identify events above. ## Custom events Chord does not forward any other track event, because Northbeam accepts only the fixed set of events above. Other events are skipped with a console warning. That includes `Order Refunded`. To report refunds, also add [Northbeam server](/activate/event-streaming/destinations/attribution-and-affiliate/northbeam/northbeam-server.md). ## Initialization On the first event it handles, Chord loads `https://j.northbeam.io/ota-sp/{dataClientId}.js` and sets up a command queue to buffer calls before the script loads. `trackPageViewInitial` fires at the same time to capture the first page view. Chord tracks loading state (`fresh` → `loading` → `loaded`/`failed`) to prevent duplicate script loads. If the script fails to load, later events are silently dropped. ## CSP requirements If your site uses a Content Security Policy, allow the following domains: | Directive | Domain | | ------------- | ------------------------ | | `script-src` | `https://j.northbeam.io` | | `connect-src` | `https://j.northbeam.io` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.chord.co/activate/event-streaming/destinations/attribution-and-affiliate/northbeam/northbeam-pixel.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.