Javascript-APIs
CCM19 bietet mehrere Javascript-APIs, mit denen auf Funktionalitäten des Cookie-Managers zugegriffen und auf Benutzerinteraktionen reagiert werden kann.
Globales Objekt
Die direkten Steuerungsmöglichkeiten von CCM19 sind im globalen Javascript-Objekt CCM
gebündelt:
Variable/Methode | Typ | Beschreibung |
---|---|---|
CCM.acceptedCookies | string[] | Liste der Namen aller akzeptierten Cookies. |
CCM.acceptedEmbeddings | [ { id: string , name: string , } , … ] |
Liste aller akzeptierten Embeddings.(ab Version 2020.10.28) |
CCM.availableLocales() | string[] | Liste aktiver Sprachen – z. B. ['de_DE', 'en_US'] (ab Version 2022.03.24) |
CCM.closeControlPanel() | Schließt den Dialog zur Auswahl der zu akzeptierenden Zwecke. | |
CCM.closeWidget() | Schließt den Cookie-Dialog. | |
CCM.consent | boolean | Gibt an, ob der Seitenbesucher seine Consent-Einstellungen festgelegt und abgespeichert hat. Das kann u. a. also auch bedeuten, dass alles abgelehnt wurde. |
CCM.crossDomainConsentString | string | Fragmentbezeichner zum manuellen Zusammensetzen einer URL für die Consent-Teilung.(ab Version 2020.10.14) |
CCM.fullConsentGiven | boolean | Gibt an, ob der Seitenbesucher allen Optionen zugestimmt hat. Ein positives Ergebnis impliziert selbiges für CCM.consent .(nach Version 2023.03.29) |
CCM.navigate(url[, replace[, navigateTop]]) | Navigiert zu einer anderen URL (wie location.href = url ), berücksichtigt dabei aber die Consent-Teilung. replace steuert, ob location.replace verwendet wird und navigateTop steuert, ob bei Frames die vollständige Seite navigiert wird.(ab Version 2020.10.14) |
|
CCM.openControlPanel() | Öffnet den Dialog zur Auswahl der zu akzeptierenden Zwecke. | |
CCM.openWidget() | Öffnet den Cookie-Dialog erneut. | |
CCM.switchLocale(localeName) | Wechselt die Sprache – siehe CCM.availableLocales() (ab Version 2022.03.24) |
|
CCM.ucid | ?string | Die eindeutige Consent-ID, oder null, wenn noch kein Consent erteilt wurde. |
CCM.version | string | Enthält die aktuelle CCM19-Version.(ab Version 2020.10.28) |
Die Dialoge können alternativ auch über Links mit den Zielen #CCM.openWidget
, #CCM.closeWidget
, #CCM.openControlPanel
und #CCM.closeControlPanel
gesteuert werden.
Erweiterung für werbe- und trackingfreie Netzwerke
Sofern die Option "Meine Website ist Teil eines werbe- und trackingfreien Netzwerks" im Bereich Developer-Einstellungen > Frontend-Verhalten der Domain aktiv ist, sind folgende Endpunkte definiert und können im Frontend verwendet werden.
Die folgenden Endpunkte wurden mit der Version 2023.03.20 veröffentlicht und sind in älteren Versionen nicht verfügbar.
Variable/Methode | Typ | Beschreibung |
---|---|---|
CCM.denyAllPrivileges() | Function | Alias für CCM.revokeAllPrivileges() . |
CCM.grantAllPrivileges() | Function | Erlaube sämtliche Kategorien, Einbindungen, TCF-Anbieter etc. Diese Funktion setzt voraus, dass die vollständige Zustimmung durch den Seitenbesucher signalisiert wurde. In Abhängigkeit von CCM.requiresConsentUpdate kann eine erneute Zustimmung erforderlich sein. Bitte nur einmal pro Benutzerinteraktion aufrufen, nicht wiederholt pro Seitenaufruf. Seit Version 2023.07.17 wird zusätzlich das Event ccm19WidgetClosed ausgelöst. |
CCM.revokeAllPrivileges() | Function | Lehne sämtliche Kategorien, Einbindungen, TCF-Anbieter etc. ab. Diese Funktion setzt voraus, dass dies durch den Seitenbesucher signalisiert wurde. Technisch notwendige Einbindungen werden weiterhin geladen.Bitte nur einmal pro Benutzerinteraktion aufrufen, nicht wiederholt pro Seitenaufruf.Seit Version 2023.07.17 wird zusätzlich das Event ccm19WidgetClosed ausgelöst. |
CCM.requiresConsentUpdate | boolean | Signalisiert, dass CCM19 eine Aktualisierung der Consent-Einstellungen erwartet. Das bedeutet, dass entweder - noch kein Consent konfiguriert wurde (erster Seitenbesuch) oder - sich in der CCM19-Konfiguration etwas rechtlich Relevantes geändert hat oder - die festgelegte Gültigkeitsdauer abgelaufen ist. Dieser Wert sollte bei jedem Seitenaufruf überprüft und berücksichtigt werden. In den obigen Fällen wird seit Version 2023.07.17 zusätzlich das Event ccm19WidgetOpened ausgelöst. |
CCM.embeddings | Object[] | Liefert ein Array über alle Einbindungen und stellt die textuellen Inhalte zur weiteren Verwendung bereit. Sowohl für die Einbindungen als auch deren assets (Cookies) werden Übersetzungen für alle Sprachen geliefert, die für das Frontend aktiv sind. CCM.embeddings[].name CCM.embeddings[].vendor CCM.embeddings[].l10n.de_DE CCM.embeddings[].l10n.en_US CCM.embeddings[].l10n._ CCM.embeddings[].assets[].name CM.embeddings[].assets[].type CCM.embeddings[].assets[].l10n Mit l10n._ stehen neben den aktiven Locales noch die Spracheinträge der Fallback-Sprache (je Kundenkonto definiert) zum Abruf bereit. Da nicht jede CMP-Konfiguration dieselben Sprachen für das Banner vorsieht, steht damit ein generell vorhandener Eintrag bereit; die Sprache der Einträge hängt jedoch von der Konfiguration ab.(nach Version 2024.03.13) |
CCM.tcf.customVendors | string[] | Enthält alle Anbieter, die in CCM19-Einbindungen definiert sind, aber keine TCF-Anbieter sind.(ab Version 2023.06.01) |
CCM.tcf.enabled | boolean | Zeigt an, ob die Unterstützung für das IAB-Framework aktiv ist. |
CCM.tcf.stacks | int[] | Enthält die TCF-Stacks, die die gegebene CCM19-Konfiguration einer Website repräsentieren.(ab Version 2023.06.01) |
CCM.tcf.vendors | Object[] | Jedes Objekt enthält neben der Anbieter-ID noch die verwendeten Purposes.Mit CCM.tcf.vendors.map(x => x.id) können die IDs aller aktiven Anbieter ausgelesen werden.Bis Version 2023.05.25 war diese Eigenschaft noch als Objekt statt als Array implementiert; die Anpassung hat in Absprache mit dem ersten Nutzer dieses Features stattgefunden. |
Da die obigen Schnittstellen nur verfügbar sind, wenn die entsprechende Option für werbe- und trackingfreie Netzwerke aktiv ist, sollte der Netzwerkbetreiber die Verfügbarkeit in seinem Code überprüfen, um den Zugriff auf undefinierte Eigenschaften zu verhindern. Der eigene Code sollte daher z. B. wie folgt eingeklammert werden.
if (typeof window.CCM == 'object' && typeof window.CCM.denyAllPrivileges == 'function') {
// Option "Meine Website ist Teil eines werbe- und trackingfreien Netzwerks" ist aktiv
// und der Zugriff auf die Eigenschaften kann erfolgen.
}
else {
console.log('Bitte Option in CCM19 aktivieren.');
}
Javascript-Events
Einige Ereignisse in CCM19 werden zu CustomEvents auf dem window
-Objekt abgebildet und mit window.addEventListener(…)
kann darauf reagiert werden.
Event | detail-Eigenschaft | Beschreibung |
---|---|---|
ccm19CookieAccepted | { name: string , code: string , purpose: string , mandatory: boolean , } |
Ein Cookie wurde durch den Nutzer akzeptiert. Dieses Event wird für jedes Cookie ausgelöst, das in den akzeptierten Zwecken gelistet ist.Diese Events erfolgen beim Erteilen des Consents durch den Besucher und werden bei jeden folgenden Seitenbesuch beim Laden der Seite wiederholt. Veraltet: Bitte auf ccm19EmbeddingAccepted umsteigen. |
ccm19EmbeddingAccepted | { name: string , code: string , purpose: string , mandatory: boolean , } |
Ein Embedding wurde durch den Nutzer akzeptiert. Diese Events erfolgen beim Erteilen des Consents durch den Besucher und werden für jeden Seitenaufruf wiederholt.(ab Version 2020.10.28) |
ccm19WidgetClosed | null | Wird ausgelöst, sobald das letzte sichtbare CCM19-Widget-Element geschlossen wird. Dabei kann es sich um ein Resultat eines Klicks auf einen Speichern-Button handeln, der zum Schließen des Widgets führt. |
ccm19WidgetOpened | null | Wird ausgelöst, sobald das erste CCM19-Widget-Element angezeigt wird. Dabei kann es sich um das initiale Öffnen beim Seitenaufruf oder auch um eine Interaktion zu einem späteren Zeitpunkt, z. B. über das Einstellungs-Icon, handeln. |
ccm19WidgetLoaded | null | Wird ausgelöst, sobald CCM19 fertig initialisiert wurde. |