Title	Implementare il punto di raccolta con API REST

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

Content

Lo scopo principale dell'SDK JavaScript è quello di fornire un mezzo rapido per implementare i punti di raccolta OneTrust. L'SDK utilizza un'architettura API Open RESTful per comunicare con i sistemi OneTrust.

Un'alternativa all'implementazione dell'SDK consiste nello scrivere un codice che consenta di interagire direttamente con le proprie API. In questo modo è possibile creare flussi di lavoro personalizzati e utilizzare il servizio in applicazioni che non supportano JavaScript.

Nota

Per ulteriori informazioni sugli endpoint e le chiamate API di OneTrust, visitare il Portale per sviluppatori OneTrust.

Utilizzare l'API Ricevute di consenso per creare transazioni

L'API Ricevute di consenso consente a un'applicazione esterna di inviare una richiesta per memorizzare le transazioni di consenso per i singoli punti di raccolta. Per generare un token di richiesta valido, è necessario innanzitutto configurare ciascun punto di raccolta in OneTrust.

Corpo della richiesta API Ricevute di consenso

Di seguito sono riportati i dati di payload supportati quando si effettuano chiamate POST su 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}"
      ]
    }
  ]
  }
  ]
}

Dati di payload	Descrizione
identificatore	Valore richiesto per l'identificatore DS. Il tipo si basa sul tipo di elemento di dati Punto di raccolta e non viene convalidato al momento dell'inoltro.
identifierType	Supportato solo nei punti di raccolta di tipo API impostati per la configurazione dinamica. Questo valore è obbligatorio per i punti di raccolta con configurazione dinamica. Il valore (ad es. "E-mail") deve corrispondere a uno degli elementi di dati dell'identificatore definiti nell'elenco degli elementi di dati. Nota Tali dati devono essere inviati solo per i punti di raccolta con configurazione dinamica.
dsDataElements (facoltativo)	Facoltativo per l'acquisizione dei valori degli elementi di dati dal punto di raccolta. Gli elementi di dati devono essere definiti nel punto di raccolta, altrimenti verranno ignorati.
lingua (facoltativo)	Consente di impostare la lingua dell'interessato. Supporta i formati del codice ISO. Verrà accettato soltanto il codice di lingua o di lingua-impostazioni cultura.
interactionDate (facoltativo)	Supportato solo nei punti di raccolta di tipo API. Consente di registrare la data e l'ora dell'interazione dell'utente con un punto di raccolta. Se utilizzato in combinazione con un TransactionType dichiarato, è possibile pubblicare più tipi di TransactionType diversi e ogni transazione verrà registrata come se fosse avvenuta nella data di interazione. Quando si utilizza interactionDate, non devono essere incluse altre date nel post. Se interactionDate e una delle altre date vengono inviate nello stesso post, verrà generato un errore. Le ricevute possono essere pubblicate non in ordine di data utilizzando la data di interazione nell'API Ricevute di consenso, il che può risultare particolarmente utile quando si invia lo storico dei consensi. Ciò significa che le nuove ricevute in entrata, con una data di interazione precedente all'ultima data registrata in ogni profilo specifico dell'interessato, creeranno una transazione ma non aggiorneranno lo stato della finalità. Ad esempio, se si pubblica una ricevuta WITHDRAWN la cui data di interazione è il 3 maggio, seguita da una ricevuta NOT_GIVEN per la stessa finalità ma con una data di interazione antecedente al 2 maggio, il profilo dell'interessato mostrerà lo stato WITHDRAWN per tale finalità sulla base della data di interazione più recente. Nota Si consiglia di utilizzare interactionDate al posto di consentDate e withdrawnDate.
customPayload (facoltativo)	Memorizza tutti i dati personalizzati in coppie di valori chiave nella ricevuta. La dimensione totale dei dati customPayload non deve superare i 4000 caratteri.
requestInformation	Token generato dal punto di raccolta. Non può essere modificato.
Finalità	Elenco delle finalità per le quali viene fornito o modificato il consenso.
ID finalità	Valore obbligatorio. Includere solo i GUID per le finalità a cui viene fornito il consenso a meno che non si utilizzi il tipo di transazione. Imposterà lo stato del consenso su ACTIVE o PENDING, a seconda dell'impostazione Doppio opt-in del punto di raccolta.
TransactionType (facoltativo)	Supportato solo nei punti di raccolta di tipo API. Valori supportati: PENDING, CONFIRMED, WITHDRAWN, EXPIRED, NOTGIVEN, EXTEND, OPT_OUT, HARD_OPT_OUT, NO_CHOICE, CHANGE_PREFERENCES, CANCEL. I valori accettabili possono essere determinati anche da altre impostazioni nel punto di raccolta. Ad esempio, il valore PENDING sarà accettato solo se il punto di raccolta prevede il doppio opt-in. NO_CHOICE è attualmente disponibile solo per i punti di raccolta di tipo Conformità cookie.
ExpiryDate (facoltativo)	Data di scadenza esplicita facoltativa. Se viene inserito un valore, questo valore sostituirà la durata del consenso per la finalità in questione. La data deve essere impostata nel futuro rispetto alla data e all'ora correnti. Una volta raggiunta la data di scadenza, viene eseguita un'attività pianificata per aggiornare lo stato del consenso a Scaduto. Nota È possibile che, dal momento in cui viene raggiunta la data di scadenza, trascorrano fino a 12 ore prima che lo stato risulti Scaduto nel profilo dell'interessato.
purposeNote	Dato facoltativo che può includere i valori noteId, noteType, noteLanguage e noteText.
noteId (facoltativo)	UUID di un template di motivo. Questo ID deve essere valido o verrà ignorato. Utilizzare questo ID solo se si desidera collegare la nota a un template di motivo.
noteType (facoltativo)	Tipo del template di motivo. Se utilizzato, il valore deve essere UNSUBSCRIBE_REASON.
noteLanguage (facoltativo)	Codice ISO della lingua del testo della nota.
noteText (facoltativo)	Il testo della nota memorizzato deve contenere al massimo 500 caratteri. Se si include purposeNote nel payload, è necessario specificare questo valore.
CustomPreferences (facoltativo)	Valore facoltativo basato sulle preferenze personalizzate collegate alla finalità.
Opzioni	Le preferenze personalizzate possono essere a selezione singola o multipla, facoltative o obbligatorie, ma non vengono convalidate dall'API. L'impostazione di più valori sulla selezione singola verrà accettata, ma potrebbe causare problemi quando l'interessato accede a un centro preferenze che include questi dati. Includere solo i GUID delle opzioni per le quali si deve fornire il consenso.
[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. Nota [en] This flag requires an API type collection point.

Risposta

L'API restituirà la seguente risposta:

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

Risposta	Descrizione
consentReceipt	Un JWT che contiene il record della transazione.
[en] instantLinkToken	[en] This token can be appended to the Preference Center login URL for a data subject login.

Modificare le preferenze tramite l'API Ricevute di consenso

È possibile passare l'API Ricevute di consenso con il tipo di transazione CHANGE_PREFERENCES per modificare le selezioni delle opzioni Argomento e Preferenza personalizzata per gli interessati esistenti. Questo tipo di transazione consente all'interessato di scegliere o rifiutare in modo esplicito le singole opzioni di preferenza senza dover includere tutte le scelte esistenti nel payload.

Cose da sapere

Quando si passa il tipo di transazione CHANGE_PREFERENCES, occorre tenere presenti le seguenti considerazioni:

Il tipo di transazione CHANGE_PREFERENCES è disponibile solo per i punti di raccolta di tipo API.
Esistono differenze significative nel payload delle preferenze personalizzate quando si passa questo tipo di transazione: è quindi importante prestare la massima attenzione quando si implementa questa opzione.
È possibile dichiarare OPT_IN come parametro TransactionType o lasciarlo vuoto per consentire all'interessato di scegliere un'opzione Argomento o Preferenza personalizzata.
Non includere gli ID degli elementi che non si desidera modificare.
Se non esiste un record di consenso per l'interessato (ad es., il tipo di transazione CHANGE_PREFERENCES è la prima transazione effettuata dall'interessato per queste finalità), il record di consenso verrà creato con lo stato ACTIVE e saranno applicate le preferenze.
[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.

Esempio di 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}

Ignorare il flusso di lavoro con doppio opt-in

È possibile ignorare il flusso di lavoro con doppio opt-in per una singola interazione dell'interessato passando il seguente parametro nell'API Ricevute di consenso:

“doubleOptIn”: false

Quando viene effettuata una chiamata POST con il parametro aggiuntivo, viene generato un tipo di transazione CONFIRMED anziché PENDING. All'interessato verrà quindi attribuito uno stato ACTIVE per tutte le finalità nel punto di raccolta.

Nota

Non verranno attivati gli eventi di e-mail di conferma con doppio opt-in o flusso di lavoro personalizzato se l'identificatore non è un indirizzo e-mail.

Attachment

Article Total View Count 17,996

Language	Italian

Is Primary Language

Implementare il punto di raccolta con API REST

Nota

Utilizzare l'API Ricevute di consenso per creare transazioni

Corpo della richiesta API Ricevute di consenso

Nota

Nota

Nota

Nota

Risposta

Modificare le preferenze tramite l'API Ricevute di consenso

Cose da sapere

Esempio di payload

Ignorare il flusso di lavoro con doppio opt-in

Nota