Iubenda logo
Generator starten

Anleitungen

INHALTSÜBERSICHT

Consent Solution – JS-Dokumentation

Die JavaScript-Bibliothek der Consent Solution ermöglicht es Ihnen, die von Ihren Nutzern durchgeführten Einwilligungshandlungen aufzuzeichnen, die im weiteren Verlauf dieser Anleitung als „Betroffene“ bezeichnet werden.

Die JavaScript-Bibliothek der Consent Solution hat folgende Merkmale:

  • Direktes Schreiben in die Consent Solution API (d.h. Aufzeichnung der Einwilligung)
  • Schreiben Sie sowohl synchron als auch asynchron, wahlweise unter Nutzung von localStorage
  • Mehrere Trackingoptionen für Einwilligungen. Sie können nicht nur ein bestimmtes Formular überwachen und die Einwilligung beim Einreichen nachverfolgen, sondern Sie können die Einwilligung auch mit anderen programmgesteuerten Mitteln nachverfolgen (z.B. nach einem Bestätigungsvorgang oder nach einem anderen Ereignis).
  • Unterstützt die meisten Browser (IE8+)
  • Ermöglicht Rückrufe
  • Logging-Funktionen
Wichtig

Am 03.04.2019 wurde eine neue Version der Consent Solution JS veröffentlicht; wenn Sie die Consent Solution vor diesem Datum installiert haben und auf die neue Version umsteigen möchten, lesen Sie bitte diesen Abschnitt (am Ende dieses Beitrags).

1. Installationsskript

Um das Consent Solution JS-Widget zu installieren, fügen Sie Ihren Consent Solution-Code in jede Seite Ihrer Website ein, bevor Sie den HEAD-Tag schließen (siehe Beispielcode unten).

<script type="text/javascript">
    var _iub = _iub || {};
    _iub.cons_instructions = _iub.cons_instructions || [];
    _iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}]);
</script>
<script type="text/javascript" src="https://cdn.iubenda.com/cons/iubenda_cons.js" async></script>

*Der API-Schlüssel ist ein eindeutiger Code, den das SDK verwendet, um mit dem Endpunkt unserer API zu kommunizieren. Ihr API-Schlüssel (im obigen Beispiel als “YOUR_PUBLIC_API_KEY” angezeigt) wird von uns während der Aktivierung der Consent Solution generiert und ist spezifisch für diese bestimmte Website.

Achtung

Der obige Code ist nur ein Beispiel. Bitte stellen Sie sicher, dass Sie Ihren eigenen Consent Solution-Code verwenden, da der Code spezifisch für Ihre Website ist. Sie finden Ihr Code-Snippet unter Dashboard > [Ihr Website-Bereich] > Consent Solution > Einbinden. Dort kopieren Sie einfach die Informationen, die Sie benötigen.

2. init-Konfiguration

Die Funktion init (im obigen Installationsskript enthalten) definiert, wie die Bibliothek erstellt und auf jeder Seite, die das Consent Solution Widget implementiert, benötigt wird.

Es ist möglich, eine Rückruf-Funktion als zweiten Parameter der init-Funktion hinzuzufügen. Die Rückruf-Funktion wird dann ausgeführt, sobald die Bibliothek geladen wurde.

Wenn Sie die init-Funktion auf diese Weise konfigurieren (durch Hinzufügen einer Rückruf-Funktion – siehe “YOUR_CALLBACK” im Beispiel unten), können Sie eine zusätzliche Aktivität festlegen, nachdem die Bibliothek geladen wurde.

_iub.cons_instructions.push(["init", {
    api_key: "YOUR_PUBLIC_API_KEY"},
    function YOUR_CALLBACK() {
        //the library has been loaded
        ...
        //put you code here
	...
    }
]);

Im Folgenden sind die Parameter aufgeführt, die Sie innerhalb des init-Konfigurationsobjekts (d.h. der erste Parameter bei der Init-Funktion, der den API-Schlüssel enthält) verwenden können, um z.B. den Logger oder das Verhalten der Bibliothek anzupassen.

Siehe Tabelle und Codebeispiel unten:

Name Erforderlich Typ Notizen
api_key Ja String Ihr öffentlicher Schlüssel
logger Nein String Mögliche Werte: “none”, “console”. Voreinstellung: “console”
log_level Nein String Mögliche Werte: “none”, “debug”, “info”, “warn”, “error”, “fatal”. Voreinstellung: “error”
sendFromLocalStorageAtLoad Nein Boolean Bestimmt, ob das Skript beim Laden localStorage liest und alles, was enthalten ist, sendet. Voreinstellung ist: true
// Eine Beispielkonfiguration mit ergänzten optionalen Parametern (Hinweis: api_key-Parameter ist immer erforderlich)

