@pdpsuite/consent-sdk

SDK oficial de PDP Suite para integrar banners y centros de preferencias de consentimiento desde un runtime externo.

Este paquete esta pensado para un modelo donde:

• el sitio cliente integra un SDK publico
• PDP Suite renderiza la UI real dentro de un iframe
• la decision se registra en el runtime de PDP Suite
• el frontend cliente consume un estado autoritativo y reutilizable

Instalacion

npm install @pdpsuite/consent-sdk

Integracion recomendada

La idea ahora es que el cliente integrador haga lo minimo posible:

1. instala @pdpsuite/consent-sdk
2. define sus llaves publicas y runtimeOrigin
3. llama bootstrapConsent()
4. usa el SDK sobre todo para consultar permisos

Opcion A: bootstrap explicito

import {bootstrapConsent} from '@pdpsuite/consent-sdk';

const consent = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_CONSENT_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  apiKeys: {
    cookies: import.meta.env.PUBLIC_PDP_COOKIE_KEY,
    legalConsents: import.meta.env.PUBLIC_PDP_LEGAL_CONSENT_KEY,
    privacyPolicies: import.meta.env.PUBLIC_PDP_PRIVACY_POLICY_KEY
  },
  consentScope: 'device',
  locale: 'es-CL',
  userRef: window.__APP_USER_ID__ ?? undefined
});

if (consent.canUseCategory('marketing')) {
  window.loadMarketingScripts?.();
}

Opcion B: configuracion desde meta y bootstrap automatico

<meta name="pdp-consent-key" content="%PUBLIC_PDP_CONSENT_KEY%" />
<meta name="pdp-consent-cookie-key" content="%PUBLIC_PDP_COOKIE_KEY%" />
<meta name="pdp-consent-legal-key" content="%PUBLIC_PDP_LEGAL_CONSENT_KEY%" />
<meta name="pdp-consent-policy-key" content="%PUBLIC_PDP_PRIVACY_POLICY_KEY%" />
<meta name="pdp-consent-origin" content="%PUBLIC_PDP_CONSENT_ORIGIN%" />
<meta name="pdp-consent-scope" content="device" />

import {bootstrapConsent} from '@pdpsuite/consent-sdk';

const consent = await bootstrapConsent();

El SDK resuelve la configuracion en este orden:

• opciones entregadas a bootstrapConsent() o createConsentClient()
• window.__PDP_CONSENT__
• etiquetas meta

API avanzada

Si quieres controlar manualmente el flujo, todavia puedes usar createConsentClient().

import {createConsentClient} from '@pdpsuite/consent-sdk';

const consent = createConsentClient({
  tenantPublicKey: 'pk_demo_pdpsuite_billy',
  runtimeOrigin: 'https://consent.pdpsuite.com',
  consentScope: 'device',
  locale: 'es-CL',
  userRef: window.__APP_USER_ID__ ?? undefined
});

Opciones:

• tenantPublicKey: clave publica del tenant entregada por PDP Suite.
• apiKeys.cookies: llave publica especifica para banner, preferencias, cookies y proveedores. Si se omite, usa tenantPublicKey.
• apiKeys.legalConsents: llave publica especifica para consentimientos formales de formularios. Si se omite, usa la llave de cookies.
• apiKeys.privacyPolicies: llave publica especifica para documentos/politicas renderizables. Si se omite, usa la llave de consentimientos legales.
• runtimeOrigin: dominio del runtime que sirve el banner, endpoints y centro de preferencias.
• consentScope: define si el consentimiento vive por dispositivo (device) o por cuenta autenticada (account).
• locale: locale preferido para la sesion. Si se omite, usa es-CL.
• userRef: identificador estable del usuario autenticado. Es opcional.
• storageKey: override del almacenamiento local del consentimiento.

Flujo automatico y flujo manual

Automatico

const consent = await bootstrapConsent();

bootstrapConsent() hace internamente esto:

• resuelve la configuracion
• crea el cliente
• ejecuta init()
• ejecuta shouldAsk()
• muestra el banner si corresponde

Manual

const {config, state} = await consent.init();

if (await consent.shouldAsk()) {
  await consent.showBanner();
}

Metodos disponibles:

