Title	Implementieren des Erfassungspunkts mit REST-API

URL Name	UUID-b039d8c3-091a-a89b-ce4e-e26e68fcffa1

Content

Der Hauptzweck des JavaScript-SDK besteht darin, eine schnelle Methode für die Implementierung von OneTrust Erfassungspunkten bereitzustellen. Das SDK nutzt eine offene RESTful API-Architektur für die Kommunikation mit den Systemen von OneTrust.

Eine Alternative zur Implementierung des SDK besteht darin, Ihren eigenen Code zu schreiben, um direkt mit unseren APIs zu interagieren. Auf diese Weise können Sie eigene benutzerdefinierte Arbeitsabläufe erstellen und den Service in Anwendungen verwenden, in denen JavaScript nicht unterstützt wird.

Anmerkung

Weitere Informationen über die API-Endpunkte und -Aufrufe von OneTrust finden Sie im OneTrust Entwicklerportal.

Verwenden der Einwilligungsbestätigungs-API zum Erstellen von Einwilligungsvorgängen

Die Einwilligungsbestätigungs-API ermöglicht es einer externen Anwendung, eine Anfrage zur Speicherung von Einwilligungsvorgängen für einzelne Erfassungspunkte zu stellen. Jeder Erfassungspunkt muss zuerst in OneTrust eingerichtet werden, um ein gültiges Anfragetoken zu generieren.

Anfragetext für Einwilligungsbestätigungs-API

Im Folgenden finden Sie die unterstützten Payloads bei POST-Aufrufen auf https://{BASEURL}/request/v1/consentreceipts.

{
  "identifier": "mail@mail.com",
  "identifierType": "Email",
  "generateInstantLinkToken", "true"         
  "dsDataElements":{                        
    "DataElement1Name": "Value",
    "DataElement2Name": "Value"
  },
  "language": "en-GB", 
  "interactionDate": "2019-05-14T01:34:33Z",                      
  "consentDate": "2019-05-14T01:34:33Z",
  "withdrawnDate" : "2018-03-01T09:00:00",  
  "customPayload":{                         
    "key1": "value1",
    "key2": "value2"
  },
  "requestInformation": "{JWT TOKEN}",      
  "purposes": [
  {
    "Id": "{GUID}",                        
    "TransactionType": "OPT_OUT",
    "ExpiryDate": "2020-01-01",
    "purposeNote": {  
        "noteId": "aa978afe-bbe9-4419-8fa9-f3691f1046c3",
        "noteType": "UNSUBSCRIBE_REASON", 
        "noteLanguage": "en-us",
        "noteText": "Reason 1",
                      }
    "CustomPreferences": [               
    {
      "Id": "{GUID}",
      "Options": [                      
      "{GUID}",                         
      "{GUID}"
      ]
    }
    ]
  },
  {
    "Id": "{GUID}",
    "CustomPreferences": [
    {
      "Id": "{GUID}",
      "Options": [
      "{GUID}",
      "{GUID}",
      "{GUID}"
      ]
    }
  ]
  }
  ]
}

