[CTV-API] Integration

Allmän översikt

Syftet med API:et är att tillåta klienter att utveckla sitt eget samtyckesgränssnitt för fall då SDK:erna tillhandahålls av consentmanager är inte tillräckliga. API:et kommer därför att tillåta klienten att bygga sitt eget grafiska gränssnitt baserat på den information som API tillhandahåller. Dessutom kommer API:et att tillåta klienten att använda industristandarder som IAB TCF eller IAB GPP utan att behöva implementera sina egna kodare/avkodare.

Genomförande

Implementeringen består av fyra delar:

1. TV API
   Det gör det möjligt att söka information om text, färger, knappar och länkar som ska visas i samtyckesgränssnittet.
   TV API tillhandahålls av consentmanager.
   
   
2. Samtyckesgränssnitt
   Den visar samtyckesmeddelandet så att slutanvändaren kan göra ett val.
   Detta ska skapas av apputvecklaren.
   
   
3. Lagring av samtycke
   När ett val har gjorts kommer samtyckeslagringen att lagra dessa val för att använda informationen när det behövs.
   Detta ska skapas av apputvecklaren.
   
   
4. QR-kod / anpassade inställningar gränssnitt
   Om slutanvändaren vill göra egna val förutom att acceptera eller avvisa, kan appen visa en specifik QR-kod som slutanvändaren kan skanna med sin mobiltelefon. Slutanvändaren kommer att dirigeras till en webbplats där de kan göra sina val. När de är klara skickas valen tillbaka till TV-enheten med hjälp av TV API och slutanvändaren kan fortsätta använda appen.
   Detta tillhandahålls av consentmanager.

Begränsningar

Eftersom klienten kommer att implementera sitt eget gränssnitt ger API:et inte den fulla funktionaliteten jämfört med en normal webb- eller appintegration. Bland annat är följande funktioner inte en del av API:et (bland annat):

Obs: De ovan nämnda inställningarna skickas inte via API:t utan kan implementeras manuellt av apputvecklaren.

Inga begränsningar på inställningar

Förutom de ovan nämnda begränsningarna finns det fortfarande många funktioner som är en del av API:t (när de är fullt implementerade i din app) och som kan användas som vanligt. Dessa är bland annat:

• Automatisk anpassning av texter till användarens språk
• Visning av samtyckesskiktet i de färger som ställts in via CMP / Design
• Stöd för IAB TCF, IAB GPP, Google Consent Mode
• A/B-Test & Maskininlärning av olika konstruktioner
• Inriktning 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ällning

Förutsättningar

För att kunna använda API:t måste du ha en consentmanager konto med funktionen "TV SDK" aktiverad (vanligtvis inkluderad i de högre paketen). Du kan se om funktionen ingår genom att logga in på ditt konto och navigera till Meny > CMPs > TV. Om du inte ser menyalternativet "TV", vänligen kontakta din kontoansvariga 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 din consentmanager konto och aktivera TV API. CMP 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 och lägga till syften och leverantörer. När du är klar, navigera till Meny > CMPs > TV och aktivera strömbrytaren Aktivera TV API.

När API är aktiverat kommer du att se API-slutpunkten under växlingen. Kopiera Endpoint URL för vidare användning i din implementering.

Notera: När API:et är aktiverat, är det kommer att ta upp till 1 timme innan API-slutpunkten blir användbar. Observera också att ändringar av CMP- eller Design-inställningarna kommer att återspeglas bara på daglig basis inom TV API.

API-flöde

För att implementera samtyckesgränssnittet i en app kommer apputvecklaren att anropa TV API för att få information om huruvida samtyckesskärmen ska visas för denna specifika användare eller inte. API:et kommer även 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 gör ett val kommer appen att informera consentmanager system via TV-API:et om detta val och kommer i gengäld att ta emot samtyckesdata (t.ex. IAB TCF-samtyckessträng, IAB GPP-sträng, lista över aktiverade leverantörer, lista över ändamål och så vidare). Appen kan sedan använda dessa samtyckesdata för att fastställa databearbetningsaktiviteter eller tillhandahålla den 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. Stegen är som följer:

1. Appstart
2. Appen hämtar data från samtyckesbutiken (om sådan finns)
3. Appen anropar TV API Endpoint "AppStart" och skickar befintlig samtyckessträng
4. TV API svarar med "displayLayer" satt till "true" eller "false" för att indikera att samtyckesgränssnittet ska visas
5. (Om displayLayer = true) Appen visar samtyckesgränssnittet med hjälp av informationen från TV:ns API
6. Användaren klickar på Acceptera: App anropar TV API Endpoint "Feedback" för att acceptera
   -> Appen lagrar samtyckesdata och fortsätter som vanligt
7. Användaren klickar på Avvisa: Appen anropar TV API Endpoint "Feedback" för avvisning
   --> Appen lagrar samtyckesdata och fortsätter som vanligt
8. Användaren klickar på Inställningar: Appen visar QR-koden
9. Appen anropar TV API Endpoint "QR-Status" var tredje sekund för statusuppdatering
10. När QR-status är "klar" (eller användaren klickar på "tillbaka"), lagrar appen samtyckesdata och fortsätter som vanligt

