@clickmax/browser-sdk

SDK de navegador da Clickmax para captura pública de leads.

Ele foi feito para dois cenários:

• você quer colar um script no site e deixar a Clickmax cuidar do formulário
• você já tem seu próprio formulário e quer usar apenas uma função JS para enviar o lead

Como escolher

Quero a forma mais simples

Use o bundle via script tag.

Bom para:

• landing pages
• Webflow
• WordPress
• sites estáticos
• integrações rápidas

Já tenho meu frontend

Use submitLead() via @clickmax/browser-sdk/forms.

Bom para:

• apps próprios
• formulários customizados
• fluxos em que sua UI já existe

Modo 1: Script Tag

O bundle global inclui:

• widget renderizado
• bind de formulários existentes
• modal
• auto-init
• estilos padrão

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js"
  defer
></script>

<script>
  async function sendLead() {
    await window.Clickmax.submitLead({
      slug: "abc123",
      data: {
        email: "[email protected]",
        name: "Maria",
      },
    });
  }
</script>

Widget inline

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js"
  defer
></script>

<div
  data-cx-form-widget
  data-cx-slug="abc123"
  data-cx-mode="inline"
  data-cx-theme="light"
  data-cx-accent="#111827"
  data-cx-title="Fale com nosso time"
  data-cx-description="Deixe seus dados e entraremos em contato."
></div>

Widget em modal

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js"
  defer
></script>

<button data-cx-open="form-contato">Abrir formulário</button>

<div
  data-cx-form-widget
  data-cx-widget-id="form-contato"
  data-cx-slug="abc123"
  data-cx-mode="modal"
  data-cx-title="Solicite contato"
></div>

Usando seu próprio HTML

Se você quer manter seu markup, o script também consegue conectar formulários existentes:

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js"
  defer
></script>

<form
  data-cx-ingest-form
  data-cx-slug="abc123"
  data-cx-success-message="Enviado com sucesso!"
>
  <input data-cx-field="name" placeholder="Seu nome" />
  <input data-cx-field="email" placeholder="Seu e-mail" />
  <input data-cx-field="telephone" placeholder="Seu telefone" />
  <input type="checkbox" data-cx-field="lgpdApproved" />
  <input type="text" data-cx-field="website" hidden />
  <button type="submit">Enviar</button>
</form>

O data-cx-field pode ficar no próprio <input> ou em um elemento pai/wrapper próximo. Isso ajuda em builders como Framer, onde o atributo customizado costuma ser aplicado no contêiner do campo em vez do controle nativo.

Se o seu builder também registra listeners próprios de submit e você quer que a SDK assuma o envio sozinha, adicione data-cx-hijack-form no <form>. Nesse modo, a SDK registra o listener em capture phase e interrompe outros listeners de submit do mesmo fluxo.

Se você quiser levar os dados já preenchidos para a próxima página no redirect, adicione data-cx-redirect-with-query. Nesse modo, a SDK acrescenta name, email, phone, utm_source, utm_medium, utm_campaign, utm_content e utm_term na query string final.

Meio-termo: comportamento da SDK com sua própria estilização

Se você quer manter o comportamento em JavaScript da SDK, mas prefere não usar os estilos dela, adicione data-cx-nostyles.

Esse modo mantém:

• submit
• validação
• redirect
• success/error
• comportamento de modal

Mas deixa de aplicar as classes visuais da SDK.

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js"
  defer
></script>

<form
  data-cx-ingest-form
  data-cx-slug="abc123"
  data-cx-nostyles
  data-cx-success-message="Enviado com sucesso!"
>
  <input data-cx-field="name" placeholder="Seu nome" />
  <input data-cx-field="email" placeholder="Seu e-mail" />
  <input data-cx-field="telephone" placeholder="Seu telefone" />
  <button type="submit">Enviar</button>
</form>

Modo 2: API JavaScript

Use esse modo quando a sua interface já existe e você quer controlar tudo por conta própria.

import { submitLead } from "@clickmax/browser-sdk/forms";

await submitLead({
  slug: "abc123",
  data: {
    email: "[email protected]",
    name: "Lead Example",
    telephone: "5511999999999",
  },
});

Exemplo com tratamento de erro

import { submitLead } from "@clickmax/browser-sdk/forms";

try {
  await submitLead({
    slug: "abc123",
    data: {
      email: "[email protected]",
      name: "Maria",
    },
  });

  console.log("Lead enviado com sucesso");
} catch (error) {
  console.error("Não foi possível enviar o lead", error);
}

Atributos suportados

| Atributo | Onde usar | Descrição | | ----------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- | | data-cx-slug | Formulários existentes, widget renderizado | Slug público do ingest link. | | data-cx-api-url | Formulários existentes, widget renderizado | Override opcional da base da API. | | data-cx-nostyles | Formulários existentes, widget renderizado | Mantém o comportamento JS sem aplicar classes visuais da SDK. | | data-cx-hijack-form | Formulários existentes | Faz a SDK assumir exclusivamente o submit do form. | | data-cx-redirect-url | Formulários existentes, widget renderizado | Redirect local configurado no HTML. Tem prioridade sobre o redirect do CRM. | | data-cx-redirect-with-query | Formulários existentes, widget renderizado | Acrescenta name, email, phone e as UTM da página na query string do redirect final. | | data-cx-success-message | Formulários existentes, widget renderizado | Mensagem exibida após envio com sucesso. | | data-cx-reset-on-success | Formulários existentes, widget renderizado | Reseta o form após sucesso quando ativo. | | data-cx-locale | Formulários existentes, widget renderizado | Localização usada pela SDK (pt-BR ou en). | | data-cx-mode="inline\|modal" | Widget renderizado | Define se o widget abre inline ou em modal. | | data-cx-widget-id | Widget renderizado | Identificador usado pelos gatilhos data-cx-open. | | data-cx-theme="light\|dark\|auto" | Widget renderizado | Tema visual do widget. | | data-cx-accent | Widget renderizado | Cor principal do widget. | | data-cx-title | Widget renderizado | Título do widget. | | data-cx-description | Widget renderizado | Descrição do widget. | | data-cx-submit-label | Widget renderizado | Texto do botão de submit. | | data-cx-fields | Widget renderizado | Lista CSV dos campos renderizados. | | data-cx-required-fields | Widget renderizado | Lista CSV dos campos obrigatórios. | | data-cx-show-lgpd | Widget renderizado | Exibe o checkbox LGPD. | | data-cx-lgpd-required | Widget renderizado | Torna o checkbox LGPD obrigatório. |

