> ## Documentation Index > Fetch the complete documentation index at: https://docs.northbeam.io/llms.txt > Use this file to discover all available pages before exploring further. # All Other Platforms Installation > Add the Northbeam pixel to your storefront ## Northbeam Pixel Installation There are two methods of installing the pixel: * Pasting the pixel in the header of your theme file * Creating it as a tag within Google Tag Manager
You’ll need to install this script in the `` 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](https://dashboard.northbeam.io/settings/api-keys). Do not modify the script Other than setting your Data Client ID, **do not modify the script in any way**. ```html theme={null} ``` Content Security Policy In order for the pixel to use this subdomain, your Content Security Policy (CSP) must explicitly or implicitly allow traffic to the i subdomain. Please make sure your CSP includes either: * `*.your-store.com`, or * `i.your-store.com` in the connect-src of your CSP.
*** ## `firePurchaseEvent` Installation
Use the `window.Northbeam.fireSlimPurchaseEvent` OR `window.Northbeam.firePurchaseEvent` Northbeam Pixel JavaScript function for any non-Shopify native checkout. These functions **equally** signal that a **conversion** has taken place within the visitor's session, but the target function to use depends on your usage intent, available fields, and actionability requirements. | Function Name | Usage | Complexity | | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | | `fireSlimPurchaseEvent` | Directly targets an order for attribution if the only guaranteed value is the Order Number and/or when backend revenue data will be sent on time for actionability. **This our default recommended function**. | Low | | `firePurchaseEvent` | Directly targets an order for attribution when revenue values need to be actionable before backend revenue data is sent to us. | Moderate | *Either* event **must** fire when a transaction is completed — once the final order details are available — typically on the **Order Confirmation** or **Thank You** page. A timely and proper trigger is required for purchase matching in Northbeam, and they can be deployed natively into your site's code or injected externally via Google Tag Manager.
### Global Requirements (both `fireSlimPurchaseEvent` and `firePurchaseEvent`) **Your chosen function must:** * Fire **after the core Northbeam base pixel.** * Fire **only after the order is finalized and all charges have been processed** to prevent ingestion of cancelled transactions. * Fire **once per completed order; do not repeat `id` values.** * Contain **all corresponding keys with defined values**. `NULL` values are invalid.
### Critical: `id` = `order_id` We use the value from the `id` key (Please see function requirements below) to match the frontend purchase event (`fireSlimPurchaseEvent` AND/OR `firePurchaseEvent`) to your backend source of truth (orders sent via the [Northbeam Orders API](/reference/post_orders)). If the value does not exactly match the corresponding server-side order (Case-sensitive): that purchase will not attribute correctly. It is **strongly** recommended that someone with basic JavaScript knowledge implements these scripts. ***Important:*** Historical purchase data cannot be recovered. An improper implementation will result in missing attribution. Thus: It is **critical** that `fireSlimPurchaseEvent` / `firePurchaseEvent` is configured correctly from day one.
### *window\.Northbeam.fireSlimPurchaseEvent* #### Definitions This lightweight function signals that the order/transaction number passed in the `id` field is a valid conversion that should be attributed. It only requires a single value for activation. This is our**primary recommended function for most\* implementations**. | Key | Type | Description | Example | | :--- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `id` | *String* | The actual transaction/order number. It must be an exact match to the [Northbeam Orders API](/reference/post_orders) `order_id` value for stitching. Must be a `string` containing at least 1 character and it's case-sensitive. | "A123" |
#### fireSlimPurchaseEvent example ```javascript theme={null} ``` * Note: The `id` key/field is an **implicit parameter** in `fireSlimPurchaseEvent` and does ***not*** need to be externally defined for the function to operate. It only needs a *value*, which is automatically mapped to the implicit `id` key. * In the above example: "A123" is a hard-coded string with your order\_id, but this should be a variable that ties to the value. #### Considerations * `fireSlimPurchaseEvent` does *not* process monetary values and is therefore not recommended when operational actionability is a crucial consideration -AND- your corresponding backend Northbeam API upsert implementation is not synchronized to your Dashboard processing cycles. On such cases: `firePurchaseEvent` is best used instead of `fireSlimPurchaseEvent`.
### *window\.Northbeam.firePurchaseEvent* #### Definitions This full-fledged function not only signals that the order/transaction number passed in the `id` field is a valid conversion that should be attributed, but it also contains transactional information that is actionable for revenue, tax, and shipping calculations in your Northbeam Dashboard. This function **requires** a full transactional object `{}` with distinct keys rather than the `order_id` string alone, which increases complexity and should only be used when actionable data is a crucial concern -AND- your corresponding backend Northbeam API upsert implementation is not synchronized to your Dashboard processing cycles.
Key Type Description Example
`id` *String* The actual transaction/order number. It must be an exact match to the [Northbeam Orders API](/reference/post_orders) `order_id` value for stitching. Must be a `string` containing at least 1 character and it's case-sensitive. "ORD98"
`totalPrice` *Number* The final paid value *after* taxes, shipping, and discounts. Must be a positive `number`. 12
`shippingPrice` *Number* The value for shipping charges. Must be a positive `number`. 6
`taxPrice` *Number* The value for tax charges. Must be a positive `number`. 7
`coupons` *String* Discount coupons applied to the order. Must be a single `string`, but multiple values can be separated via comma as a single string (EX: `"coupon 1, coupon 2"`). "PROMO 4"
`currency` *String* The currency code of the transaction. Must be a 3-digit `string` using the [3-digit ISO-4217 standard](https://www.iso.org/iso-4217-currency-codes.html). "USD"
`customerId` *String* The visitor/customer identifier. Must be a `string` containing at least 1 character. "VICTOR12"
`lineItems` *Array `[]` of Objects `{}`* The list of individual items purchased in the order. This is a ***single*** array `[]` composed of individual objects `{}` (One per product) all nested within the array. The object uses the following keys (Which must all exist and contain a value): `productId`, `variantId`, `productName`, `variantName`, `price` and `quantity`. `[{productId: "SKU-0001", variantId: "0001-A", productName: "Pants", variantName: "Blue", price: 10, quantity: 1}]`
`productId` *String* The identifier for the global parent product. Must be a `string` containing at least 1 character. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. "SKU-01"
`variantId` *String* An identifier used if the global parent product has an alternative identifier or sub-type identifier. Must be a `string`. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. "VAR-01"
`productName` *String* The commercial product name for the purchased item. Must be a `string` containing at least 1 character. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. "Hat"
`variantName` *String* An identifier used if the item name has a sub-type or alternative name. Must be a `string`. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. "Green Hat"
`price` *Number* The gross merchandise value of the item in the current object. Must be a positive `number`. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. 12
`quantity` *Number* The number of times the item in the current object was purchased. Must be a positive `number`. Belongs to the `lineItems` array `[]` of objects `{}` and can not be used outside the object. 2

#### firePurchaseEvent example ```javascript theme={null} ``` * Note: The payload must be structured as an object and thus wrapped in curly brackets `{}`. * In the above example: "ORD98" is a hard-coded string with your order\_id, but this should be a variable that ties to the value.
#### Considerations * Values from `totalPrice`, `shippingPrice` and `taxPrice` will directly power Northbeam Dashboard metrics tied to revenue, shipping, and taxes respectively. * The Northbeam Orders API is the ultimate source of truth. In case of a value conflict with the corresponding `order_id` payload: Values from `firePurchaseEvent` will be overwritten and replaced by the Northbeam API value. * Timely/synchronized Northbeam Orders API upserts negate the need to use `firePurchaseEvent`. We recommend using `fireSlimPurchaseEvent` with synchronized API Upserts when possible.
### Validation and testing A valid/fully-compliant event trigger for *either* `fireSlimPurchaseEvent` or `firePurchaseEvent` shows a network request (**nb-collector**) with a payload containing the data object **ue** (`data: [{e: "ue",…}]`) alongside second payload containing the data object **se** (`data: [{e: "se",…}]`). The **se\_la** key of the **se** object **contains the order number we received** . These 2 events and network requests are only ever seen together as requests when the trigger is valid. These events can can only be reviewed if the network console is open *before* the event fires. They can not be reviewed after the fact.
### Sequencing The [Northbeam base pixel](/docs/add-pixel) must fire **before** `firePurchaseEvent`. If deploying via Google Tag Manager, configure tag sequencing correctly: [https://support.google.com/tagmanager/answer/6238868?hl=en](https://support.google.com/tagmanager/answer/6238868?hl=en) Improper sequencing may prevent the purchase event from registering.
### Publishing If deploying via Google Tag Manager: * Ensure the tag is configured correctly * Publish the container Unpublished containers will prevent tracking.
### Final Checklist Before going live, confirm: * `firePurchaseEvent` fires on the confirmation page * It fires once per order * The Order ID matches backend data exactly (Orders API) * The base pixel fires first * GTM container is published If these conditions are met, purchase matching will function correctly.
### Best Practices * Wrap `fireSlimPurchaseEvent` or `firePurchaseEvent` in a function that logs if the script was successful or if it failed. This eases debugging and validation. * Wrap `fireSlimPurchaseEvent` or `firePurchaseEvent` in a function that checks if `window.Northbeam` is defined and ready to push the function, or retry if it isn't. This helps with scrip sequencing issues.
#### fireSlimPurchaseEvent with debug function example ```javascript theme={null} ```