_iub.cons_instructions.push(["init", {
    api_key: "YOUR_PUBLIC_API_KEY",
    logger: "console",
    log_level: "warn",
    sendFromLocalStorageAtLoad: false
}, ...]);

3. Verbinden Sie die Consent Solution mit einem Anmeldeformular

Um die über ein Anmeldeformular erteilten Einwilligungen automatisch zu erfassen, können Sie entweder die load-Funktion oder die submit-Funktion verwenden.

3.1 load

Die load-Funktion ermöglicht es Ihnen, Felder des consent-Objekts an Eingabefelder mit <form> zu binden und die Einwilligung zum Zeitpunkt der Einreichung automatisch aufzuzeichnen.

Wichtig: Die load-Funktion darf erst nach der Angabe des form-Objekts aufgerufen werden (wie im Beispiel unten zu sehen ist).

Wir empfehlen, den <script>-Tag nach dem<form>-Tag wie folgt einzufügen:

<form>
    <!-- Your form input fields -->
    <input type="submit" id="submit-btn" name="submit-button" />
</form>

<script type="text/javascript">
    _iub.cons_instructions.push([ * "load" * ,
        {
            submitElement: "submit-btn", // if this line is missing, the consent is not automatically recorded at submit time; a call to _iub.cons.sendData (see section below) is needed instead
            form: {
                ...your form object
            },
            consent: {
                legal_notices: [{
                    identifier: "term",
                    version: "1"
                }]
            }
        }
    ])
</script>

Parameter:

Name Erforderlich Typ Notizen
submitElement Nein String oder DOM-Element Geben Sie die Id-Zeichenfolge oder das DOM-Element eines Elements weiter, das die Übermittlung der Einwilligung auslöst, wenn es angeklickt wird. Wenn dieses Element nicht angegeben oder nicht ausgelöst wird, müssen Sie _iub.cons.sendData() aufrufen, um die Einwilligung aufzuzeichnen (siehe auch unten).
form Nein/Ja, wenn Einwilligung nicht definiert ist FormConfig Überprüfen Sie den form-Objektbereich
consent Nein/Ja, wenn form nicht definiert ist ConsentConfig Überprüfen Sie den consent-Objektbereich
writeOnLocalStorage Nein Boolean Definiert, ob die Daten direkt gesendet oder in localStorage geschrieben werden sollen. Voreinstellung: true
autodetect_ip_address Nein Boolean Ein Parameter, der die IP-Autoerkennung aktiviert oder deaktiviert. Voreinstellung: true

Der Code im obigen Beispiel erfasst automatisch das consent-Objekt mit den Werten der gebundenen Eingabefelder:

  • wenn das submitElement ein Klick-Event erhält (falls submitElement angegeben wurde); oder
  • wenn die _iub.cons.sendData()-Funktion manuell aufgerufen wird (siehe unten)

3.1.1 sendData

The sendData-Funktion muss in Verbindung mit der load-Funktion verwendet werden und stößt die Aufzeichnung des consent-Objekts mit den Werten der Eingabefelder an, die durch einen vorherigen Aufruf der load-Funktion gebunden wurden.

Es muss verwendet werden, wenn das submitElement nicht vorhanden ist (z.B. wenn Sie das Eingabeformular vor dem Absenden validieren müssen) und Sie programmgesteuert den Abruf der Daten aus dem Formular und die anschließende Aufzeichnung der Einwilligung auslösen müssen.

// your form handler function
function validateForm() {
    if (isValidForm()) {
        // the form has been validated
  	_iub.cons.sendData();
  	// ...
     }
}

3.1.2 sendFromLocalStorage

Das von der load-Funktion erzeugte consent-Objekt wird grundsätzlich nicht direkt an unsere Server zur Speicherung gesendet; es wird vielmehr im localStorage gespeichert, um vor Datenverlust zu schützen, falls eine neue Seite geladen wird, bevor die Ausführung des JavaScript abgeschlossen ist. Die imlocalStorage gespeicherte Einwilligung wird automatisch beim nächsten Seitenaufruf aufgezeichnet (d.h. zur Speicherung an unsere Server gesendet).

Wenn Sie das automatische Senden der in localStorage gespeicherten Einwilligung beim Seitenaufruf deaktivieren möchten, müssen Sie in der Konfiguration des Init-Objekts den Parameter sendFromLocalStorageAtLoad = false angeben. In solchen Fällen müssen Sie, um die in localStorage gespeicherte Einwilligung an unsere Server zu senden, explizit die Funktion_iub.cons.sendFromLocalStorage aufrufen (siehe unten).