Campos suportados no form

| Atributo | Onde usar | Descrição | | ------------------------------ | -------------------------------------- | -------------------------- | | data-cx-field="name" | Input, select, textarea ou wrapper pai | Mapeia o nome do lead. | | data-cx-field="email" | Input, select, textarea ou wrapper pai | Mapeia o e-mail do lead. | | data-cx-field="telephone" | Input, select, textarea ou wrapper pai | Mapeia o telefone do lead. | | data-cx-field="lgpdApproved" | Input checkbox ou wrapper pai | Mapeia a aprovação LGPD. | | data-cx-field="website" | Input hidden ou wrapper pai | Honeypot anti-spam. |

O atributo pode estar no campo nativo ou em um wrapper pai, desde que esse wrapper envolva o input/select/textarea correspondente.

O que o script faz automaticamente

Quando você usa o bundle global, ele inicializa apenas estes seletores:

• [data-cx-form-widget]
• form[data-cx-ingest-form]

Em páginas CSR, como Framer, ele também observa o DOM e inicializa esses mesmos seletores quando eles aparecerem depois do carregamento inicial.

Ou seja: nada de comportamento implícito fora do que estiver marcado explicitamente.

Comportamentos importantes

UTM

• os parâmetros UTM da página são enviados junto com o lead quando presentes

Anti-spam

• o campo website funciona como honeypot
• se ele vier preenchido, o envio é ignorado

Redirect

• você pode configurar redirect via data-cx-redirect-url
• se esse atributo não existir, a SDK usa o redirectUrl configurado no ingest link do CRM
• quando os dois existirem, data-cx-redirect-url tem prioridade
• por padrão não adicionamos parâmetros sensíveis na URL

Quando usar cada abordagem

Use script tag quando:

• quer colocar para rodar rápido
• quer usar o widget pronto
• quer reaproveitar HTML simples sem escrever JS

Use submitLead() quando:

• seu app já controla validação, loading e erros
• você quer integrar com sua própria UI
• você não quer nenhum comportamento automático de DOM

Tracking

Além dos formulários, a SDK publica um bundle independente de tracking que dispara eventos anônimos (clicks em botões, submits, scroll, visibilidade, page view) para o pages-server da Clickmax. Funciona em páginas externas (Webflow, WP, sites estáticos) e não depende do bundle de forms.

<script
  src="https://cdn.jsdelivr.net/npm/@clickmax/browser-sdk@latest/dist/tracking/clickmax-tracking.js"
  data-cx-api-url="https://api.clickmax.io/tracking"
  data-cx-track-clicks
  data-cx-track-scroll="25,50,75,90"
  data-cx-track-visibility
  data-cx-pixel-fb
  defer
></script>

Atributos do script

| Atributo | Default | Descrição | | -------------------------- | ----------- | ----------------------------------------------------------------------- | | data-cx-api-url | same-origin | Base URL do pages-server. Obrigatório para páginas externas. | | data-cx-track-clicks | ligado | Captura clicks em .cm-checkout-button, [data-cx-track="click"]. | | data-cx-track-scroll | desligado | Thresholds de scroll em %, separados por vírgula (ex.: 25,50,75,90). | | data-cx-track-visibility | desligado | Dispara eventos ao entrar na viewport ([data-cx-track="visibility"]). | | data-cx-pixel-fb | desligado | Ecoa eventos para o Facebook Pixel se fbq estiver presente. |

O que é enviado

Cada evento vira um POST (via navigator.sendBeacon com fallback para fetch keepalive) com Content-Type: application/vnd.clickmax.tracking+json. Bots são descartados no servidor.

Forms + Tracking em um único script

Se você quer forms e tracking na mesma página, dá para carregar os dois bundles em uma única requisição usando o endpoint combine do jsDelivr:

<script
  src="https://cdn.jsdelivr.net/combine/npm/@clickmax/browser-sdk@latest/dist/forms/clickmax-forms.js,npm/@clickmax/browser-sdk@latest/dist/tracking/clickmax-tracking.js"
  data-cx-api-url="https://api.clickmax.io/tracking"
  data-cx-track-clicks
  defer
></script>

Os atributos data-cx-* do tracking continuam funcionando normalmente na própria tag combinada. Os bundles são independentes (window.Clickmax para forms, window.ClickmaxTracking para tracking) e não colidem.

Use bundles separados quando a página precisa apenas de tracking — o bundle de forms traz CSS e ~13 KB extras que não serão usados.

Seletores reconhecidos

| Seletor | Evento | | ------------------------------ | ----------------- | | .cm-checkout-button | button_click | | [data-cx-track="click"] | button_click | | .cm-next-funnel-node | link_click | | [data-cx-track="link"] | link_click | | form.cm-form (submit) | form_submit | | [data-cx-track="visibility"] | element_visible |