Documentación del SDK

# SDK JavaScript de adconsent

Esta guía describe la integración de adconsent (`/cmp/v1/cmp.js`), el bloqueo de scripts e iframes hasta el consentimiento, Google Consent Mode v2, las interfaces IAB `__tcfapi` / `__gpp` y la API JavaScript `window.cmp`.

## Instalación (snippet)

**El snippet debe ser lo primero en `<head>`.** Las etiquetas que están en el HTML antes de la CMP las carga el navegador de inmediato y ya no se pueden bloquear.

```html
<script src="https://YOUR-CMP-DOMAIN/cmp/v1/stub.js"></script>
<script>
  window.cmp = window.cmp || { q: [] };
  window.__CMP_BASE__ = {
    apiBase: "https://YOUR-CMP-DOMAIN",
    propertyKey: "PROPERTY_PUBLIC_KEY"
  };
  window.dataLayer = window.dataLayer || [];
  function gtag(){ dataLayer.push(arguments); }
  gtag("consent", "default", {
    ad_storage: "denied", ad_user_data: "denied", ad_personalization: "denied",
    analytics_storage: "denied", functionality_storage: "denied",
    personalization_storage: "denied", security_storage: "granted",
    wait_for_update: 500
  });
</script>
<script src="https://YOUR-CMP-DOMAIN/cmp/v1/cmp.js" async></script>
```

Las llamadas hechas antes de que cargue `cmp.js` se encolan en `cmp.q`, por ejemplo `cmp.q.push(["show"])`.

El país del visitante se determina en el servidor. Para probar otro país: `window.__CMP_BASE__.country = "US"` (solo pruebas).

## Bloqueo manual

```html
<script type="text/plain" data-cmp-vendor="755" src="https://example.com/tag.js"></script>
<iframe data-cmp-src="https://www.youtube.com/embed/…" data-cmp-custom="youtube"></iframe>
```

- `data-cmp-vendor` : identificador de vendor IAB de la Global Vendor List.
- `data-cmp-custom` : clave de un vendor personalizado del admin.
- `data-cmp-purposes` : identificadores de finalidades IAB; todas deben tener consentimiento.

## API (`window.cmp`)

| Método | Descripción |
| --- | --- |
| `consentAll()` | Aceptar todas las finalidades y vendors |
| `declineAll()` | Rechazar todo / opt-out |
| `show()` / `open()` | Volver a abrir el banner o los ajustes |
| `getConsent()` | Estado actual |
| `hasConsent(vendorIdOrCustomKey)` | `cmp.hasConsent(755)` or `cmp.hasConsent("hotjar")` |
| `on(event, cb)` / `off(event, cb)` | Events: `ready`, `consent`, `shown`, `hidden` |
| `setLanguage(lang)` | Cambiar el idioma (por ejemplo `"es"`) |
| `console()` / `console(false)` | Abrir / cerrar la consola de depuración |

Reapertura exigida por la política TCF: ponga un enlace en cada página, por ejemplo `<a href="#" data-adconsent-open>Ajustes de cookies</a>`.

## Consola de depuración (cmpconsole)

Abra una página con `?cmpconsole` o `#cmpconsole`, o llame a `cmp.console()`. Cierre con ✕, `cmp.console(false)` o `?cmpconsole=0`.

Guía completa: /docs/cmpconsole

## `__tcfapi` / `__gpp`

- UE/EEE, Reino Unido y Suiza: `__tcfapi` según la API CMP de IAB TCF v2.3. El stub síncrono proporciona de inmediato `__tcfapi` e `iframe[name=__tcfapiLocator]`.
- Entorno de prueba: hasta el registro en IAB Europe, adconsent usa el ID CMP de prueba `999`. Todavía no es una CMP registrada en IAB Europe.
- Estados Unidos (`gpp_us`): `__gpp` con la sección nacional de EE. UU. (opt-out). Un Global Privacy Control activo se trata como opt-out.

## Google Consent Mode v2

Valor por defecto `denied` (con `wait_for_update`) en el snippet. Tras la decisión, adconsent envía `gtag('consent','update',…)` según el mapeo de la property.

## Regímenes

| Régimen | Países | Modelo |
| --- | --- | --- |
| `tcf_eu` | UE/EEE | Opt-in (IAB TCF) |
| `tcf_uk` | Reino Unido | Opt-in (IAB TCF) |
| `ch` | Suiza | Opt-in (IAB TCF) |
| `gpp_us` | Estados Unidos | Opt-out (GPP) |
| `notice_only` / `none` | otros países | configurable por property |

## Cookie declaration

Lista pública de cookies: `https://SU-DOMINIO-CMP/c/PROPERTY_KEY/cookie-declaration`

## Resolución de problemas

1. No hay banner → ¿hay una configuración publicada? ¿`config.json` responde 200? La consola (`?cmpconsole`) muestra los errores en el registro.
2. Hay scripts antes del consentimiento → ¿el snippet es el primero en `<head>`?
3. La cola no se ejecuta → ¿`window.cmp = window.cmp || { q: [] }` está antes de `cmp.js`?
4. Google Consent Mode sigue en `denied` → ¿`gtag` / `dataLayer` están definidos antes de la CMP?
5. Probar otro país → página demo de la property con `?country=US`.