[CTV-API] Integration - Consentmanager Staging

Allmän översikt

Syftet med API:et är att göra det möjligt för kunder att utveckla sitt eget samtyckesgränssnitt för fall där de SDK:er som tillhandahålls av consentmanager inte är tillräckliga. API:et gör det därför möjligt för kunden att bygga sitt eget grafiska gränssnitt baserat på den information som API:et tillhandahåller. Dessutom gör API:et det möjligt för kunden att använda branschstandarder såsom IAB TCF eller IAB GPP utan att behöva implementera egna kodare/avkodare.

Implementering

Implementeringen består av fyra delar:

TV API
Det gör det möjligt att hämta information om text, färger, knappar och länkar som ska visas i samtyckesgränssnittet.
TV API tillhandahålls av consentmanager.
Samtyckesgränssnitt
Det visar samtyckesmeddelandet för att låta slutanvändaren göra ett val.
Detta ska skapas av apputvecklaren.
Lagring
av samtycke När ett val har gjorts kommer lagringen av samtycke att spara dessa val för att använda informationen när det behövs.
Detta ska skapas av apputvecklaren.
QR-kod / Gränssnitt
för anpassade inställningar Om slutanvändaren vill göra anpassade val utöver att acceptera eller avvisa, kan appen visa en specifik QR-kod som slutanvändaren kan skanna med sin mobiltelefon. Slutanvändaren dirigeras till en webbplats där hen kan göra sina val. När detta är klart skickas valen tillbaka till TV-enheten med hjälp av TV-API:et och slutanvändaren kan fortsätta använda appen.
Detta tillhandahålls av consentmanager.

Begränsningar

Eftersom kunden kommer att implementera sitt eget gränssnitt erbjuder API:et inte full funktionalitet jämfört med en vanlig webb- eller appintegration. Bland annat ingår följande funktioner inte i API:et (bland annat):

CMP-inställningar

· Integrationer (t.ex. Adobe, Awin, etracker osv.)

· Integritets-API:er (DNT, GPC, ADPC, …)

· Automatisk blockering

· Åldersverifiering

· Begränsade rapporteringsfunktioner

Designinställningar

· Rutan storlek och placering

· Teckenstorlek och teckensnitt

· Växlar / Kryssrutor på det första lagret

· Ikoner för syften, knappar och länkar

· Stöd för WCAG

· Beteendelogik och effekter

Obs: Ovanstående inställningar skickas inte via API:et utan kan implementeras manuellt av apputvecklaren.

Inga begränsningar för inställningar

Förutom de ovan nämnda begränsningarna finns det fortfarande många funktioner som ingår i API:et (när det är fullt implementerat i din app) och som kan användas som vanligt. Bland annat är dessa:

Automatisk anpassning av texter till användarens språk
Visning av samtyckeslagret i de färger som ställts in via CMP / Design
Stöd för IAB TCF, IAB GPP, Google Consent Mode
A/B-testning och maskininlärning av olika designer
Anpassning av design till slutanvändare baserat på språk, land eller andra attribut
(begränsad) Rapportering av användare, visade samtyckesskärmar och val

Inställningar

Förutsättningar

För att kunna använda API:et måste du ha ett ConsentManager-konto med funktionen ”TV SDK” aktiverad (ingår vanligtvis i de högre paketen). Du kan se om funktionen ingår genom att logga in på ditt konto och gå till Meny > CMP:er > TV. Om du inte ser menyalternativet ”TV”, vänligen kontakta din kontoansvarige för att uppgradera ditt konto.

Aktivera TV API

För att börja använda API:et måste du skapa en CMP i ditt ConsentManager-konto och aktivera TV-API:et. CMP:n ska följa samma inställningar som du normalt skulle göra för en webbmiljö, vilket innebär att du måste ställa in de allmänna inställningarna för CMP:n och lägga till syften och leverantörer. När du är klar navigerar du till Meny > CMP:er > TV och aktiverar knappen för Aktivera TV-API.

När API:et är aktiverat ser du API-ändpunkten under växlingsknappen. Kopiera ändpunktens URL för vidare användning i din implementering.

Obs: När API:et har aktiverats tar det upp till en timme innan API-ändpunkten blir användbar. Observera också att ändringar i CMP- eller designinställningarna endast återspeglas dagligen inom TV-API:et.

API-flöde

För att implementera samtyckesgränssnittet i en app kommer apputvecklaren att anropa TV-API:et för att få information om huruvida samtyckesskärmen ska visas för just denna användare. API:et kommer också att innehålla information om färger och texter som ska presenteras för slutanvändaren samt vilka knappar och länkar som ska visas. När slutanvändaren har gjort ett val kommer appen att informera ConsentManager-systemet via TV-API:et om detta val och i gengäld få samtyckesdata (t.ex. IAB TCF-samtyckessträng, IAB GPP-sträng, lista över aktiverade leverantörer, lista över syften och så vidare). Appen kan sedan använda dessa samtyckesdata för att fastställa databehandlingsaktiviteter eller tillhandahålla dem till tredje part (t.ex. IAB TCF-samtyckessträngen).