Payload-Daten	Beschreibung
identifier	Erforderlicher Wert für die DS-ID. Der Typ basiert auf dem Datenelementtyp des Erfassungspunkts und wird beim Übermitteln nicht validiert.
identifierType	Wird nur auf API-Erfassungspunkten unterstützt, die für die dynamische Konfiguration eingerichtet sind. Dieser Wert ist für Erfassungspunkte mit dynamischer Konfiguration erforderlich. Der Wert (z. B. „Email“) muss mit einem der in der Datenelementliste definierten Bezeichner-Datenelemente übereinstimmen. Anmerkung Diese Daten sollten nur für Erfassungspunkte mit dynamischer Konfiguration gesendet werden.
dsDataElements (Optional)	Optional für die Erfassung von Datenelementwerten aus dem Erfassungspunkt. Datenelemente müssen auf dem Erfassungspunkt definiert werden, andernfalls werden sie ignoriert.
language (Optional)	Dient zum Festlegen der Sprache für die betroffene Person. Unterstützt ISO-Codeformate. Zulässige Optionen sind Nur-Sprache oder Sprachkulturcode.
interactionDate (Optional)	Wird nur bei Erfassungspunkten des API-Typs unterstützt. Dient zur Aufzeichnung von Datum und Uhrzeit der Benutzerinteraktion mit einem Erfassungspunkt. Bei Verwendung in Kombination mit einem deklarierten TransactionType können mehrere verschiedene TransactionTypes veröffentlicht werden und jeder Einwilligungsvorgang wird als am interactionDate erfolgt erfasst. Bei der Verwendung von interactionDate dürfen keine anderen Daten in die Veröffentlichung aufgenommen werden. Wenn interactionDate und eines der anderen Termine in derselben Veröffentlichung gesendet werden, wird ein Fehler ausgelöst. Bestätigungen können mit dem Interaktionsdatum in der Einwilligungsbestätigungs-API veröffentlicht werden, was besonders nützlich sein kann, wenn ältere Einwilligungsdaten gesendet werden. Das bedeutet, dass neu eingehende Bestätigungen mit einem früheren Interaktionsdatum als dem letzten Datum, das für das jeweilige Profil der betroffenen Person aufgezeichnet wurde, zwar einen Einwilligungsvorgang erzeugen, aber den Zweckstatus nicht aktualisieren. Wenn Sie beispielsweise eine WITHDRAWN-Bestätigung mit dem Interaktionsdatum 3. Mai gefolgt von einer NOT_GIVEN-Bestätigung für denselben Zweck mit einem früheren Interaktionsdatum 2. Mai veröffentlichen, würde das Profil der betroffenen Person basierend auf dem letzten Interaktionsdatum den Zweckstatus WITHDRAWN anzeigen. Anmerkung Es wird empfohlen, interactionDate anstelle von ConsentDate und WithdrawnDate zu verwenden.
customPayload (Optional)	Speichert alle benutzerdefinierten Daten in Schlüsselwertpaaren für die Bestätigung. Die Gesamtgröße der customPayload-Daten darf 4000 Zeichen nicht überschreiten.
requestInformation	Vom Erfassungspunkt generiertes Token. Muss ohne Änderung verwendet werden.
Zwecke	Die Liste der Zwecke, für die die Einwilligung erteilt oder geändert wird.
Zweck-ID	Erforderlicher Wert. Nehmen Sie nur die GUIDs für Zwecke auf, denen zugestimmt wird, es sei denn, Sie verwenden den Einwilligungsvorgangstyp. Setzt den Einwilligungsstatus auf ACTIVE oder PENDING, je nach Einstellung für Double Opt-in am Erfassungspunkt.
TransactionType (Optional)	Wird nur bei Erfassungspunkten des API-Typs unterstützt. Unterstützte Werte: PENDING, CONFIRMED, WITHDRAWN, EXPIRED, NOTGIVEN, EXTEND, OPT_OUT, HARD_OPT_OUT, NO_CHOICE, CHANGE_PREFERENCES, CANCEL. Akzeptable Werte können auch durch andere Einstellungen am Erfassungspunkt bestimmt werden. PENDING wird beispielsweise nur akzeptiert, wenn der Erfassungspunkt für Double Opt-in festgelegt ist. NO_CHOICE ist derzeit nur für Erfassungspunkte des Typs Cookie-Compliance verfügbar.
ExpiryDate (Optional)	Optionales explizites Ablaufdatum. Wenn ein Wert eingegeben wird, überschreibt dieser die Dauer der Einwilligung in Bezug auf den Zweck. Das Datum sollte in Bezug auf das aktuelle Datum und die aktuelle Uhrzeit in der Zukunft liegen. Nach Erreichen des Ablaufdatums wird eine geplante Aufgabe ausgeführt, um den Einwilligungsstatus auf „Abgelaufen“ zu aktualisieren. Anmerkung Es kann zu einer Verzögerung von bis zu 12 Stunden nach Erreichen des Ablaufdatums kommen, bis der Status „Abgelaufen“ im Profil der betroffenen Person angezeigt wird.
purposeNote	Optionale Daten, die noteId, noteType, noteLanguage und noteText enthalten können.
noteId (Optional)	UUID einer Begründungsvorlage. Diese ID muss gültig sein, andernfalls wird sie ignoriert. Verwenden Sie diese ID nur, wenn Sie den Hinweis mit einer Begründungsvorlage verknüpfen möchten.
noteType (Optional)	Typ der Begründungsvorlage. Bei Verwendung muss der Wert UNSUBSCRIBE_REASON lauten.
noteLanguage (Optional)	ISO-Code für die Sprache des Hinweistextes.
noteText (Optional)	Hinweistext mit maximal 500 Zeichen, der gespeichert werden soll. Wenn Sie „purposeNote“ in Ihre Payload einschließen, muss dieser Wert vorhanden sein.
CustomPreferences (Optional)	Optionaler Wert basierend auf benutzerdefinierten Präferenzen, die mit dem Zweck verknüpft sind.
Optionen	Benutzerdefinierte Präferenzen können als Einzel- oder Mehrfachauswahl festgelegt, optional oder erforderlich sein, dies wird von der API jedoch nicht geprüft. Das Festlegen von mehr als einem Wert für die Einzelauswahl wird akzeptiert, kann jedoch zu Problemen führen, wenn sich die betroffene Person bei einem Präferenz-Center anmeldet, das diese Daten enthält. Nehmen Sie nur die GUIDs für Optionen auf, für die eine Einwilligung erfolgen soll.
[en] generateInstantLinkToken [en] (Optional)	[en] Flag to generate an instant access magic link token for the Preference Center that expires after one year, with a default value of false. Anmerkung [en] This flag requires an API type collection point.

