@convertmax/js

Isomorphic Convertmax analytics client for browser and Node.js applications.

Browser delivery is asynchronous and background-friendly via fetch(..., { keepalive: true }). sendBeacon support is intentionally disabled until the Convertmax browser endpoint is deployed for it. keepalive is best-effort browser behavior, not a configurable timeout or guaranteed delivery mechanism.

autoPage

When autoPage: true is enabled in the browser, the client automatically emits page_view:

• on the initial page load after initialization
• after history.pushState and history.replaceState
• on back/forward navigation via popstate
• when only the query string changes

Hash-only changes are ignored by default.

Automatic browser behaviors

When initialized in the browser, the SDK can automatically:

• emit page_view events when autoPage: true
• detect ad click IDs like gclid, msclkid, ttclid, fbclid, scclid, epik, twclid, li_fat_id, tag, yclid, rdt_cid, and qaid, then emit a cpc event
• classify organic referrers and emit organic
• classify social referrers and emit social
• classify search-engine referrers and emit search when a search term is available
• populate hidden form inputs named cm_visitor and cm_session
• optionally capture Clickfunnels cf_uvid from browser storage when captureCfUvid: true
• detect mobile browsers and include that state in automatic browser events
• respect local opt-out state

Install

npm install @convertmax/js

Usage

import { createConvertmax } from "@convertmax/js";

const convertmax = createConvertmax({
  host: "https://event.convertmax.io",
  apiKey: "public-XXXX"
});

await convertmax.identify("user_123", {
  email: "[email protected]"
});

await convertmax.page("Pricing");
await convertmax.track("click", {
  target: "hero_cta",
  page: "https://example.com/pricing"
});

Node.js

import { createConvertmax } from "@convertmax/js";

const convertmax = createConvertmax({
  host: "https://event.convertmax.io",
  apiKey: process.env.CONVERTMAX_API_KEY,
  runtime: "node"
});

await convertmax.track("page_view", {
  product: "shop",
  event_type: "checkout"
});

await convertmax.track("convert", {
  event_name: "order_checkout_completed",
  source: "api",
  page: "https://shop.example.com/checkout/success",
  order_id: "ord_12345",
  checkout_id: "chk_456",
  currency: "USD",
  value: 149.99,
  revenue: 149.99,
  items: [
    {
      product_id: "sku_1",
      name: "Widget Pro",
      quantity: 1,
      price: 99.99
    }
  ]
});

If your Node.js runtime does not expose fetch, pass one with the fetch option.

writeKey is also supported as a legacy alias, but apiKey is the preferred option name. In browsers, tracking currently uses fetch with keepalive for background-friendly delivery. sendBeacon will be enabled in a future release once the compatible endpoint is deployed.

Opt-out helpers:

• optoutTracking()
• optinTracking()
• optoutStatus()

Legacy-style browser lifecycle helper:

• config(options?)

Browser lifecycle events:

• convertmaxLoaded when the browser client is created
• convertmaxReady after browser auto behaviors have been initialized

API

• createConvertmax(options)
• track(event, properties?)
• identify(userId?, traits?)
• page(name?, properties?)
• group(groupId, traits?)
• alias(userId)
• config(options?)
• reset()

Supported track() events

• page_view
• click
• add_cart
• convert
• custom
• search

Supported event examples

await convertmax.track("page_view", {
  product: "shop",
  event_type: "category"
});

await convertmax.track("click", {
  target: "hero_cta",
  page: "https://example.com/pricing"
});

await convertmax.track("add_cart", {
  id: "PRODUCT_ID",
  quantity: 1,
  recommendation: true
});

await convertmax.track("convert", {
  event_name: "order_checkout_completed",
  source: "api",
  page: "https://shop.example.com/checkout/success",
  order_id: "ord_12345",
  checkout_id: "chk_456",
  currency: "USD",
  value: 149.99,
  revenue: 149.99
});

await convertmax.track("custom", {
  event_name: "newsletter_signup",
  source: "api",
  page: "https://shop.example.com/blog/spring-launch",
  email: "[email protected]",
  signup_location: "footer_form",
  list_id: "weekly_updates"
});

await convertmax.track("search", {
  query: "running shoes",
  hits: 42
});

Event schemas

Use convert for measurable conversions such as completed checkouts or qualified leads. Use custom for arbitrary business events such as newsletter signups.

Default source for native JSON API events:

{ "source": "api" }

Canonical convert payload for an order conversion:

{
  "event_type": "convert",
  "visitor": "user_123",
  "session_id": "sess_checkout_789",
  "data": {
    "event_name": "order_checkout_completed",
    "source": "api",
    "page": "https://shop.example.com/checkout/success",
    "order_id": "ord_12345",
    "checkout_id": "chk_456",
    "currency": "USD",
    "value": 149.99,
    "revenue": 149.99,
    "items": [
      {
        "product_id": "sku_1",
        "name": "Widget Pro",
        "quantity": 1,
        "price": 99.99
      },
      {
        "product_id": "sku_2",
        "name": "Widget Case",
        "quantity": 1,
        "price": 50
      }
    ]
  }
}

Canonical custom payload for a newsletter signup:

{
  "event_type": "custom",
  "visitor": "user_123",
  "session_id": "sess_abc123",
  "data": {
    "event_name": "newsletter_signup",
    "source": "api",
    "page": "https://shop.example.com/blog/spring-launch",
    "email": "[email protected]",
    "signup_location": "footer_form",
    "list_id": "weekly_updates"
  }
}

When using the SDK, pass the contents of data to track():

await convertmax.track("convert", {
  event_name: "order_checkout_completed",
  source: "api",
  page: "https://shop.example.com/checkout/success",
  order_id: "ord_12345",
  checkout_id: "chk_456",
  currency: "USD",
  value: 149.99,
  revenue: 149.99
});

await convertmax.track("custom", {
  event_name: "newsletter_signup",
  source: "api",
  page: "https://shop.example.com/blog/spring-launch",
  email: "[email protected]",
  signup_location: "footer_form",
  list_id: "weekly_updates"
});

Links

• Website: www.convertmax.io
• Docs: docs.convertmax.io
• React guide: www.convertmax.io
• API docs: docs.convertmax.io