Instala el SDK del navegador

Instala el SDK una vez mediante el mecanismo global de scripts de tu framework. La etiqueta siguiente es para HTML plano.

Los frameworks gestionan el head del documento. En Next.js App Router, usa next/script en el layout raíz. No renderices un head personalizado ni inyectes esta etiqueta con dangerouslySetInnerHTML.

Llama a los dos métodos principales

Usa JavaScript para comportamientos relevantes sin una activación equivalente en el DOM. Para enlaces, botones, controles y formularios, añade atributos HTML en su lugar.

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>

Reglas para las acciones

• Usa una clave de propósito en minúsculas que empiece por una letra, contenga letras, números y guiones bajos simples, y no supere los 64 caracteres.
• Reutiliza la misma clave en distintas ubicaciones. Anota un formulario una sola vez, en el propio formulario, y nunca añadas una llamada programática para el mismo gesto.
• Nunca generes claves ni ubicaciones a partir del texto visible, el idioma, datos del visitante, IDs de cuenta, marcas de tiempo o variantes de experimento.

Llama a conversion solo después de que el flujo existente de la aplicación demuestre que se ha completado correctamente; por ejemplo, tras una respuesta satisfactoria de la API o al llegar a un estado que confirme el resultado.

Autoridad

Declarada por el cliente. Una ubicación correcta da significado al evento, pero el código del navegador no puede aportar la autoridad de un servidor autenticado.

Cuándo usarlo

Un registro, trial, alta en una lista de espera o solicitud de demo se ha completado realmente y el navegador es el único punto disponible que confirma el éxito. Nunca la llames en el clic o envío que inicia el proceso.

const result = await startTrial();

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

Cuando tu backend controla la transacción que confirma el éxito, envía la conversión mediante POST a /v1/conversion con la clave privada del sitio. Las solicitudes aceptadas devuelven 202. url es obligatorio y debe pertenecer a un dominio permitido del proyecto; name, occurredAt, referrer y los IDs de visitante, sesión y vista de página son opcionales.

Autoridad

Procedencia autenticada a nivel de proyecto. Es más sólida que una declaración del navegador, pero no demuestra la identidad de una persona.

Cuándo usarlo

Tu backend ha confirmado un resultado no relacionado con un pago. Mantén la clave privada en el servidor y elige esta vía en lugar de emitir la misma conversión desde el navegador.

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

Conecta Stripe, obtén stripeMetadata() después de que cargue el SDK del navegador y valida en tu backend las claves de atribución admitidas. Para Checkout en modo suscripción, adjúntalas tanto a los metadatos de Checkout Session como a los de la suscripción. Los eventos firmados invoice.payment_succeeded aportan el importe bruto, la moneda y el momento del pago; los webhooks de reembolso y disputa ajustan el valor neto, mientras que los webhooks de suscripción añaden señales de cancelación y churn. No se importan facturas históricas.

Autoridad

Respaldada por el proveedor para el estado de la factura pagada, el importe bruto, la moneda y el momento del pago. Los metadatos de Splendorize conectan el recorrido del visitante; no demuestran el pago.

Cuándo usarlo

Necesitas medir compras respaldadas por facturas de Stripe cobradas correctamente o ingresos recurrentes por suscripción. No informes de importes proporcionados por el navegador ni emitas una segunda conversión desde el navegador solo para atribuirte el mismo pago.

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

Llama a estos métodos en window.splendorize. Con el loader personalizado, todos excepto stripeMetadata() pueden ponerse en cola antes de que cargue el SDK.

action(actionKey, { placement? })

Registra una acción estable basada en el propósito, con una ubicación opcional. No declara que un resultado se haya completado.

conversion(name?, properties?)

Registra una conversión declarada por el cliente. Llámala solo después de que la aplicación haya confirmado el éxito.

payment({ email })

Genera un hash del email de checkout para enlazar el recorrido actual del visitante. Nunca demuestra el pago, el importe ni los ingresos.

stripeMetadata()Después de cargar el SDK

Devuelve los IDs de atribución de Splendorize para añadirlos a los metadatos de Stripe. No demuestra el pago.

setConsent(allowed)

Permite o retira el seguimiento persistente cuando tu sitio requiere consentimiento previo. Pasar false elimina la atribución persistente.

El loader generado también admite comandos invocables como window.splendorize("action", "start_trial"). En el código de la aplicación, prioriza los métodos con nombre anteriores porque son más fáciles de leer.

Mantén la implementación acotada y haz que cada señal signifique exactamente una cosa.

• Instala un único loader global y conserva el comportamiento de consentimiento y CSP del sitio.
• Mantén la clave privada del sitio en el servidor; la clave pública del sitio puede aparecer en el código del navegador.
• Nunca envíes valores de formularios, emails, nombres, teléfonos, IDs de clientes ni secretos en los metadatos de acciones o conversiones.
• Emite una única acción semántica por gesto y elige una sola fuente de referencia para cada resultado.
• Trata la atribución del pago como un enlace de identidad, nunca como autorización ni como prueba del pago.