SDK-documentatie

# adconsent JavaScript-SDK

Deze handleiding beschrijft het inbouwen van adconsent (`/cmp/v1/cmp.js`), het blokkeren van scripts en iframes tot toestemming, Google Consent Mode v2, de IAB-interfaces `__tcfapi` / `__gpp` en de JavaScript-API `window.cmp`.

## Installatie (snippet)

**Het snippet moet als eerste in `<head>` staan.** Tags die in de HTML vóór de CMP staan, laadt de browser meteen en kunnen niet meer worden geblokkeerd.

```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>
```

Aanroepen vóór het laden van `cmp.js` komen in de wachtrij `cmp.q`, bijvoorbeeld `cmp.q.push(["show"])`.

Het land van de bezoeker wordt op de server bepaald. Om een ander land te testen: `window.__CMP_BASE__.country = "US"` (alleen tests).

## Handmatig blokkeren

```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` : IAB-vendor-id uit de Global Vendor List.
- `data-cmp-custom` : sleutel van een eigen vendor in de admin.
- `data-cmp-purposes` : IAB-doeleinde-id's; ze moeten allemaal toestemming hebben.

## API (`window.cmp`)

| Methode | Beschrijving |
| --- | --- |
| `consentAll()` | Alle doeleinden en vendors accepteren |
| `declineAll()` | Alles weigeren / opt-out |
| `show()` / `open()` | Banner of instellingen opnieuw openen |
| `getConsent()` | Huidige status |
| `hasConsent(vendorIdOrCustomKey)` | `cmp.hasConsent(755)` or `cmp.hasConsent("hotjar")` |
| `on(event, cb)` / `off(event, cb)` | Events: `ready`, `consent`, `shown`, `hidden` |
| `setLanguage(lang)` | Taal wisselen (bijvoorbeeld `"nl"`) |
| `console()` / `console(false)` | Debugconsole openen / sluiten |

Opnieuw openen is verplicht volgens het TCF-beleid: zet op elke pagina een link, bijvoorbeeld `<a href="#" data-adconsent-open>Cookie-instellingen</a>`.

## Debugconsole (cmpconsole)

Open een pagina met `?cmpconsole` of `#cmpconsole`, of roep `cmp.console()` aan. Sluit met ✕, `cmp.console(false)` of `?cmpconsole=0`.

Volledige handleiding: /docs/cmpconsole

## `__tcfapi` / `__gpp`

- EU/EER, Verenigd Koninkrijk en Zwitserland: `__tcfapi` volgens de IAB TCF v2.3 CMP-API. De synchrone stub levert meteen `__tcfapi` en `iframe[name=__tcfapiLocator]`.
- Testomgeving: tot registratie bij IAB Europe gebruikt adconsent test-CMP-ID `999`. Het is nog geen bij IAB Europe geregistreerde CMP.
- Verenigde Staten (`gpp_us`): `__gpp` met de Amerikaanse nationale sectie (opt-out). Een ingestelde Global Privacy Control geldt als opt-out.

## Google Consent Mode v2

Standaard `denied` (met `wait_for_update`) in het snippet. Na de beslissing stuurt adconsent `gtag('consent','update',…)` volgens de property-mapping.

## Regimes

| Regime | Landen | Model |
| --- | --- | --- |
| `tcf_eu` | UE/EEE | Opt-in (IAB TCF) |
| `tcf_uk` | Verenigd Koninkrijk | Opt-in (IAB TCF) |
| `ch` | Zwitserland | Opt-in (IAB TCF) |
| `gpp_us` | Verenigde Staten | Opt-out (GPP) |
| `notice_only` / `none` | overige landen | per property instelbaar |

## Cookie declaration

Openbare cookielijst: `https://UW-CMP-DOMEIN/c/PROPERTY_KEY/cookie-declaration`

## Problemen oplossen

1. Geen banner → is er een configuratie gepubliceerd? Antwoordt `config.json` met 200? De console (`?cmpconsole`) toont fouten in het log.
2. Scripts laden vóór toestemming → staat het snippet als eerste in `<head>`?
3. De wachtrij loopt niet → staat `window.cmp = window.cmp || { q: [] }` vóór `cmp.js`?
4. Google Consent Mode blijft `denied` → zijn `gtag` / `dataLayer` vóór de CMP gedefinieerd?
5. Een ander land testen → demopagina van de property met `?country=US`.