Panoramica generale
Lo scopo dell'API è consentire ai clienti di sviluppare la propria interfaccia di consenso nei casi in cui gli SDK forniti da ConsentManager non siano sufficienti. L'API consentirà quindi al cliente di creare la propria interfaccia grafica sulla base delle informazioni fornite dall'API. Inoltre, l'API consentirà al cliente di utilizzare standard di settore come l'IAB TCF o l'IAB GPP senza la necessità di implementare i propri codificatori/decodificatori.
Implementazione
L'implementazione si compone di quattro parti:
-
TV API
Consente di interrogare le informazioni relative al testo, ai colori, ai pulsanti e ai link che devono essere visualizzati nell'interfaccia di consenso.
L'API TV è fornita da consentmanager.
-
Interfaccia
di consenso Visualizza il messaggio di consenso per consentire all'utente finale di effettuare una scelta.
Deve essere creata dallo sviluppatore dell'app.
-
Archiviazione
dei consensi Una volta effettuata una scelta, l'archivio dei consensi memorizzerà tali scelte per utilizzare le informazioni quando necessario.
Questo deve essere creato dallo sviluppatore dell'app.
-
Codice QR / Interfaccia
delle impostazioni personalizzate Se l'utente finale desidera effettuare scelte personalizzate oltre ad accettare o rifiutare, l'app può mostrare uno specifico codice QR che l'utente finale può scansionare con il proprio cellulare. L'utente finale verrà indirizzato a un sito web dove potrà effettuare le proprie scelte. Una volta fatto, le scelte vengono inviate al dispositivo TV utilizzando l'API TV e l'utente finale può continuare a utilizzare l'app.
Questo servizio è fornito da consentmanager.
Limiti
Poiché il cliente implementerà la propria interfaccia, l'API non fornisce tutte le funzionalità rispetto a una normale integrazione web o in app. Tra le altre cose, le seguenti funzionalità non fanno parte dell'API (tra le altre):
|
Impostazioni CMP · Integrazioni (ad es. Adobe, Awin, etracker e così via) · API sulla privacy (DNT, GPC, ADPC, …) · Blocco automatico · Verifica dell'età · Funzionalità di reporting ridotte
|
Impostazioni di design · Dimensioni e posizione della casella · Dimensione e famiglia dei caratteri · Interruttori / Caselle di controllo sul primo livello · Icone per scopi, pulsanti e link · Supporto per WCAG · Logica di comportamento ed effetti |
Nota: le impostazioni sopra menzionate non vengono inviate tramite l'API, ma possono essere implementate manualmente dallo sviluppatore dell'app.
Nessuna limitazione sulle impostazioni
Oltre alle limitazioni sopra menzionate, ci sono ancora molte funzionalità che fanno parte dell'API (quando completamente implementata nella tua app) e che possono essere utilizzate come di consueto. Tra le altre, queste sono:
- Allineamento automatico dei testi alla lingua dell'utente
- Visualizzazione del layer di consenso nei colori impostati tramite CMP / Design
- Supporto per IAB TCF, IAB GPP, Google Consent Mode
- Test A/B e apprendimento automatico di diversi design
- Destinazione dei progetti agli utenti finali in base alla lingua, al paese o ad altri attributi
- Segnalazione (limitata) degli utenti, schermate di consenso visualizzate e scelte
Configurazione
Prerequisiti
Per utilizzare l'API devi disporre di un account ConsentManager con la funzione "TV SDK" abilitata (di solito inclusa nei pacchetti superiori). Puoi verificare se la funzione è inclusa accedendo al tuo account e andando su Menu > CMP > TV. Se non vedi la voce di menu "TV", contatta il tuo account manager per effettuare l'upgrade del tuo account.
Abilita l'API TV
Per iniziare a utilizzare l'API dovrai creare un CMP nel tuo account ConsentManager e abilitare l'API TV. Il CMP deve seguire le stesse impostazioni che useresti normalmente per un ambiente web, il che significa che dovrai configurare le impostazioni generali del CMP e aggiungere finalità e fornitori. Una volta fatto, vai su Menu > CMP > TV e attiva l'opzione Abilita API TV.
Una volta abilitata l'API, vedrai l'API-Endpoint sotto il pulsante di attivazione. Copia l'URL dell'Endpoint per utilizzarlo successivamente nella tua implementazione.
Nota: una volta abilitata l'API, ci vorrà fino a 1 ora prima che l'API-Endpoint diventi utilizzabile. Si prega inoltre di notare che le modifiche alle impostazioni CMP o di design si rifletteranno solo su base giornaliera all'interno dell'API TV.
Flusso API
Per implementare l'interfaccia di consenso in un'app, lo sviluppatore dell'app chiamerà l'API TV per ricevere informazioni sulla necessità o meno di mostrare la schermata di consenso a questo specifico utente. L'API conterrà anche informazioni sui colori e sui testi da presentare all'utente finale, nonché sui pulsanti e sui link da visualizzare. Una volta che l'utente finale avrà effettuato una scelta, l'app informerà il sistema Consentmanager tramite l'API TV di tale scelta e riceverà in cambio i dati relativi al consenso (ad es. stringa di consenso IAB TCF, stringa IAB GPP, elenco dei fornitori attivati, elenco delle finalità e così via). L'app può quindi utilizzare questi dati di consenso per determinare le attività di trattamento dei dati o fornirli a terzi (ad es. la stringa di consenso IAB TCF).
Diagramma di flusso dettagliato
Di seguito trovi il diagramma di flusso dettagliato per l'implementazione dell'API TV. I passaggi sono i seguenti:
- Avvio dell'app
- L'app recupera i dati dall'archivio dei consensi (se presente)
- L'app chiama l'endpoint API TV "AppStart" e passa la stringa di consenso esistente
- L'API TV risponde con "displayLayer" impostato su "true" o "false" per indicare se l'interfaccia di consenso deve essere mostrata
- (Se displayLayer = true) L'app visualizza l'interfaccia di consenso utilizzando le informazioni provenienti dall'API TV
- L'utente clicca su Accetta: l'app chiama l'endpoint "Feedback" dell'API TV per
l'accettazione –> L'app memorizza i dati relativi al consenso e prosegue normalmente - L'utente clicca su Rifiuta: l'app chiama l'endpoint "Feedback" dell'API TV per il
rifiuto –> L'app memorizza i dati relativi al consenso e procede normalmente - L'utente clicca su Impostazioni: l'app visualizza il codice QR
- L'app chiama l'endpoint API TV "QR-Status" ogni 3 secondi per l'aggiornamento dello stato
- Una volta che lo stato del QR è "completato" (o l'utente clicca sul pulsante "indietro"), l'app memorizza i dati relativi al consenso e procede normalmente
AppStart Endpoint
L'URL dell'Endpoint AppStart è disponibile nell'area di accesso di ConsentManager (vedi la sezione "Configurazione" sopra). L'Endpoint restituirà un oggetto JSON e fornirà due informazioni:
- Se l'interfaccia di consenso debba essere mostrata
o meno. Ciò è segnalato dalla proprietà “displayLayer” con valore “true” (visualizza l'interfaccia di consenso) o “false” (non è necessario visualizzare l'interfaccia di consenso).
- Quale stile dovrebbe essere utilizzato, nel caso in cui si debba/si voglia mostrare l'interfaccia
di consenso? Ciò è indicato dalle proprietà “display”
Chiamata dell'endpoint AppStart
Quando chiami l'endpoint AppStart, devi utilizzare l'URL che ti è stato fornito nell'area di accesso di ConsentManager. Inoltre, devi estendere l'URL aggiungendo i seguenti parametri:
|
Parametro |
Descrizione |
|
|
(opzionale, consigliato) Lingua desiderata per la visualizzazione. Ad es. &l=DE o &l=EN-US. L'API restituirà i testi in questa lingua. |
|
|
(opzionale, consigliato) Identificatore dell'app. Ad es. &appid=123456 o &appid=my-app-name |
|
|
(opzionale, obbligatorio se presente) La stringa di consenso memorizzata dell'ultima scelta dell'utente. La stringa di consenso viene trasmessa all'app tramite: |
|
|
(facoltativo) Indirizzo IP dell'utente da utilizzare a fini di geolocalizzazione. Se non viene passato alcun IP, viene utilizzato l'IP della fonte della richiesta. Ad es. &ip=123.123.123.123 |
Risposta dell'endpoint AppStart
La risposta dell'API sarà un oggetto codificato in JSON nel seguente formato:
{
"displayLayer": true | false, //Whether to display the consent interface or not
"display":
{
"colors":
{
"background": "#...", //Color for the background of the consent interface
"headline": "#...", //Color for the headline text
"text": "#...", //Color for the normal text
"comment": "#...", //Color for less important texts
"buttonbackground": "#...", //Color for the background of buttons
"buttontext": "#...", //Color for the text in buttons
"accept":
{
"buttonbackground": "#...", //Color for the background of the accept button
"buttontext": "#..." //Color for the text of the accept button
},
"reject":
{
"buttonbackground": "#...", //Color for the background of the reject button
"buttontext": "#..." //Color for the text of the reject button
},
"settings":
{
"buttonbackground": "#...", //Color for the background of the settings button
"buttontext": "#..." //Color for the text of the settings button
},
"save":
{
"buttonbackground": "#...", //Color for the background of the save button
"buttontext": "#..." //Color for the text of the save button
},
"highlight": "#...", //Color for highlighted elements
"link": "#..." //Color for link texts
},
"texts":
{
"headline": "...", //Text for the headline
"text": "...", //Text for the main text
"accept": "...", //Text for the accept button
"reject": "...", //Text for the reject button
"settings": "...", //Text for the settings button
"save": "...", //Text for the save button
"settingsheadline": "...", //Text for the headline in the settings page
"settingstext": "...", //Text for the text in the settings page
"backlink": "..." //Text for the back link in the settings page
},
"layout":
{
"buttons": [...], //Set of strings representing the buttons to be displayed.
//Options: "accept", "reject", "settings", "save" (min. 1, max. 3)
"links": [...] //Set of strings representing the links to be displayed
//Options: "settings", "privacy", "tac", "imprint" (min. 0, max. 4)
}
},
"links":
{
"privacyurl": "https://...", //Link to privacy policy
"tacurl": "https://...", //Link to terms and conditions
"imprinturl": "https://..." //Link to imprint / legal notes
},
"customsettings":
{
"link": "https://...", //Link to a webpage where the end-user can customize their settings
"qrcodeimage": "https://...", //URL of an image (PNG, 196x196 px) of a QR Code
//The QR-Code should be displayed to the end-user to allow customization
"statusurl": "https://..." //QR-Status Endpoint URL to be queried for status updates on the end-user
},
"feedback":
{
"accept": "https://...", //Feedback Endpoint URL for signaling that the user clicked on accept
"reject": "https://..." //Feedback Endpoint URL for signaling that the user clicked on reject
}
}Stile dell'interfaccia di consenso
Soprattutto quando si utilizzano standard di settore come l'IAB TCF o l'IAB GPP, consentmanager è tenuta per politica a garantire che determinati standard siano rispettati dai propri clienti. Dobbiamo quindi richiedere a tutti i clienti di utilizzare le informazioni fornite tramite l'AppStart Endpoint per comporre il design dell'interfaccia di consenso.
Importante: per garantire il rispetto di tutte le regole, richiediamo a tutti i clienti di inviare uno screenshot di esempio dell'interfaccia di consenso che hanno creato per l'approvazione.
Conformità IAB TCF e GPP
Al fine di garantire la conformità a IAB TCF e GPP, dobbiamo richiedere a tutti i clienti di utilizzare gli elementi forniti tramite l'AppStart Endpoint, in particolare:
- L'interfaccia di consenso deve mostrare un titolo e un testo nella prima schermata. Il titolo e il testo devono essere prelevati dall'API e visualizzati per intero. Non possono essere oscurati, abbreviati o resi invisibili in altro modo.
- L'interfaccia di consenso deve visualizzare i pulsanti indicati dall'API e con il testo dell'etichetta fornito dall'API. I pulsanti devono essere immediatamente visibili e non possono essere oscurati.
- L'interfaccia di consenso deve visualizzare i link indicati dall'API. I link devono essere accessibili al cliente ma non è necessario che siano immediatamente visibili. In ogni caso, consigliamo di rendere sempre visibili tutti i link.
- L'interfaccia di consenso deve utilizzare i colori indicati dall'API. Se ciò non fosse possibile a causa delle limitazioni del dispositivo, l'interfaccia di consenso deve essere progettata in modo tale da garantire che tutti i pulsanti abbiano la stessa importanza.
Feedback Endpoint
La risposta dell'AppStart Endpoint conterrà due URL tramite "feedback.accept" e "feedback.reject". Questi URL devono essere richiamati dall'app una volta che l'utente sceglie di accettare o rifiutare le impostazioni sulla privacy.
Chiamata dell'endpoint di feedback
Gli URL degli endpoint di feedback sono già precompilati dalla chiamata API dell'endpoint AppStart e non devono essere modificati o integrati. Si prega di richiamare l'URL corretto corrispondente alla scelta dell'utente.
Feedback Risposta dell'endpoint
La risposta dell'API sarà un oggetto codificato in JSON nel seguente formato:
{
"feedback": "...", //Consent status for the user, one of "accept", "reject", "custom" or "error"
"consentstring": "...", //consentmanager specific consent information to be stored on the device.
//This string needs to be passed back with the next request to the AppStart
//Endpoint as parameter &cs=...
"vendorConsents": {...}, //Object of vendors that have consent. Format is "vendorID":true|false
//For example: {"s26": true, "c172": false}
//Note: If a vendor ID is not present, you MUST assume no consent for this ID
"vendorLI": {...}, //Object of vendors that have legitimate interests. Format as above.
"purposeConsents": {...}, //Object of purposes that have consent. Format as above.
"purposeLI": {...}, //Object of purposes that have legitimate interests. Format as above.
"iabtcf": "...", //IAB TCF Consent String
"iabgpp": "...", //IAB GPP String
"addtlConsent": "...", //Google Additional Consent String
"metadata": //List of objects to be stored in device shared storage
//(e.g. NSUserDefaults, SharedPreferences or similar)
[
{ //Each object in the list contains 3 properties:
"name": "...", //Name (or key) of the data to be stored (e.g. keyname for SharedPreferences)
"value": "...", //Value to be stored
"type": "..." //Type of the value to be stored, can be “string” or “int”
},
...
]
}Endpoint del codice QR
Nel caso in cui l'utente clicchi su "Impostazioni", l'app mostrerà una seconda schermata di consenso con un codice QR (e un URL opzionale). L'utente scansionerà quindi il codice QR e continuerà a effettuare le proprie scelte relative alla privacy sul proprio cellulare. Mentre l'utente esegue questa operazione, l'app verificherà lo stato attuale della procedura.
A tal fine, la risposta dell'AppStart Endpoint conterrà un URL tramite “customsettings.statusurl”. Questo URL dovrà essere richiamato dall'app una volta che il codice QR sarà visualizzato all'utente. Si consiglia di richiamare l'URL ogni 3 secondi per verificare la presenza di aggiornamenti.
Chiamata dell'endpoint di feedback
L'URL dell'endpoint del codice QR è già pre-costruito dalla chiamata API dell'endpoint AppStart e non deve essere modificato o integrato. Si prega di effettuare una chiamata ogni 3 secondi mentre l'utente effettua le sue scelte.
Risposta dell'endpoint del codice QR
La risposta dell'API sarà un oggetto codificato in JSON nel seguente formato:
{
"status": "...", //Status of the process, one of:
//„initialized“ – User did not open the custom settings page yet
//„pending“ – User opened the custom settings page
//„finished“ – User finished their choices
//„error“ – An error occured
"feedbackobject": //In case of status=finished, the object will contain all consent data similar
//to the Feedback Endpoint API
{
...
}
}Altre informazioni sull'implementazione
Archiviazione dei consensi
Ogni volta che l'utente effettua una scelta o il processo del codice QR termina, l'API restituirà l'oggetto di feedback con tutti i dettagli. Consigliamo agli sviluppatori di app di memorizzare l'oggetto completo.
Gestione degli errori
Poiché l'app dipende da una chiamata a un'API esterna, raccomandiamo diverse strategie di gestione degli errori al fine di evitare problemi e un'esperienza utente negativa:
-
Errori
API Nel caso in cui un'API restituisca un codice di stato HTTP inatteso (ad es. 4xx, 5xx o 6xx), l'app dovrà trattarlo come un errore. L'app deve ricorrere a uno stato o a una logica predefiniti e saltare i passaggi successivi del processo. Nei casi in cui venga inviato un codice di stato HTTP 3xx o venga segnalato un cambiamento di posizione, l'app deve seguire l'URL segnalato (Nota: applicare una regola di follow massimo per evitare loop infiniti).
-
Timeout
Tutte le chiamate API devono avere un timeout massimo, ad esempio 15 secondi. Se l'API non risponde entro questo lasso di tempo, deve essere considerata offline. L'app deve ricorrere a uno stato o a una logica predefinita e saltare i passaggi successivi del processo.
-
Convalida
SSL Soprattutto con i dispositivi più vecchi, la convalida SSL può causare problemi quando le versioni dei certificati o i metodi di crittografia non sono più supportati. In tal caso, gli sviluppatori di app possono chiamare gli endpoint API tramite http invece che https.
-
Errori
di analisi Tutti gli endpoint API restituiscono oggetti JSON come stringhe codificate in UTF-8. Durante l'analisi della stringa, l'app deve verificare che l'analisi abbia funzionato come previsto. Inoltre, l'app deve:- Considera tutte le proprietà di tutti gli oggetti come opzionali e verifica sempre se una proprietà esiste prima di accedervi.
- Verifica se il valore restituito da una proprietà è del tipo di dati previsto (ad es. stringa, booleano o intero).
- Sii flessibile sulla struttura degli oggetti. Alcuni oggetti hanno una struttura dinamica e possono presentarsi con più o meno proprietà. Se un'app non riconosce una proprietà, deve ignorarla.
-
Errore
di stato del codice QR Nei casi in cui l'Endpoint di stato del codice QR restituisca status=error, l'app dovrebbe interrompere la raccolta del consenso e riprendere normalmente.
- Codice QR abbandonato
Nei casi in cui il codice QR sia visualizzato ma non si osservi alcun cambiamento di stato per un periodo di tempo prolungato, l'app dovrà tornare all'interfaccia di consenso iniziale (prima schermata) e consentire all'utente di scegliere nuovamente. Si consiglia un tempo di attesa massimo di 5 minuti prima di tornare alla prima schermata.
Gestione delle versioni
Le versioni dell'API sono gestite tramite l'URL dell'endpoint di AppStart. In caso di modifica dell'API, aggiorneremo l'URL dell'endpoint di AppStart a una nuova versione per consentire l'attivazione simultanea di più versioni.