Personalización

Esta página es la guía para aplicaciones host que necesitan personalizar la pantalla embebida de consentimientos. La personalización es opcional.

Cuándo activar configuración del host

Usa la integración por defecto cuando el host solo necesita mostrar y guardar consentimientos. Añade enableCustomConfig=true solo cuando el host necesite enviar configuración JSON antes de que el componente renderice.

enableCustomConfig no selecciona entre componentes Legacy y Custom. El runtime siempre usa el camino actual de UI Custom.

Handshake de configuración

Host carga iframe/WebView con ?enableCustomConfig=true
  -> mas-consents inicializa el bridge
  -> mas-consents envía CONSENTS_CONFIG_REQUIRED
  -> el host responde con SET_CONFIG { payload: ... }
  -> mas-consents sanea overrides de diseño inválidos
  -> mas-consents construye el tema y renderiza
  -> mas-consents obtiene consentimientos
  -> mas-consents emite CONSENTS_LOADED
  -> el cliente guarda
  -> mas-consents emite CONSENTS_COMPLETED o CONSENTS_ERROR

Si enableCustomConfig=true está presente y el host nunca envía SET_CONFIG, el componente no renderiza nada de forma intencionada.

Payload de SET_CONFIG

El host envía la configuración en la clave payload del mensaje SET_CONFIG. Estas son las claves de primer nivel soportadas dentro de payload; todas son opcionales.

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light",
    "design": {},
    "uiOptions": {},
    "useMockData": false,
    "consentIds": ["C01", "C02"]
  }
}

Ejemplo mínimo:

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light"
  }
}

Ejemplo más completo:

{
  "type": "SET_CONFIG",
  "payload": {
    "theme": "light",
    "consentIds": ["C01", "C02"],
    "design": {
      "tokens": {
        "container-background-color": "base.primary",
        "footer-button-background-color": "#3466F5",
        "footer-button-radius": "md",
        "title-typography": {
          "style": "h4",
          "mobile": {
            "style": "h5",
            "family": "Menlo"
          }
        }
      }
    },
    "uiOptions": {
      "groupDisplay": "flat",
      "collapsible": true,
      "showDescription": true
    }
  }
}

Opciones de design

Define los overrides visuales en payload.design.tokens. Cada clave es un token de dominio público que representa un uso concreto de Consents.

{
  "type": "SET_CONFIG",
  "payload": {
    "design": {
      "tokens": {
        "component-background-color": "primary",
        "global-padding-x": "base",
        "statement-help-icon-size": "500"
      }
    }
  }
}

El resolver canónico acepta estos valores:

Usa preferentemente las referencias abreviadas del editor, como primary, red.700, sm, 400, thin, md o 2. Las rutas DS completas compatibles siguen aceptándose.

Las rutas semánticas de color y sombra se normalizan al modo activo light o dark. Las rutas semánticas de tipografía se normalizan al breakpoint activo desktop o mobile. Las rutas no soportadas y los nombres de token de dominio desconocidos se ignoran y se mantiene el valor predeterminado.

Consulta Tokens de dominio para ver el catálogo público.

Tipografía responsive

Un token de dominio tipográfico puede seleccionar un estilo DS completo con un solo valor:

{
  "design": {
    "tokens": {
      "footer-button-typography": "md"
    }
  }
}

Usa la forma de objeto para cambiar la familia o especializar escritorio y móvil. Los valores globales afectan a ambos breakpoints; desktop o mobile prevalece en su modo.

{
  "design": {
    "tokens": {
      "title-typography": {
        "style": "h4",
        "family": "Inter",
        "desktop": {
          "style": "h3"
        },
        "mobile": {
          "style": "h5",
          "family": "Menlo"
        }
      }
    }
  }
}

La API canónica solo permite sobrescribir family. El tamaño, peso, interlineado y espaciado entre letras se resuelven siempre desde el estilo completo. El título admite h1 a h6; el botón del pie, base, md y xs; el resto de tokens tipográficos, los estilos completos de body.

