Bonsai Pixel

Why it is required

The pixel establishes _bonsai_s, the first-party identifier that ties a shopper’s page views, searches, Concierge conversations and orders together. Only the pixel creates one. The search and Concierge components read it and never mint their own, because an identifier created anywhere else would join to nothing. Without the pixel, <bonsai-search> still works — but every event it emits reports NOT_SET, and none of your search analytics can be attributed to a session, a campaign or an order. The SDK says so in the browser console:

bonsai: no _bonsai_s shopper identifier on this page. Only the Bonsai pixel
establishes one — search and the concierge read it and never create their own.
Events from this page will report NOT_SET.

If you see that line, the pixel is missing from that page.

Install

Add this to every page of the storefront, ideally in <head> so it runs before the search components load. Google Tag Manager is the usual delivery path in production — one Custom HTML tag installs the queue, and one tag per funnel event calls bonsaiq("track", …).

<script>
  (function (w, d, s, u) {
    if (w.bonsaiq) return;
    var q = function () {
      q.q.push(arguments);
    };
    q.q = [];
    w.bonsaiq = q;
    var js = d.createElement(s);
    js.async = true;
    js.src = u;
    var f = d.getElementsByTagName(s)[0];
    f.parentNode.insertBefore(js, f);
  })(window, document, "script", "https://assets.hibonsai.com/sdk/bonsai-pixel-snippet-latest.js");

  bonsaiq("init", {
    apiKey: "YOUR_PUBLIC_API_KEY",
    cookieDomain: ".example.com",
    endpoint: "https://api.hibonsai.com/rest/events/pixel",
    deliveryChannel: "bonsaiq_markup",
  });
  bonsaiq("track", "page_viewed");
</script>

`init` options

All four are required — every install states all four, so the call site fully describes the behaviour it gets.

Option	What it is
`apiKey`	Your organization’s public pixel key. Safe in page source; it carries no organization id
`cookieDomain`	The registrable domain the visitor cookie is scoped to, e.g. `.example.com`. Pass `""` to declare a deliberate single-host install
`endpoint`	The ingest URL, stated explicitly so the call site names the network the page talks to
`deliveryChannel`	Which install mechanism this is: `"gtm_container"` or `"bonsaiq_markup"`

cookieDomain must be the registrable domain with a leading dot if the identifier should survive across subdomains — www.example.com and shop.example.com otherwise get separate shoppers.

Funnel events

track accepts five event names:

Event	Fire when
`page_viewed`	Every page load
`contents_viewed`	A product detail page is viewed
`items_added`	An item is added to the cart
`checkout_started`	Checkout begins
`order_created`	An order completes

Each takes an optional payload: { contents, amount, currency, cart_token, checkout_token, event_id }.

amount is in integer minor units — 1999, not 19.99. A non-integer amount is dropped along with currency.

<script>
  bonsaiq("track", "order_created", {
    amount: 15400,
    currency: "USD",
    checkout_token: "abc123",
  });
</script>

Verify

Load a page with the pixel installed.
Confirm the console shows no _bonsai_s warning.
Run a search and confirm the request carries a shopper identifier rather than NOT_SET.

Get Started

Web Components

Support

Why it is required

Install

`init` options

Funnel events

Verify

​Why it is required

​Install

​init options

​Funnel events

​Verify

Why it is required

Install

`init` options

Funnel events

Verify