NPM Package

Use @convertmax/js when you want to install Convertmax through your application bundle instead of the site script snippet.

Install the package

npm install @convertmax/js

createConvertmax() is the canonical client factory for the published package.

Browser usage

Create a client and point it at the Convertmax event endpoint:

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

const convertmax = createConvertmax({
  host: "https://event.convertmax.io",
  apiKey: "YOUR_API_KEY",
  autoPage: true
});

await convertmax.page("Pricing");

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

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 and 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 published SDK can also automatically:

• detect ad click IDs like gclid, msclkid, ttclid, fbclid, and related campaign identifiers, 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

Node.js usage

Use the same package for backend or server-side tracking with runtime: "node":

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

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

await convertmax.track("convert", {
  event_name: "order_checkout_completed",
  source: "api",
  revenue: 149.99
});

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

Browser lifecycle and opt-out helpers

The published package also includes:

• config(options?) for legacy-style browser lifecycle setup
• optoutTracking()
• optinTracking()
• optoutStatus()
• convertmaxLoaded when the browser client is created
• convertmaxReady after browser auto behaviors have been initialized

Send baseline events

After setup, track at least a page view and one conversion path event:

await convertmax.track("page_view", {});

Verify the install

After loading your app or sending a server event:

1. confirm the SDK initializes successfully
2. confirm a page_view event is emitted
3. trigger one tracked event such as click, add_cart, or convert
4. confirm requests are sent to https://event.convertmax.io

Use the Convertmax Chrome Extension to inspect runtime signals and captured requests in browser environments.