_iub.cons.sendFromLocalStorage()

3.2 submit

Mit der submit -Funktion können Sie die Einwilligungsdaten programmatisch (z.B. innerhalb eines Event-Handlers oder einer Rückruffunktion) an die iubenda-APIs senden, d.h. die Einwilligung aufzeichnen:

// An example of .submit scenario: inside the init callback function
$("#submit-btn").click(function(e) {
    e.preventDefault();
    // Synchronous call, it's sent immediately when this function is executed
    _iub.cons_instructions.push(["submit", {... your configuration object(see the examples below)},
      {
        success: function(response) {
          console.log(response);
        }, 
        error: function(response) {
          console.log(response);
        }
      }
    ])
 });

Es kann auf zwei Arten konfiguriert werden:

  • Durch Festlegung des selector-Parameters auf die gleiche Weise wie die load-Funktion
  • Durch Angabe aller Werte des consent-Objekts

Bemerkenswert ist, dass die submit-Funktion im Gegensatz zur load-Funktion standardmäßig nicht den localStorage nutzt und stattdessen das consent-Objekt direkt an unseren Server zur Speicherung sendet.

Parameter:

Name Erforderlich Typ Notizen
form Nein/Ja, wenn consent nicht definiert ist FormConfig (Siehe den form-Objektbereich unten)
consent Nein/Ja, wenn form nicht definiert ist ConsentConfig (Siehe den consent-Objektbereich unten)
writeOnLocalStorage Nein Boolean Definiert, ob die Daten direkt gesendet oder in localStorage geschrieben werden sollen. Voreinstellung: false
autodetect_ip_address Nein Boolean Hiermit können Sie die IP-Autoerkennung aktivieren oder deaktivieren. Voreinstellung: true
Wichtig

In den Fällen, in denen Sie sowohl das Formular als auch die Einwilligungsparameter angeben, werden diese zusammengeführt, um das consent-Objekt zu erstellen. In Fällen, in denen es einen Konflikt zwischen den aus dem Formular abgerufenen Daten und den direkt im consent-Objekt angegebenen Daten gibt, hat das consent-Objekt Vorrang.

Rückrufe

Die .success-Rückruf-Funktion wird bei Erfolg aufgerufen, die.error-Rückruf-Funktion wird bei Fehlern aufgerufen.

3.2.1 Wenn das Formularobjekt angegeben wird

Im Beispiel unten (wo das form-Objekt angegeben ist), kümmert sich die submit-Funktion darum, das consent-Objekt aus den Formulareingaben zu füllen.

_iub.cons_instructions.push(["submit",
{
    form: {"... your form object"},
    consent: {
      legal_notices: [{
        identifier: "term",
        version: "1"
      }]
    }
},
{
    success: function(response) {
      console.log(response);
    },
    error: function(response) {
      console.log(response);
    }
}
])

3.2.2 Wenn das Formularobjekt nicht angegeben wird

Alternativ können Sie das consent-Objekt auch wie im folgenden Beispiel gezeigt weitergeben:

_iub.cons_instructions.push(["submit",
  {
    consent: {
      subject: {
        id: "your-subject-id",
        email: "your-subject-email0@example.com"
      },
      preferences: {
        term: true
      },
      legal_notices: [
        {
          identifier: "privacy_policy"
        }
      ],
      proofs: [
        {
          content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
          form: "<form action=\"/action\" method=\"POST\"><p><label>First Name</label><input type=\"text\" name=\"first_name\" /></p><p><label>Last name</label><input type=\"text\" name=\"last_name\" /></p><p><label>E-mail</label><input type=\"email\" name=\"email\" /></p><input type=\"submit\" /></form>"
        }
      ]
    }
  },
  {
    success: function(response) {
      console.log(response);
    },
    error: function(response) {
      console.log(response);
    }
  }
])

Dies ist ein Beispiel für eine Antwort (in diesem Fall eine Erfolgsantwort) vom Server:

200 OK
{
    id: "de801ca9-abec-45e2-8f7c-729822cfffad",
    timestamp: "2018-05-04T14:52:26Z",
    subject_id: "J02eZvKYlo2ClwuJ1"
}

4. Programmatisch Ihr Einwilligungsobjekt erstellen und aufzeichnen

Wenn Sie Ihr consent-Objekt programmatisch erstellen und an die API der Consent Solution senden möchten, müssen Sie die submit-Funktion verwenden, wie zuvor in 3.2.2 beschrieben: “Wenn das Formularobjekt nicht angegeben wird”.