Detaljerat flödesschema

Nedan hittar du det detaljerade flödesschemat för implementering av TV-API:et. Stegen är följande:

Appstart
Appen hämtar data från samtyckeslagret (om sådant finns)
Appen anropar TV API-ändpunkten ”AppStart” och skickar den befintliga samtyckessträngen
TV API svarar med ”displayLayer” inställt på ”true” eller ”false” för att ange att samtyckesgränssnittet ska visas
(Om displayLayer = true) Appen visar samtyckesgränssnittet med hjälp av informationen från TV-API:et
Användaren klickar på Acceptera: Appen anropar TV API-ändpunkten ”Feedback” för att bekräfta acceptans
–> Appen lagrar samtyckesdata och fortsätter som vanligt
Användaren klickar på Avvisa: Appen anropar TV API-ändpunkten ”Feedback” för
avvisning –> Appen lagrar samtyckesdata och fortsätter som vanligt
Användaren klickar på Inställningar: Appen visar en QR-kod
Appen anropar TV API-ändpunkten ”QR-Status” var tredje sekund för statusuppdatering
När QR-statusen är ”klar” (eller användaren klickar på ”tillbaka”-knappen) lagrar appen samtyckesuppgifterna och fortsätter som vanligt

AppStart Endpoint

URL:en till AppStart Endpoint finns i ditt inloggningsområde på Consentmanager (se avsnittet om inställningar ovan). Endpoint returnerar ett JSON-objekt och ger dig två uppgifter:

Om samtyckesgränssnittet ska visas
eller inte Detta anges av egenskapen ”displayLayer” med värdet ”true” (visa samtyckesgränssnittet) eller ”false” (samtyckesgränssnittet behöver inte visas).
Vilken stil ska användas om du måste/vill visa gränssnittet
för samtycke? Detta anges av egenskaperna ”display”

Anropa AppStart-ändpunkten

När du anropar AppStart Endpoint ska du använda den URL som du har fått i ditt ConsentManager-inloggningsområde. Dessutom ska du utöka URL:en genom att lägga till följande parametrar:

Parameter	Beskrivning
`&l=…`	(valfritt, rekommenderas) Önskat språk för visningen. T.ex. &l=DE eller &l=EN-US. API:et returnerar texterna på detta språk.
`&appid=…`	(valfritt, rekommenderat) Appens identifierare. T.ex. &appid=123456 eller &appid=my-app-name
`&cs=…`	(valfritt, krävs om det finns) Den lagrade samtyckessträngen för användarens senaste val. Samtyckessträngen skickas till appen via: a) Feedback Endpoint under egenskapen ”consentstring” eller b) QR-Status Endpoint under egenskapen ”feedbackobject.consentstring”
`&ip=…`	(valfritt) Användarens IP-adress som ska användas för geolokalisering. Om ingen IP-adress skickas används IP-adressen för begäran. T.ex. &ip=123.123.123.123

AppStart Endpoint Response

API-svaret kommer att vara ett JSON-kodat objekt i följande format:

{
 "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
 }
}

Utformning av gränssnittet för samtycke

Särskilt när branschstandarder som IAB TCF eller IAB GPP används är consentmanager enligt policy skyldigt att säkerställa att vissa standarder upprätthålls av sina kunder. Vi måste därför kräva att alla kunder använder den information som tillhandahålls via AppStart Endpoint för att utforma samtyckesgränssnittet.

Viktigt: För att säkerställa att alla regler följs kräver vi att alla kunder skickar in en skärmdump av det samtyckesgränssnitt de har skapat för godkännande.

IAB TCF & GPP-efterlevnad

För att säkerställa efterlevnad av IAB TCF och GPP måste vi kräva att alla kunder använder de element som tillhandahålls via AppStart Endpoint, närmare bestämt:

Samtyckesgränssnittet måste visa en rubrik och text på den första skärmen. Rubrik och text måste hämtas från API:et och visas i sin helhet. De får inte döljas, förkortas eller på annat sätt vara osynliga.
Gränssnittet för samtycke måste visa de knappar som anges av API:et och med den etiketttext som ges av API:et. Knapparna måste vara synliga omedelbart och får inte skymmas.
Gränssnittet för samtycke måste visa de länkar som anges av API:et. Länkarna måste vara tillgängliga för kunden men behöver inte vara omedelbart synliga. Vi rekommenderar dock att alltid göra alla länkar synliga.
Samtyckesgränssnittet ska använda de färger som anges av API:et. Om detta inte är möjligt på grund av begränsningar i enheten måste samtyckesgränssnittet utformas på ett sätt som säkerställer att alla knappar har samma betydelse.

