Docs

SDK de JavaScript

Instalación, cliente, métodos, control de etiquetas, doble opt-in y verificación de justificantes.

El SDK envuelve la API sin procesar con lo que tendrías que construir tú mismo: caché de respuestas, revalidación por ETag, verificación de justificantes sin conexión y un control de etiquetas que bloquea los rastreadores hasta que el consentimiento realmente lo permite.

npm i @croombit/sdk

Cliente

import { CroombitClient } from '@croombit/sdk';

const tc = new CroombitClient({
  baseUrl: 'https://api.croombit.com',
  apiKey: 'pk_live_…',      // sk_live_… en servidor
  cacheTtlMs: 60_000,       // opcional
});

Métodos

  • recordConsent(params, { idempotencyKey }) · recordConsentBatch(records) · recordPreferences(params)
  • getConsentState(subject, { purpose?, fresh? }) · getPreferences(subject): cacheados con ETag
  • getPurposes({ locale? }) · getPurpose(key, { locale? }) · getPreferenceTemplate() · getPolicy({ country? })
  • getTcString(subject) · getConsentMode(subject) · applyConsentMode(subject, gtag) · getGppString(subject)
  • getReceipt(id) · verifyReceipt(receipt): Ed25519 sin conexión mediante Web Crypto
  • createPortalToken(subject) · createSubject · addIdentifier · mergeSubjects · createDataRequest: requieren sk_
  • getConsentHistory(subject, { purpose? }) · getPreferenceHistory(subject, { field? }): el historial de solo anexión, de más reciente a más antiguo; requieren sk_ (consulta Guía: mostrar a un usuario su propio historial)
  • getWebhookEvents(): el catálogo de eventos de webhook y el contrato de entrega (GET /v1/webhook-events)

recordConsent y recordConsentBatch aceptan source: 'API' | 'IMPORT' | 'MIGRATION' (por defecto API). IMPORT y MIGRATION significan que el registro lo afirmas tú, no el sujeto, y requieren una clave sk_; consulta Quién actuó: source.

Utilidades de servidor

La entrada @croombit/sdk/server es solo para tu backend (Web Crypto, sin dependencias; Node 18+, Deno, Bun y entornos edge):

  • signIdentityToken(…): avala a un usuario con sesión iniciada para que una clave pk_ pueda llegar a él (guía)
  • constructWebhookEvent({ header, rawBody, secret }): verifica la firma de un webhook y devuelve el evento tipado; lanza WebhookSignatureError
  • verifyWebhookSignature({ header, rawBody, secret, toleranceSeconds? }): la misma comprobación, como booleano
  • WEBHOOK_EVENTS · WebhookEventType · WebhookEvent: los nombres y tipos de los eventos

Tienes un receptor completo en Webhooks: cuerpos y firma.

Control de etiquetas

// carga tus scripts solo cuando el sujeto ha concedido alguno de estos propósitos
await tc.gate('email:user@example.com', ['analytics'], () => loadAnalytics());

// después de que tu banner escriba consentimiento nuevo:
tc.notifyConsentChanged();

Leer preferencias

getPreferences devuelve el estado actual del centro de preferencias para un sujeto — canales, temas y campos tipados — derivado de las escrituras POST /v1/preferences.

const prefs = await tc.getPreferences('email:user@example.com');
// prefs.channels['marketing'].topics['newsletter'].state === 'GRANTED'

Doble opt-in (preferencias de correo)

Para el correo de marketing, muchas normativas exigen opt-in confirmado. Usa createPreferenceConfirmationToken desde tu servidor (requiere una clave sk_ — el token es toda la capacidad, así que nunca debe llegar a un navegador) para solicitar el envío del email de confirmación; la persona hace clic en un enlace que llama a POST /v1/preferences/confirm.

// 1. Escribe una preferencia pendiente y solicita el email de confirmación (servidor, sk_)
const { token, confirmUrl } = await tc.createPreferenceConfirmationToken({
  subject: 'email:usuario@ejemplo.com',
  values: [{ field: 'newsletter', value: true }],
  channel: 'email',
  redirectUrl: 'https://acme.com/suscripcion/confirmada', // debe estar en uno de los dominios del sitio
});
// Tu servicio de correo envía confirmUrl — o pasa `to: 'usuario@ejemplo.com'` (el correo del propio
// sujeto) y Croombit lo envía por ti.

// 2. No hay nada más que hacer — el endpoint de confirmación escribe GRANTED
//    y se dispara el webhook preference.confirmed.
La preferencia pendiente NO cuenta como consentimiento hasta que se confirme. getPreferences devuelve PENDING hasta que se hace clic en el enlace.
AnteriorErrores