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": {
      "color": {
        "background-button-default": "#3466F5"
      },
      "radius": {
        "radius-button": 8
      },
      "typography": {
        "headings-h4-size": "font-size-24",
        "xs": {
          "headings-h4-size": "font-size-20"
        }
      }
    },
    "uiOptions": {
      "groupDisplay": "flat",
      "collapsible": true,
      "showDescription": true
    }
  }
}

Opciones de design

Define los overrides visuales en la clave design dentro de payload. Estos son los grupos soportados:

{
  "type": "SET_CONFIG",
  "payload": {
    "design": {
      "color": {},
      "spacing": {},
      "typography": {},
      "radius": {},
      "shadows": {},
      "border": {},
      "components": {}
    }
  }
}

Semántica de valores soportados:

Usa claves de tokens semánticos como nombres de override. El valor puede ser una clave de token primitivo o un valor directo, según la categoría. Consulta Tokens semánticos y Tokens primitivos para ver el catálogo actual.

Restricciones importantes:

• border no acepta declaraciones CSS arbitrarias como 1px solid red.
• typography no acepta tamaños de fuente arbitrarios ni snippets CSS.
• color es la categoría más permisiva porque acepta valores CSS de color válidos.

Tipografía responsive

El modelo de tipos expone xs, sm, md, lg, xl y base, pero el resolver actual usa de forma efectiva dos grupos:

• xs para móvil
• xl para cualquier caso que no sea xs

Uso recomendado:

• pon valores compartidos en el nivel superior
• añade xs cuando móvil necesite diferir
• añade xl cuando tablet/escritorio necesite diferir del valor superior
• evita bloques sm, md, lg y base hasta que el resolver los consuma explícitamente

{
  "type": "SET_CONFIG",
  "payload": {
    "design": {
      "typography": {
        "headings-h4-size": "font-size-24",
        "typography-base-family": "font-family-inter",
        "xs": {
          "headings-h4-size": "font-size-20"
        },
        "xl": {
          "headings-h4-lineheight": "line-height-2xl"
        }
      }
    }
  }
}

uiOptions

Define los overrides de comportamiento de UI en la clave uiOptions dentro de payload. Este ejemplo muestra las opciones soportadas:

{
  "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."
    }
  }
}

Notas:

• showDescription vale true por defecto cuando se omite.
• groupDisplay='boxed' cambia la presentación de grupos, bordes y contenedores.
• title y description sobrescriben el texto mostrado por la pantalla.

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 y límites actuales están documentados en Validaciones de tokens.

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')

window.addEventListener('message', (event) => {
  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: {
            color: {
              'background-button-default': '#3466F5',
            },
          },
          uiOptions: {
            groupDisplay: 'flat',
            collapsible: true,
          },
        },
      },
      '*',
    )
  }
})