5. FormConfig

Dies ist die Struktur des form-Objekts, das an load– und submit-Funktionen weitergegeben wird:

Name Typ Notizen
selector String oder DOM-Element Die ID (String ) des Formulars oder des Formulars des DOM-Elements
map Object Objekt, das die Zuordnung von consent-Attributen zu bestimmten Formularfeldern anhand ihrer “Name”-Attribute als Alternative zu data-cons-x-Attributen erlaubt (siehe Beispiel unten)
subject Object
id String Name-Attribut eines im Formular vorhandenen DOM-Elements
email String Name-Attribut eines im Formular vorhandenen DOM-Elements
first_name String Name-Attribut eines im Formular vorhandenen DOM-Elements
last_name String Name-Attribut eines im Formular vorhandenen DOM-Elements
full_name String Name-Attribut eines im Formular vorhandenen DOM-Elements
preferences Object
preference_name String Name-Attribut eines im Formular vorhandenen DOM-Elements
exclude Array Eine Liste der Felder, die wir von den Einwilligungsnachweisen ausschließen möchten

5.1 Bindung der Formularfelder an Ihr Einwilligungsobjekt

Die Formularfelder können auf zwei Arten an Ihr consent-Objekt gebunden werden:

1) Durch Angabe des entsprechenden name-Attributs im MAP-Objekt (bitte beachten Sie, dass id hier nicht verwendet werden kann, sondern nur das name-Attribut):

form: {
    selector: "form-id", // The string (ID) or the DOM element of the form from which you'd like to detect the data
    map: { // optional: map consent attributes directly to the corresponding
        // input's "name" attribute, instead of using data-cons-x attributes
        subject: {
            id: "id-element-name"
            email: "email-element-name",
            first_name: "first-name-element-name",
            last_name: "last-name-element-name",
            full_name: "full-name-element-name"
        },
        preferences: {
            term: "terms-checkbox-element-name"
        }
    }
}

2) Durch die Verwendung von data-cons-x-Attributen in Ihrem Eingabefeld:

<form id="form-id">
    <!-- subject -->
    <input type="..." name="subject_name" data-cons-subject-name />

    <input type="hidden" name="id" value="12141412" *data-cons-subject="id" * />
    <p>
        First name:<br />
        <input type="text" value="value" name="first_name" *data-cons-subject="first_name" * />
    </p>
    <p>
        Last name:<br />
        <input type="text" name="last_name" *data-cons-subject="last_name" * />
    </p>
    <p>
        Full Name:<br />
        <input type="text" name="full_name" *data-cons-subject="full_name" * />
    </p>
    <p>
        Email<br />
        <input type="text" name="email" *data-cons-subject="email" * />
    </p>
    <p>
        Password<br />
        <input type="password" name="password" *data-cons-exclude* />
    </p>

    <!-- preferences -->
    <p>
        <label><input type="hidden" name="terms-and-conditions" data-cons-preference="terms-and-conditions" value="value" />
            Accept terms and conditions</label>
    </p>
    <p>
        <label><input type="hidden" name="newsletter" value="newsletter" data-cons-preference="newsletter" /> newsletter</label>
    </p>
    <input type="submit" id="submit-btn" />
</form>

Sie können auch bestimmte Felder (d.h. Passwort oder Felder, die nicht mit der Einwilligung zusammenhängen) auf zwei Weisen ausschließen:

1) Durch die Verwendung von data-cons-exclude in Ihrem Eingabefeld:

<input type="password" name="password" data-cons-exclude />

2) Durch Verwendung des exclude-Objekts innerhalb des Mapcodes:

map: {
    .
    .
    // exclude fields by inserting inputs names in this array
    exclude: ['password']
}

6. ConsentConfig

Das consent-Objekt setzt sich aus den folgenden Feldern zusammen:

Name Erforderlich Typ Notizen
subject Ja Object
id Nein String Kennung zur Identifizierung des Betroffenen, der die Einwilligung gesendet hat. Wenn eine ID weitergegeben wird, wird sie verwendet, und Sie können eine Information aktualisieren, indem Sie neue Einwilligungen mit demselben Betroffenen-ID veröffentlichen. Wenn Sie jedoch keinen spezifische Betroffenen-ID angeben, wird die API eine sichere Zufalls-UUID für Sie erstellen.
email Nein String
first_name Nein String
last_name Nein String
full_name Nein String
verified Nein Boolean Reserviertes Feld, das verwendet wird, um zu signalisieren, ob ein Betroffener verifiziert ist, zum Beispiel durch die Double-Opt-In-Methode
legal_notices Ja Array Gruppe von Objekten, die legal_notices Daten enthalten
identifier Nein String
version Nein String Automatisch ausgefüllt, falls nicht vorhanden
proofs Ja Array Reihe von Objekten, die Daten zu Einwilligungsnachweisen enthalten
content Nein String
form Nein String
preferences Ja Object Eine Reihe von Schlüssel-Werte-Paaren mit Präferenzen des Nutzers für die Einwilligungshandlung.