• init(): carga configuracion del tenant y trata de rehidratar el consentimiento vigente desde el runtime.
• refresh(): recarga configuracion y vuelve a consultar el consentimiento actual.
• shouldAsk(): retorna true si no hay consentimiento vigente para la identidad actual o si cambio la version de politica.
• showBanner(): abre el banner principal.
• showPreferences(): abre el centro de preferencias.
• getState(): retorna el estado local recordado.
• getConfig(): retorna la configuracion actual del tenant.
• getVisitorId(): retorna el identificador anonimo estable generado para ese navegador y tenant.
• canUseCategory(categoryId): indica si una categoria fue concedida.
• canUseProvider(providerId): indica si un proveedor fue concedido.
• revoke(): limpia el estado local recordado.
• onChange(callback): escucha cambios de consentimiento.
• destroy(): desmonta listeners y overlay del SDK.

Helpers exportados:

• bootstrapConsent(): inicializa el SDK y muestra el banner automaticamente si hace falta.
• resolveConsentOptions(): resuelve la configuracion desde opciones, window.__PDP_CONSENT__ o meta.

Identidad: userRef + visitorId

El SDK soporta dos capas de identidad:

• userRef: identidad del usuario autenticado, si el sitio cliente ya la conoce.
• visitorId: identidad anonima y estable por tenant, generada por el SDK y persistida en localStorage.

Comportamiento:

• si el consentScope es device, el consentimiento se resuelve por visitorId
• si el consentScope es account, el runtime prioriza userRef y cae a visitorId si no existe
• el IP no se usa como identidad principal; solo puede guardarse como metadata tecnica para auditoria

Scope del consentimiento

PDP Suite soporta dos scopes:

device

Es el recomendado para banners de cookies y trackers web.

Caracteristicas:

• cada navegador o dispositivo puede tener una decision distinta
• modo normal e incognito pueden divergir
• aunque el userRef coincida, el consentimiento no se sincroniza entre dispositivos

Usalo cuando:

• el consentimiento controla cookies, local storage, pixels, analytics o scripts del navegador
• quieres respetar el contexto tecnico del dispositivo donde se ejecuta la web

const consent = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_CONSENT_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  consentScope: 'device'
});

account

Es util cuando quieres que una cuenta autenticada comparta el mismo consentimiento entre dispositivos.

Caracteristicas:

• si existe userRef, distintos navegadores autenticados convergen al consentimiento mas reciente
• si no existe userRef, el runtime cae a visitorId
• sirve mejor para experiencias autenticadas o centros de privacidad de cuenta

Usalo cuando:

• tu app exige login
• el consentimiento debe seguir a la cuenta y no solo al navegador
• quieres que un cambio hecho por el usuario en un equipo reaparezca en otro al refrescar

const consent = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_CONSENT_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  consentScope: 'account',
  userRef: window.appSession?.userId
});

Recomendacion practica

• device: default recomendado para banners publicos de cookies
• account: opcion enterprise o para apps autenticadas

El visitorId queda almacenado con esta clave:

pdp-consent-visitor:<tenantPublicKey>

El consentimiento recordado queda almacenado con esta clave:

pdp-consent:<tenantPublicKey>

Estado de consentimiento

getState() retorna un objeto como este:

{
  "tenantPublicKey": "pk_demo_pdpsuite_billy",
  "consentScope": "device",
  "visitorId": "vst_c6a78016f9184c24a2489f68c9c1f62f",
  "userRef": null,
  "policyVersion": "2026.04",
  "grantedCategories": ["performance", "marketing", "necessary"],
  "grantedProviders": ["google-analytics", "meta-pixel", "essential-storage"],
  "receiptId": "rct_92c00cf9944aa92f8235",
  "decisionId": "cns_4d1a17c391f59876d609",
  "issuedAt": "2026-04-19T18:59:18.628Z",
  "updatedAt": "2026-04-19T18:59:18.628Z"
}

Si ves un resultado como:

{
  "reason": "preferences",
  "shouldAsk": false,
  "remembered": true
}

significa que:

• el SDK ya encontro un consentimiento vigente para esa identidad
• la politica activa coincide con la version aceptada
• no deberia volver a mostrarse el banner en esa visita

Consentimientos legales en formularios

El banner de cookies y los consentimientos legales son superficies separadas. Para formularios, el SDK puede montar un bloque oficial renderizado desde la version publicada en PDP Suite. El cliente decide donde ponerlo; PDP Suite resuelve texto, documento, version y evidencia.

import {bootstrapConsent} from '@pdpsuite/consent-sdk';