Feedback Endpoint

Svaret från AppStart Endpoint kommer att innehålla två URL:er via ”feedback.accept” och ”feedback.reject”. Dessa URL:er ska anropas av appen när användaren väljer att acceptera eller avvisa sekretessinställningarna.

Anropa feedback-ändpunkten

URL:erna för feedback-ändpunkterna är redan förkonstruerade av AppStart Endpoint API-anropet och behöver inte ändras eller kompletteras. Anropa den korrekta URL:en som motsvarar användarens val.

Feedback Endpoint Response

API-svaret kommer att vara ett JSON-kodat objekt i följande format:

{
 "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”
  },
  ...
 ]
}

QR-kodens slutpunkt

Om användaren klickar på inställningar ska appen visa en andra samtyckesskärm med en QR-kod (och valfri URL). Användaren skannar sedan QR-koden och fortsätter att göra sina integritetsval på sin mobiltelefon. Medan användaren gör detta ska appen kontrollera procedurens aktuella status.

För detta kommer svaret från AppStart Endpoint att innehålla en URL via ”customsettings.statusurl”. Denna URL ska anropas av appen så snart QR-koden visas för användaren. Vi rekommenderar att URL:en anropas var tredje sekund för att kontrollera om det finns uppdateringar.

Anropa feedback-ändpunkten

QR-kodens slutpunkts-URL är redan förkonstruerad av AppStart Endpoint API-anropet och behöver inte ändras eller kompletteras. Vänligen anropa var tredje sekund medan användaren gör sina val.

Svar från QR-kodens slutpunkt

API-svaret kommer att vara ett JSON-kodat objekt i följande format:

{
 "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
 {
  ...
 }
}

Övrig information om implementering

Lagring av samtycke

När användaren har gjort ett val eller QR-kodprocessen är avslutad returnerar API:et feedbackobjektet med alla detaljer. Vi rekommenderar apputvecklare att lagra hela objektet.

Felhantering

Eftersom appen är beroende av ett anrop till ett externt API rekommenderar vi olika strategier för felhantering för att undvika problem och en dålig användarupplevelse:

API-fel
Om ett API returnerar en oväntad HTTP-statuskod (t.ex. 4xx, 5xx eller 6xx) ska appen behandla detta som ett fel. Appen ska återgå till ett standardläge eller standardlogik och hoppa över nästa steg i processen. I fall där HTTP-statuskod 3xx skickas eller på annat sätt signaleras en platsändring, ska appen följa den signalerade URL:en (Obs: Tillämpa en regel om maximalt antal följningar för att undvika oändliga loopar).
Timeouts
Alla API-anrop ska ha en maximal timeout, t.ex. 15 sekunder. Om API:et inte svarar inom denna tidsram ska det betraktas som offline. Appen ska då återgå till ett standardläge eller standardlogik och hoppa över nästa steg i processen.
SSL-validering
Särskilt på äldre enheter kan SSL-validering orsaka problem när certifikatversioner eller krypteringsmetoder inte längre stöds. Om så är fallet kan apputvecklare anropa API-ändpunkterna via http istället för https.
Parsningsfel
Alla API-ändpunkter returnerar JSON-objekt som UTF-8-kodade strängar. Vid parsning av strängen ska appen verifiera att parsningen fungerade som förväntat. Dessutom ska appen:
- Behandla alla egenskaper hos alla objekt som valfria och kontrollera alltid om en egenskap finns innan du använder den.
- Kontrollera om det returnerade värdet för en egenskap är av den förväntade datatypen (t.ex. sträng, bool eller heltal).
- Var flexibel när det gäller objektstrukturen. Vissa objekt har en dynamisk struktur och kan förekomma med fler eller färre egenskaper. Om en app inte känner till en egenskap ska den ignorera den.
QR-kodstatusfel
I de fall då QR-kodstatusändpunkten returnerar status=error ska appen avbryta insamlingen av samtycke och återuppta som vanligt.
QR-kod borttagen

I de fall då QR-koden visas men ingen statusförändring observeras under en längre tid, ska appen återgå till det inledande samtyckesgränssnittet (första skärmen) och låta användaren välja på nytt. Vi rekommenderar en maximal väntetid på 5 minuter innan återgång till första skärmen.

Versionshantering

API-versionerna hanteras via AppStart Endpoint URL. Vid en API-ändring uppdaterar vi AppStart Endpoint URL till en ny version för att möjliggöra att flera versioner är aktiva samtidigt.