Wichtig: In der JS-Bibliothek müssen alle Eigenschaften innerhalb desconsent-Objekts angegeben werden. Beispiel:

consent: {
  subject: {
    id: "your-subject-id",
    email: "your-subject-email0@example.com"
  },
  preferences: {
    term: true
  },
  legal_notices: [
    {
      identifier: "privacy_policy"
    }
   ]},
   proofs: [
    {
      content: "{ \"first_name\": \"John\", \"last_name\": \"Doe\", \"email\": \"john@example.com\" }"
      form: "<form action=\"/action\" method=\"POST\"><p><label>First Name</label><input type=\"text\" name=\"first_name\" /></p><p><label>Last name</label><input type=\"text\" name=\"last_name\" /></p><p><label>E-mail</label><input type=\"email\" name=\"email\" /></p><input type=\"submit\" /></form>"
    }
   ]
}

7. Rechtliche Hinweise

Wenn Sie iubenda für Ihre juristischen Dokumente verwenden, werden wir den Inhalt der legal_notices automatisch für Sie aktualisieren, sobald Ihre juristischen Dokumente geändert werden. Wie Sie diese Funktion aktivieren, können Sie hier nachlesen.

Sie müssen jedoch nach wie vor angeben, welche legal_notices bei jeder Erstellung einer Einwilligung vereinbart werden. Wenn Sie also legal_notices verwenden, sollten Sie das Feld legal_notices mit der Identifizierung und der Version Ihrer zuvor erstellten rechtlichen Hinweise ausfüllen.

Beispiel:

consent: {
  legal_notices: [
    {
      identifier: "privacy_policy",
      version: "1" // auto-filled if not provided
    },
    {
      identifier: "another_legal_notice"
    },
    ...
  ]
}

8. Implementierungsbeispiele

Nachstehend finden Sie einige praktische Beispiele dafür, wie Sie die Consent Solution tatsächlich umsetzen können.

8.1 MAP -Funktion

Load-Funktion

See the Pen [Iubenda Cons] (async) Load function by iubenda (@iubenda) on CodePen.

Funktion mit Mapcode laden (kein Daten-Attribut)

See the Pen [Iubenda Cons] (async) Load function and Map option by iubenda (@iubenda) on CodePen.

8.2 Implementierung eingeben (asynchron)

See the Pen [Iubenda Cons] (async) Submit implementation by iubenda (@iubenda) on CodePen.

8.3 Implementierung mehrerer Formulare

See the Pen [Iubenda Cons] (async)Multiple Form implementation by iubenda (@iubenda) on CodePen.

8.4 Externe Gültigkeitsprüfungstools (Funktion mit validate.js laden)

See the Pen [Iubenda Cons] (async) load function with validate.js by iubenda (@iubenda) on CodePen.

Wie man ConS-Installationen aus der Zeit vor dem 03.04.2019 aktualisiert

Falls Sie die iubenda Consent Solution vor dem 03.04.2019 installiert haben, um die aktuelle Version zu verwenden, aktualisieren Sie die Verwendung der init und load-Funktionen, um die neue Funktion des asynchronen Ladens zu ermöglichen.

Die init– oder load-Funktionen können in zwei verschiedenen Situationen aufgerufen werden:

  • Bevor die Bibliothek das Laden abgeschlossen hat (asynchrones Laden)
  • Nachdem die Bibliothek das Laden beendet hat (synchrones Laden)

Load

Vorher:

_iub.cons.load({ ... your options })

Nachher:

_iub.cons_instructions.push(["load", { ... your options }])

Wichtig: Dieser Code muss hinter Ihrem Element stehen, siehe den obigen Abschnitt zum Thema Laden.

Init

Vorher:

_iub.cons.init({api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION);

Nachher:

_iub.cons_instructions.push(["init", {api_key: "YOUR_PUBLIC_API_KEY"}, YOUR_CALLBACK_FUNCTION]);

Wichtig: Die init -Funktion ist in Ihr Installationsskript eingebettet und sollte von Ihnen nicht aktualisiert werden müssen.

Siehe auch