const pdp = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_COOKIE_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  apiKeys: {
    cookies: import.meta.env.PUBLIC_PDP_COOKIE_KEY,
    legalConsents: import.meta.env.PUBLIC_PDP_LEGAL_CONSENT_KEY
  },
  userRef: window.appUser?.email
});

const legalConsent = await pdp.mountFormConsent('#terms-consent', {
  required: true,
  layout: 'compact',
  showDescription: false,
  maxAcceptanceTextLength: 220
});

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const evidence = await legalConsent.accept({
    rut: form.rut.value,
    correo: form.email.value,
    userRef: window.appUser?.email
  });

  await submitForm({
    ...formData,
    pdpConsent: evidence
  });
});

Metodos nuevos:

• getFormConsent(options): obtiene la version publicada activa para la llave legal. Tambien acepta consentimientoId o consentimientoVersionId solo para casos avanzados/debug.
• mountFormConsent(container, options): monta checkbox, texto oficial, version y documento asociado.
• canSubmitFormConsent(handle): retorna si el bloque requerido ya fue aceptado.
• acceptFormConsent(options): registra aceptacion directamente sin montar UI, util para flujos propios controlados.
• onFormConsentChange(callback): escucha cambios globales de bloques legales montados.

El texto visible junto al checkbox viene en consent.acceptanceText. El runtime lo resuelve desde el snapshot publicado de PDP Suite: primero texto explicito de aceptacion/aviso, luego una clausula publicada asociada al consentimiento, y solo si no existe usa un fallback seguro. El sitio cliente puede montar el bloque, pero no necesita escribir ni versionar esa frase.

El bloque renderizado puede adaptarse al espacio del formulario sin perder trazabilidad. Opciones utiles:

• layout: standard, compact o inline.
• showDescription: permite ocultar la descripcion larga del consentimiento.
• showTitle, showVersion, showDocumentLink: controlan metadata visible.
• maxDescriptionLength y maxAcceptanceTextLength: recortan texto visible con puntos suspensivos.
• className y style: permiten ajustar el contenedor cuando el sitio cliente necesita otro tamano visual.

Si la llave tiene una configuracion publicada en el Fiori de personalizacion, el runtime entrega esos valores como defaults. El sitio cliente solo debe pasar estas opciones cuando quiere sobreescribir puntualmente lo definido en PDP Suite.

Cuando se registra la aceptacion, el runtime vuelve a construir el snapshot de lo mostrado usando estas opciones. Asi la bandeja audita el texto efectivamente visible y no una version generica distinta.

El handle devuelto por mountFormConsent() expone:

• canSubmit(): habilita/deshabilita el submit del formulario cliente.
• accept(identity): registra en CAP con CONSENTIMIENTO_VERSION_ID y devuelve evidencia.
• showError() / clearError(): permite marcar el bloque si el usuario intenta enviar sin aceptar.
• destroy(): desmonta el bloque.

accept() exige identidad (rut, correo o userRef). Un consentimiento legal sin identidad queda debil para auditoria, por eso el runtime lo rechaza.

Documentos legales nativos

Los terminos, politicas y avisos publicos tienen una llave separada porque no registran una aceptacion por si solos: renderizan o entregan el documento oficial publicado. PDP Suite es la fuente autoritativa del texto; no se usan PDF, Word ni URLs externas como documento legal principal.

• mountLegalDocument(container, options): PDP Suite renderiza la pagina/bloque completo con layout oficial.
• getLegalDocument(options): PDP Suite entrega titulo, version visible, hash, HTML seguro, texto plano y clausulas para que el cliente pinte con sus propios componentes.
• mountPublicPolicy() y getPublicPolicy() siguen existiendo como alias compatibles.

const pdp = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_COOKIE_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  apiKeys: {
    cookies: import.meta.env.PUBLIC_PDP_COOKIE_KEY,
    legalConsents: import.meta.env.PUBLIC_PDP_LEGAL_CONSENT_KEY,
    privacyPolicies: import.meta.env.PUBLIC_PDP_PRIVACY_POLICY_KEY
  }
});

await pdp.mountLegalDocument('#terms-page', {
  apiKey: import.meta.env.PUBLIC_PDP_PRIVACY_POLICY_KEY,
  legalDocumentId: '98010000-0000-4000-8000-000000000001'
});

const policy = await pdp.getLegalDocument({
  apiKey: import.meta.env.PUBLIC_PDP_PRIVACY_POLICY_KEY,
  legalDocumentId: '98010000-0000-4000-8000-000000000001'
});