Validación y fallback

Cuando el host envía SET_CONFIG, el runtime sanea los overrides de tokens antes de construir el tema. Las reglas, límites y valores de fallback están documentados en Validaciones de tokens.

uiOptions

uiOptions permite ajustar la presentación y algunos comportamientos de la interfaz sin modificar los consentimientos ni sus reglas de negocio. Todas las opciones son opcionales.

Ejemplo con todas las opciones:

{
  "type": "SET_CONFIG",
  "payload": {
    "uiOptions": {
      "collapsible": true,
      "languageSelector": true,
      "showDescription": true,
      "descriptionsAlwaysVisible": false,
      "groupDisplay": "boxed",
      "title": "Gestión de consentimientos",
      "description": "Revisa y confirma tus preferencias de consentimiento."
    }
  }
}

Consideraciones:

• showDescription controla exclusivamente la descripción de la cabecera; descriptionsAlwaysVisible controla las descripciones de los consentimientos.
• collapsible solo añade el control de expansión a consentimientos padre que tengan hijos. Si la validación detecta un consentimiento hijo obligatorio sin completar, su grupo se expande automáticamente para hacerlo visible.
• Con descriptionsAlwaysVisible=false, al expandir un grupo colapsable también se muestra en línea la descripción del consentimiento padre.
• El selector de idioma solo ofrece los idiomas habilitados por la configuración de ejecución.
• Los valores personalizados de title y description son textos literales y no se traducen automáticamente al cambiar de idioma.
• groupDisplay solo modifica la composición visual; no altera la jerarquía, el orden ni la editabilidad de los consentimientos.

consentIds

consentIds permite al host solicitar un subconjunto concreto de consentimientos.

{
  "type": "SET_CONFIG",
  "payload": {
    "consentIds": ["C01", "C02", "C03"]
  }
}

Comportamiento:

• el host envía consentIds en SET_CONFIG
• el frontend lo reenvía como consent_ids=C01,C02,C03 en la petición GET de consents
• el backend decide qué consentimientos devueltos son editables y cuáles vienen como read_only=true
• los statements de solo lectura siguen visibles, pero el cliente no puede modificarlos

useMockData

useMockData está pensado solo para validación local y STA.

{
  "type": "SET_CONFIG",
  "payload": {
    "useMockData": true
  }
}

Comportamiento:

• el runtime usa datos mock de consentimientos en lugar de llamar al backend
• solo se respeta cuando ENV vale LOCAL o STA
• en PRO, el flag se ignora

Ejemplo mínimo de host web

const iframe = document.querySelector<HTMLIFrameElement>('#mas-consents')
const consentsOrigin = new URL(iframe?.src ?? 'https://consents.masstack.com').origin

window.addEventListener('message', (event) => {
  if (event.origin !== consentsOrigin) return

  const msg = event.data
  if (msg?.source !== 'consents') return

  if (msg.type === 'CONSENTS_CONFIG_REQUIRED') {
    iframe?.contentWindow?.postMessage(
      {
        type: 'SET_CONFIG',
        payload: {
          theme: 'light',
          consentIds: ['C01', 'C02'],
          design: {
            tokens: {
              'footer-button-background-color': '#3466F5',
            },
          },
          uiOptions: {
            groupDisplay: 'flat',
            collapsible: true,
          },
        },
      },
      '*',
    )
  }
})

Sistema de personalización legacy

Consents ha adoptado un sistema de tokens de dominio para alinear su API pública de personalización con el Design System actual de MasStack. Todas las nuevas configuraciones y migraciones deben usar design.tokens.

Los valores del contrato anterior por categorías están deprecados. El runtime continúa resolviéndolos únicamente para mantener la retrocompatibilidad y evitar romper integraciones ya existentes; este soporte no implica que deban usarse en nuevas implementaciones.