@convertmax/react

React bindings for Convertmax analytics.

Browser tracking is asynchronous and background-friendly through the underlying client's fetch(..., { keepalive: true }) transport. sendBeacon support is intentionally disabled until the compatible Convertmax endpoint is deployed. keepalive is best-effort browser behavior, not a configurable timeout or guaranteed delivery mechanism.

autoPage

When autoPage: true is enabled, the browser 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.

Use autoPage for browser route tracking. Use usePageTracking() when you want a manual page-view-style event from a specific component. ConvertmaxProvider initializes the client on mount, so browser auto behaviors start without waiting for the first manual track() call.

Automatic browser behaviors

The underlying JS client can also:

• 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/react @convertmax/js

Usage

import { ConvertmaxProvider, useConvertmax } from "@convertmax/react";

function SignupButton() {
  const convertmax = useConvertmax();

  return (
    <button
      onClick={() =>
        void convertmax.track("click", {
          target: "hero_cta",
          page: "https://example.com/pricing"
        })
      }
    >
      Start free
    </button>
  );
}

export function App() {
  return (
    <ConvertmaxProvider
      options={{
        host: "https://event.convertmax.io",
        apiKey: "public-XXXX",
        autoPage: true
      }}
    >
      <SignupButton />
    </ConvertmaxProvider>
  );
}

Exports

• ConvertmaxProvider
• useConvertmax()
• usePageTracking(name?, properties?)

Supported track() events

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

Supported event examples

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

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

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

void 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
});

void 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"
});

void 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" }

SDK examples:

void 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
});

void 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