renderMyTermsPage({
  title: policy.title,
  version: policy.versionLabel,
  clauses: policy.clauses
});

En local usamos estas tres llaves para separar poderes: cap-local-playground-key para cookies, cap-local-legal-key para formularios y cap-local-policy-key para terminos/politicas publicas.

Donde se define el texto oficial

El texto que vio la persona no debe salir del sitio cliente. Se define y versiona en PDP Suite:

• Banner de cookies: sale del centro de preferencias publicado en CAP. El runtime lee CENTRO_PREFERENCIA_VERSION, PERSONALIZACION, propositos y cookies, y renderiza el iframe con ese snapshot.
• Botones del banner: deben pertenecer a la version publicada del centro de preferencias. Si el texto cambia, se publica una nueva version para que la evidencia diga que texto/botones estaban vigentes.
• Consentimiento de formulario: sale de CONSENTIMIENTO_VERSION, con su tipo publicado y documento legal versionado.
• Politicas/documentos/avisos: salen de DOCUMENTO_LEGAL_VERSION; el registro guarda version, hash y snapshot del texto aceptado. DOCUMENTOS_TYC queda solo como compatibilidad temporal.

La regla de auditoria es: cuando alguien acepta, PDP Suite guarda version + hash + snapshot. La bandeja no deberia reconstruir desde maestros editables, sino leer lo aceptado desde la version publicada.

Ejemplo de evidencia:

{
  "accepted": true,
  "registroConsentimientoId": "6f2a8f52-11af-4423-a557-e960350d6b89",
  "consentimientoId": "93000000-0000-4000-8000-000000000001",
  "consentimientoVersionId": "97000000-0000-4000-8000-000000000002",
  "legalDocumentId": "98010000-0000-4000-8000-000000000001",
  "legalDocumentVersionId": "99010000-0000-4000-8000-000000000001",
  "legalDocumentHashContenido": "seed-hash-legal-terms-v1",
  "hashContenido": "seed-hash-consent-legal-v1",
  "acceptedAt": "2026-04-24T10:00:00.000Z",
  "identity": {
    "rut": "11111111-1",
    "correo": null,
    "userRef": null
  }
}

Eventos de cambio

onChange() entrega tanto el estado anterior como el nuevo, ademas de un diff granular:

const unsubscribe = consent.onChange((event) => {
  console.log(event.source);
  console.log(event.previousState);
  console.log(event.state);
  console.log(event.changes.categories.added);
  console.log(event.changes.categories.removed);
  console.log(event.changes.providers.added);
  console.log(event.changes.providers.removed);
});

source puede ser:

• banner
• preferences
• refresh
• revoke

Endpoints esperados del runtime

El SDK espera que el runtime implemente al menos:

• GET /api/tenants/:tenantPublicKey/banner
• POST /api/sessions
• GET /api/consents/current
• POST /api/consents
• GET /embed/:tenantPublicKey
• GET /api/legal-consents/:tenantPublicKey/active
• POST /api/legal-consents/:tenantPublicKey/accept
• GET /api/public-policies/:tenantPublicKey/active
• GET /api/legal-documents/:tenantPublicKey/active

Ejemplo de integracion orientada a consulta

import {bootstrapConsent} from '@pdpsuite/consent-sdk';

const consent = await bootstrapConsent({
  tenantPublicKey: import.meta.env.PUBLIC_PDP_CONSENT_KEY,
  runtimeOrigin: import.meta.env.PUBLIC_PDP_CONSENT_ORIGIN,
  consentScope: 'device',
  userRef: window.appSession?.userId
});

if (consent.canUseCategory('marketing')) {
  window.loadMarketingScripts?.();
}

consent.onChange((event) => {
  if (event.changes.providers.added.includes('meta-pixel')) {
    window.enableMetaPixel?.();
  }
});

Notas operativas

• tenantPublicKey es publico. No debe tratarse como secreto.
• La autorizacion real depende del runtime, el tenant, el origen permitido, la sesion y la decision registrada.
• El SDK recuerda la ultima decision local, pero init() y shouldAsk() consultan el runtime para validar si sigue vigente.
• Si quieres una integracion de una sola linea en el frontend, usa bootstrapConsent().
• Si el consentimiento es de cookies/tracking web, usa consentScope: 'device'.
• Si quieres sincronizar consentimiento entre dispositivos autenticados, usa consentScope: 'account' junto con userRef.

Licencia

Copyright 2026 PDP Suite. Todos los derechos reservados.