AppStart Endpoint

Webbadressen till AppStart Endpoint finns i din consentmanager Inloggningsområde (se avsnittet om Inställningar ovan). Endpoint returnerar ett JSON-objekt och ger dig två delar av information:

1. Huruvida samtyckesgränssnittet ska visas eller inte
   Detta signaleras av egenskapen "displayLayer" med värdet "true" (visa samtyckesgränssnittet) eller "false" (inget behov av att visa samtyckesgränssnittet).
   
   
2. Vilken styling ska användas, om du måste/vill visa samtyckesgränssnittet
   Detta indikeras av egenskaperna "display"

Anropar AppStart Endpoint

När du ringer AppStart Endpoint bör du använda den URL som du fått i din consentmanager Inloggningsområde. Dessutom bör du utöka webbadressen genom att lägga till följande parametrar:

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

Styling av samtyckesgränssnittet

Speciellt när man använder industristandarder som IAB TCF eller IAB GPP, consentmanager enligt policy krävs för att säkerställa att vissa standarder upprätthålls av dess kunder. Vi måste kräver därför att alla klienter använder informationen som tillhandahålls via AppStart Endpoint för att sammanställa designen av samtyckesgränssnittet.

Viktigt: För att säkerställa att alla regler följs har vi kräver alla kunder att skicka in en exempelskärmdump av samtyckesgränssnittet som de har skapat för godkännande.

IAB TCF & GPP-efterlevnad

För att säkerställa IAB TCF & GPP-efterlevnad måste vi kräva att alla kunder använder de element som tillhandahålls via AppStart Endpoint, specifikt:

1. 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 skymmas, förkortas eller på annat sätt osynliga.
2. Samtyckesgränssnittet måste visa knapparna som anges av API:et och med etiketttexten som ges av API:et. Knappar måste vara synliga omedelbart och får inte skymmas.
3. Samtyckesgränssnittet måste visa länkarna som anges av API:et. Länkar måste vara tillgängliga för klienten men behöver inte vara omedelbart synliga. Hur som helst rekommenderar vi att du alltid gör alla länkar synliga.
4. Samtyckesgränssnittet ska använda de färger som anges av API:et. Om det inte är möjligt på grund av begränsningar av 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å webbadresser via "feedback.accept" och "feedback.reject". Dessa webbadresser ska anropas av appen när användaren väljer att acceptera eller avvisa sekretessinställningarna.

Ringer Feedback Endpoint

Feedback Endpoint-URL:erna är redan förkonstruerade av AppStart Endpoint API-anropet och behöver inte ändras eller läggas till. Ring den korrekta webbadressen 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-kod slutpunkt

Om användaren klickar på inställningar ska appen visa en andra samtyckesskärm som visar en QR-kod (och valfri URL). Användaren kommer sedan att skanna QR-koden och fortsätta göra sina integritetsval på sin mobiltelefon. Medan användaren gör detta ska appen kontrollera den aktuella statusen för proceduren.

För detta kommer svaret från AppStart Endpoint att innehålla en URL via "customsettings.statusurl". Denna URL ska anropas av appen när QR-koden visas för användaren. Vi rekommenderar att du ringer webbadressen var tredje sekund för att söka efter uppdateringar.

Ringer Feedback Endpoint

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

QR-kod Endpoint Response

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

Annan implementeringsinformation

Lagring av samtycke

Närhelst användaren gjort ett val eller QR-kodprocessen avslutas, kommer API:et att returnera 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 felhanteringsstrategier för att undvika problem och 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 bör falla tillbaka till ett standardtillstånd eller logik och hoppa över nästa steg i processen. I de fall när HTTP-statuskod 3xx skickas eller på annat sätt en platsändring signaleras, ska appen följa den signalerade URL:en (Obs: Använd en maximal följningsregel för att undvika oändliga loopar).
  
  
• Tidsgränser
  Alla API-anrop ska ha en maximal timeout, t.ex. 15 sekunder. Om API:et inte svarar inom denna tidsperiod bör det betraktas som offline. Appen bör falla tillbaka till ett standardtillstånd eller logik och hoppa över nästa steg i processen.
  
  
• SSL-validering
  Speciellt med ä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 Endpoints via http istället för https.
  
  
• Parsningsfel
  Alla API-slutpunkter returnerar JSON-objekt som UTF-8-kodade strängar. När strängen analyseras bör appen verifiera att analysen fungerade som förväntat. Dessutom ska appen:
  • Behandla alla egenskaper för alla objekt som valfria och kontrollera alltid om en egenskap finns innan du kommer åt 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 på objektstrukturen. Vissa objekt har en dynamisk struktur och kan förekomma med mer eller mindre egenskaper. Om en app inte känner till en egenskap ska den ignorera den.
    
    
• QR-kod statusfel
  I de fall QR-koden Status Endpoint returnerar status=error bör appen avbryta samtyckesinsamlingen och återupptas som vanligt.
  
  
• QR-koden övergiven

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

Versionshantering

API-versionerna hanteras via AppStart Endpoint URL. I händelse av en API-ändring kommer vi att uppdatera AppStart Endpoint URL till en ny version för att tillåta att flera versioner är aktiva samtidigt.