Antwort

Die folgende Antwort wird von der API zurückgegeben:

{"instantLinkToken": "{JWT TOKEN}","receipt": "{JWT TOKEN}"
}

Antwort	Beschreibung
consentReceipt	Ein JWT, das den Datensatz des Einwilligungsvorgangs enthält.
[en] instantLinkToken	[en] This token can be appended to the Preference Center login URL for a data subject login.

Ändern von Einstellungen über die Einwilligungsbestätigung-API

Sie können die API für Einwilligungsbestätigungen mit dem Einwilligungsvorgangstyp CHANGE_PREFERENCES übergeben, um die Auswahl vorhandener Optionen für Thema und benutzerdefinierte Präferenzen für vorhandene betroffene Personen zu ändern. Mit diesem Einwilligungsvorgangstyp können Sie ein betroffene Person explizit für einzelne Präferenzoptionen an- oder abmelden, ohne alle vorhandenen Auswahlmöglichkeiten in die Payload einschließen zu müssen.

Was Sie wissen sollten

Bei der Übergabe des Einwilligungsvorgangstyps CHANGE_PREFERENCES sind folgende wichtige Hinweise zu beachten:

Der Einwilligungsvorgangstyp CHANGE_PREFERENCES ist nur für Erfassungspunkte des API-Typs verfügbar.
Es gibt erhebliche Unterschiede in der Payload der benutzerdefinierten Präferenz bei der Übergabe dieses Transaktionstyps, daher ist bei der Implementierung Vorsicht geboten.
Sie können entweder OPT_IN als TransactionType-Parameter deklarieren oder das Feld leer lassen, um eine betroffene Person für ein Thema oder eine benutzerdefinierte Präferenzoption anzumelden.
Geben Sie die IDs für Elemente, die Sie nicht ändern, nicht an.
Wenn für die betroffene Person noch kein Datensatz für die Einwilligung existiert (d. h. der Einwilligungsvorgangstyp CHANGE_PREFERENCES der erste Einwilligungsvorgang für die betroffene Person für diese Zwecke ist), wird der Datensatz für die Einwilligung mit dem Status ACTIVE erstellt, und die Präferenzen werden angewendet.
[en] The CHANGE_PREFERENCES transactionType should only be used to modify preferences for an existing data subject with a purpose in Active status, or to create a new data subject record.

Beispiel-Payload

{
2  "identifier": "changepref@otprivacy.com",
3  "requestInformation": "{JWT}",
4  "purposes": [
5    {
6      "Id": "6ede4731-b0d3-44f9-8eca-0b82d211e084",
7      "TransactionType":"CHANGE_PREFERENCES",
8      "CustomPreferences": [
9        {
10          "Id": "a3f54f53-0747-4d98-b428-0b2316162122",
11          "Choices": [
12              {
13            "OptionId":"614bafbc-60e0-46c7-9f0f-411fcd83cbc3",
14            "TransactionType":"OPT_OUT"
15              },
16              {
17            "OptionId":"4c8bdec4-552d-4a72-9029-a218124b8c19",
18            "TransactionType":"OPT_OUT"
19              }
20            
21          ]
22        }
23        
24      ]
25    }
26  ]
27}

Umgehen des Arbeitsablaufs mit Double Opt-in

Sie können den Arbeitsablauf mit Double Opt-in für eine Interaktion einzelner Betroffener umgehen, indem Sie den folgenden Parameter in der Einwilligungsbestätigung-API übergeben:

“doubleOptIn”: false

Wenn ein POST-Aufruf mit dem zusätzlichen Parameter erfolgt, wird der Einwilligungsvorgangstyp CONFIRMED und nicht PENDING erzeugt. Die betroffene Person erhält dann am Erfassungspunkt für alle Zwecke den Status ACTIVE.

Anmerkung

Die Bestätigungs-E-Mail für Double Opt-in oder benutzerdefinierte Arbeitsablauf-Ereignisse, bei denen der Bezeichner keine E-Mail-Adresse ist, werden nicht ausgelöst.

Attachment

Article Total View Count 18,322

Language	German

Is Primary Language

Implementieren des Erfassungspunkts mit REST-API

Anmerkung

Verwenden der Einwilligungsbestätigungs-API zum Erstellen von Einwilligungsvorgängen

Anfragetext für Einwilligungsbestätigungs-API

Anmerkung

Anmerkung

Anmerkung

Anmerkung

Antwort

Ändern von Einstellungen über die Einwilligungsbestätigung-API

Was Sie wissen sollten

Beispiel-Payload

Umgehen des Arbeitsablaufs mit Double Opt-in

Anmerkung