Paquete NPM | Convertmax Docs

Usa @convertmax/js cuando quieras instalar Convertmax mediante el bundle de tu aplicación en lugar del snippet de script del sitio.

Instala el paquete

npm install @convertmax/js

createConvertmax() es la fábrica de cliente canónica del paquete publicado.

Uso en el navegador

Crea un cliente y apúntalo al endpoint de eventos de Convertmax:

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`

Cuando autoPage: true está habilitado en el navegador, el cliente 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.

Comportamientos automáticos del navegador

Cuando se inicializa en el navegador, el SDK publicado 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)

Uso en Node.js

Usa el mismo paquete para tracking en backend o del lado del servidor con 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
});

Si tu runtime de Node.js no expone fetch, pásalo con la opción fetch.

Ciclo de vida en el navegador y helpers de opt-out

El paquete publicado también incluye:

config(options?) para configuración de ciclo de vida en el navegador al estilo heredado
optoutTracking()
optinTracking()
optoutStatus()
convertmaxLoaded cuando se crea el cliente de navegador
convertmaxReady después de que se inicializan los comportamientos automáticos del navegador

Envía eventos básicos

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

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

Verifica la instalación

Después de cargar tu app o enviar un evento desde el servidor:

confirma que el SDK se inicializa correctamente
confirma que se emite un evento page_view
dispara un evento registrado como click, add_cart o convert
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 en entornos de navegador.