React SDK

Usa @convertmax/react cuando quieras bindings específicos de React sobre el SDK base de JavaScript. ConvertmaxProvider es el export de provider canónico, y createConvertmax de @convertmax/js es la fábrica de cliente canónica.

Instala los paquetes

Instala el paquete de React junto con el SDK base:

npm install @convertmax/react @convertmax/js

ConvertmaxProvider inicializa el cliente de navegador al montarse, por lo que los comportamientos automáticos del navegador empiezan sin esperar la primera llamada manual a track().

Envuelve tu app

Configura el provider con el endpoint de eventos de Convertmax:

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: "YOUR_API_KEY",
        autoPage: true
      }}
    >
      <SignupButton />
    </ConvertmaxProvider>
  );
}

autoPage

Cuando autoPage: true está habilitado, el cliente de navegador emite automáticamente page_view:

• en la carga inicial de la página después de la inicialización
• después de history.pushState y history.replaceState
• en navegación hacia atrás y adelante mediante popstate
• cuando solo cambia la query string

Los cambios que solo afectan al hash se ignoran por defecto.

Usa autoPage para el seguimiento de rutas en el navegador. Usa usePageTracking() cuando quieras un evento manual de estilo vista de página desde un componente específico.

Comportamientos automáticos del navegador

El cliente JS publicado subyacente también puede automáticamente:

• detectar IDs de clic de anuncios como gclid, msclkid, ttclid, fbclid, e identificadores de campaña relacionados, y luego emitir un evento cpc
• clasificar referrers orgánicos y emitir organic
• clasificar referrers sociales y emitir social
• clasificar referrers de motores de búsqueda y emitir search cuando hay un término de búsqueda disponible
• rellenar los inputs de formulario ocultos llamados cm_visitor y cm_session
• opcionalmente capturar el cf_uvid de Clickfunnels desde el almacenamiento del navegador cuando captureCfUvid: true
• detectar navegadores móviles e incluir ese estado en los eventos automáticos del navegador
• respetar el estado local de exclusión (opt-out)

Helpers de React disponibles

El paquete incluye estos exports enfocados en React:

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

Si necesitas construir un cliente fuera de React, usa createConvertmax() de @convertmax/js.

Envía eventos básicos

Después de montar el provider, registra al menos una vista de página y un evento del flujo de conversión:

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

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

  return (
    <button
      onClick={() => void convertmax.track("page_view", {})}
    >
      Track page view
    </button>
  );
}

Verifica la instalación

Después de cargar tu app de React:

1. confirma que el provider se inicializa correctamente
2. confirma que se emite un evento page_view
3. dispara un evento registrado como click, add_cart o convert
4. confirma que las solicitudes se envían a https://event.convertmax.io

Usa la Convertmax Chrome Extension para inspeccionar señales en tiempo de ejecución y las solicitudes capturadas.