Instala o SDK do browser

Instala o SDK uma única vez através do mecanismo global de scripts do teu framework. A tag abaixo destina-se a HTML simples.

Os frameworks gerem o head do documento. No Next.js App Router, usa next/script no layout raiz. Não renderizes um head personalizado nem injetes esta tag com dangerouslySetInnerHTML.

Chama os dois métodos principais

Usa JavaScript para comportamentos relevantes sem uma ativação DOM correspondente. Para links, botões, controlos e formulários, adiciona atributos HTML em vez disso.

window.splendorize.action(
  "change_billing_period",
  { placement: "pricing" },
);

<a
  href="/signup"
  data-splendorize-action="start_trial"
  data-splendorize-action-placement="hero"
>
  Start trial
</a>

<form data-splendorize-action="request_demo">
  <!-- Existing fields and submit button -->
</form>

Regras para as ações

• Usa uma chave de propósito em minúsculas que comece por uma letra, contenha letras, números e underscores simples, e não ultrapasse 64 caracteres.
• Reutiliza a mesma chave em vários posicionamentos. Anota um formulário uma única vez no próprio formulário e nunca adiciones uma chamada programática para o mesmo gesto.
• Nunca cries chaves ou posicionamentos a partir do texto visível, do idioma, de dados do visitante, de IDs de conta, de timestamps ou de variantes de experiências.

Chama conversion apenas depois de o fluxo existente da aplicação comprovar o sucesso, por exemplo, após uma resposta bem-sucedida da API ou ao chegar a um estado que confirme o resultado.

Autoridade

Declarada no lado do cliente. Um posicionamento correto dá significado ao evento, mas o código do browser não pode fornecer a autoridade de um servidor autenticado.

Quando usar

Um registo, trial, entrada numa lista de espera ou pedido de demo foi realmente concluído e o browser é o único ponto disponível que confirma o sucesso. Nunca a chames no clique ou envio que inicia o processo.

const result = await startTrial();

if (result.trialStarted === true) {
  window.splendorize.conversion("trial_started");
}

Quando o teu backend controla a transação que confirma o sucesso, envia a conversão por POST para /v1/conversion com a chave privada do site. Os pedidos aceites devolvem 202. url é obrigatório e deve pertencer a um domínio permitido do projeto; name, occurredAt, referrer e os IDs de visitante, sessão e visualização de página são opcionais.

Autoridade

Proveniência autenticada ao nível do projeto. É mais forte do que uma declaração do browser, mas não comprova a identidade de uma pessoa.

Quando usar

O teu backend confirmou um resultado não relacionado com um pagamento. Mantém a chave privada no servidor e escolhe esta via em vez de emitir a mesma conversão no browser.

const response = await fetch("https://cdn.splendorize.com/v1/conversion", {
  method: "POST",
  headers: {
    authorization: "Bearer " + process.env.SPLENDORIZE_PRIVATE_SITE_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "trial_started",
    url: "https://example.com/welcome",
    occurredAt: new Date().toISOString(),
  }),
});

if (response.status !== 202) {
  throw new Error("Splendorize rejected the conversion");
}

Liga a Stripe, recolhe stripeMetadata() depois de o SDK do browser carregar e valida no teu backend as chaves de atribuição suportadas. Para Checkout em modo de subscrição, anexa-as aos metadados da Checkout Session e da subscrição. Os eventos assinados invoice.payment_succeeded fornecem o montante bruto, a moeda e o momento do pagamento; os webhooks de reembolso e disputa ajustam o valor líquido, enquanto os webhooks de subscrição acrescentam sinais de cancelamento e churn. As faturas históricas não são importadas.

Autoridade

Comprovada pelo fornecedor para o estado da fatura paga, montante bruto, moeda e momento do pagamento. Os metadados da Splendorize ligam o percurso do visitante; não comprovam o pagamento.

Quando usar

Precisas de medir compras associadas a faturas da Stripe pagas com sucesso ou receita recorrente de subscrições. Não comuniques montantes fornecidos pelo browser nem emitas uma segunda conversão no browser apenas para reivindicar o mesmo pagamento.

const attribution = window.splendorize.stripeMetadata();

await fetch("/api/checkout", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ attribution }),
});

const attribution = Object.fromEntries(
  [
    "splendorize_site_id",
    "splendorize_visitor_id",
    "splendorize_session_id",
    "splendorize_page_view_id",
  ].flatMap((key) => {
    const value = requestBody.attribution?.[key];
    return typeof value === "string" && value.length <= 120
      ? [[key, value]]
      : [];
  }),
);

await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items,
  success_url,
  cancel_url,
  metadata: attribution,
  subscription_data: { metadata: attribution },
});

Chama estes métodos em window.splendorize. Com o loader personalizado, todos exceto stripeMetadata() podem ser colocados em fila antes de o SDK carregar.

action(actionKey, { placement? })

Regista uma ação estável baseada no propósito, com um posicionamento opcional. Não declara que um resultado foi concluído.

conversion(name?, properties?)

Regista uma conversão declarada no lado do cliente. Chama-a apenas depois de a aplicação confirmar o sucesso.

payment({ email })

Cria um hash do email de checkout para ligar o percurso atual do visitante. Nunca comprova o pagamento, o montante ou a receita.

stripeMetadata()Depois de o SDK carregar

Devolve os IDs de atribuição da Splendorize para anexar aos metadados da Stripe. Não comprova o pagamento.

setConsent(allowed)

Permite ou retira o tracking persistente quando o teu site exige consentimento prévio. Passar false elimina a atribuição persistente.

O loader gerado também suporta comandos invocáveis como window.splendorize("action", "start_trial"). No código da aplicação, dá preferência aos métodos com nome acima, porque são mais fáceis de ler.

Mantém a implementação restrita e faz com que cada sinal signifique exatamente uma coisa.

• Instala um único loader global e mantém o comportamento de consentimento e CSP do site.
• Mantém a chave privada do site no servidor; a chave pública do site pode aparecer no código do browser.
• Nunca envies valores de formulários, emails, nomes, números de telefone, IDs de clientes ou segredos nos metadados de ações ou conversões.
• Emite uma única ação semântica por gesto e escolhe uma só fonte de referência para cada resultado.
• Trata a atribuição de pagamentos como uma ligação de identidade, nunca como autorização ou prova de pagamento.