Browser · window.axo

Tag JS API

Once the tag loads it exposes window.axo. Every method is safe to call from page-level JS — calls made before init are queued. Personalization zones are authored declaratively with data-vt-* attributes.

Install

One deferred, first-party script before </head>. See Getting Started for the full install (Shopify, anti-flicker) and Site Speed for the load model.

HTML

<script src="https://axoapp.ai/tag.js?site=YOUR_SITE_ID" defer></script>

Identify a visitor

JavaScript

// Call after login, checkout, or a form submit.
axo.identify({
  email: "customer@example.com",
  external_id: "usr_12345",
  // any additional traits become profile attributes:
  plan: "pro"
});

Conversions & cart

JavaScript

// SPA / custom-flow escape hatch — fire the primary goal manually.
axo.convert(149.00);        // optional revenue value

// Pass cart state so /api/convert can attach line items:
axo.setCart([
  { sku: "SKU-1", qty: 2, price: 24.0 },
  { sku: "SKU-2", qty: 1, price: 101.0 }
]);

Read session state

JavaScript

axo.getSessionId();   // "sess_…" — current session UUID
axo.getVisitorId();   // "vis_…"  — persistent, first-party cookie
axo.getSegment();     // "deliberator" — current primary segment
axo.lastRender();     // RenderSnapshot — per-zone outcome, for QA

Method reference

Method	Type	Description
axo.identify(traits) required	traits: object	Attach a known identity (email, external_id, arbitrary traits) to the current anonymous session. Merges cross-device sessions.
axo.convert(value?) optional	value?: number	Fire a conversion for the primary goal. The escape hatch for SPAs where no goal URL is navigated to. No-op without consent or in preview.
axo.setCart(items) optional	items: LineItem[]	Persist cart state so the next convert attaches line_items (powers CAPI content_ids + the co-purchase recommender).
axo.getSessionId() optional	→ string	The active session ID (UUID).
axo.getVisitorId() optional	→ string	The persistent visitor ID (survives sessions, first-party cookie).
axo.getSegment() optional	→ string	The current visitor's primary segment ID.
axo.getResumedContext() optional	→ object \| null	Context from a triggered-email token redemption (fire_id, cart resume URL, …) when the visitor lands via a ?vt_token= link.
axo.lastRender() optional	→ RenderSnapshot	The last personalize pass, per zone (applied / holdout / no_variant / not_found / render_error) — for QA and DevTools.

Authoring attributes

These data-vt-* attributes are part of the public authoring surface — add them to your markup so the tag can find zones and read commerce context without JS.

Attribute	Type	Description
data-vt-zone optional	string	Marks an element as a named personalization zone (the DOM slot AXO can swap or fill).
data-vt-revenue optional	number	On a goal page, the conversion revenue to record.
data-vt-category optional	string	Tags the current page/product category for behavioral scoring and reco context.
data-vt-line-item optional	container	Marks a cart/line-item element; child data-vt-product-id / -sku / -price supply its fields.
data-vt-breadcrumb optional	string	Supplies breadcrumb context for taxonomy and page-type detection.

AXO honors consent before any PII path runs. Set window.vt_consent (or the vt_consent cookie) from your CMP, or use AXO's built-in banner — see Privacy, Consent & Compliance. Without consent, identify and convert no-op.