Northbeam DashboardQuestions? Reach out to our team!
Technical Guides

Standard Installation

Add the Northbeam pixel to your storefront

Install the pixel on every page of your site to track visits

You’ll need to install this script in the <head> section of every page on your site. Be sure to replace {DATA_CLIENT_ID} with your unique Northbeam Data Client ID, which you can find here.

🚧

Do not modify the script

Other than setting your Data Client ID, do not modify the script in any way.

<!-- Begin: Northbeam pixel -->
<script>(function(){var r;(e=r=r||{}).A="identify",e.B="trackPageView",e.C="fireEmailCaptureEvent",e.D="fireCustomGoal",e.E="firePurchaseEvent",e.F="firePurchaseSyncEvent";var e="//j.northbeam.io/ota-sp/{DATA_CLIENT_ID}.js";function t(e){for(var n=[],r=1;r<arguments.length;r++)n[r-1]=arguments[r];a.push({fnName:e,args:n})}var a=[],n=((n={_q:a})[r.A]=function(e,n){return t(r.A,e,n)},n[r.B]=function(){return t(r.B)},n[r.C]=function(e,n){return t(r.C,e,n)},n[r.D]=function(e,n){return t(r.D,e,n)},n[r.E]=function(e){return t(r.E,e)},n[r.F]=function(e){return t(r.F,e)},window.Northbeam=n,document.createElement("script"));n.async=!0,n.src=e,document.head.appendChild(n);})()</script>
<!-- End: Northbeam pixel -->

Implement firePurchaseEvent to track purchases

After embedding the pixel on every single page you will need to implement the firePurchaseEvent JavaScript function at every conversion point in your store. This script can be deployed through Google Tag Manager, or hardcoded on your website.

  • The firePurchaseEvent data should match what you upload to Northbeam through the orders API.

firePurchaseEvent

<script type="application/javascript">
   window.Northbeam.firePurchaseEvent({
   id: "The order ID",
   totalPrice: 100,
   shippingPrice: 10,
   taxPrice: 5.5,
   coupons: "SALE20,FAMILY10",
   currency: "USD",
   customerId: "The customer ID",
   lineItems: [
     {
       productId: "SKU1",
       variantId: "VARSKU1",
       productName: "Socks",
       variantName: "Blue",
       price: 12,
       quantity: 10,
     },
     {
       productId: "SKU2",
       variantId: "VARSKU2",
       productName: "Bucket",
       variantName: "Small",
       price: 180,
       quantity: 1,
     }]
   })
</script>
FieldTypeDescription
idStringA unique identifier for the order that was placed. Must be unique among all orders. For custom setups on Shopify, make sure this is the Order Number and not the Order Name or Order ID.
totalPriceNumberThe total amount collected for the purchase.
shippingPriceNumberShipping fees charged to the customer for this purchase.
taxPriceNumberTaxes charged to the customer for this purchase.
couponsStringA comma separated list of discount codes used.
currencyStringA 3-character ISO currency code describing totalPrice, taxPrice, and shippingPrice.
customerIdStringA unique identifier for the customer who made a purchase.
lineItemsArray<Product>Array of line items
lineItems.$.productIdStringItem product identifier
lineItems.$.variantIdStringItem variant identifier
lineItems.$.productNameStringItem product name
lineItems.$.variantNameStringItem variant name
lineItems.$.priceNumberItem price
lineItems.$.quantityNumberItem quantity

Video guide

firePurchaseEvent Considerations

To make sure that your firePurchaseEvent is triggering correctly, please see the below list of considerations. Any misfires will cause a lack of tracking and attribution for any associated orders.

🚧

Any missing or incorrect historical pixel data cannot be recovered.

It's extremely important that your firePurchaseEvent implementation is validated early to prevent lost data.

It's recommended that somebody with basic Javascript knowledge sets up the script to decrease the likelihood of any issues.

Macros

The values in the script above are placeholders (ex. "The Order ID", "100", "USD"). Be sure to replace these with the corresponding macros.

If deploying via Tag Manager, these order details need to be passed to the Data Layer. From here, variables will need to be created, which can then be used within your GTM Tag.

customerId

In some instances, some of our customers do not use a customerId (or an equivalent value) -- for something like guest checkout. If this applies to you, please use the customer email address as a last resort.

For context, we use the Customer IDs to inform our First Time and Returning Customer data, as well as Customer LTV data, so it's very important to populate these values as accurately as possible.

Values cannot be Empty or Null

If a specific value does not exist, please pass a "blank" or 0 value -- depending if it's asking for a string or numeric value.

For example, let's say there isn't a taxPrice or any coupons. The keys and values should be:

  taxPrice: 0, 
  coupons: "",

Sequencing

Please make sure the Northeam Pixel fires BEFORE the Purchase Pixel. If you're deploying via Google Tag Manager, learn more about sequencing here.

Publishing

If deploying via Google Tag Manager, please make sure the tag is published in your container.

Updated 4 months ago