[CTV-API] Integracja

Przegląd ogólny

Celem interfejsu API jest umożliwienie klientom opracowania własnego interfejsu zgody na wypadek, gdyby zestawy SDK udostępniane przez consentmanager nie są wystarczające. API pozwoli zatem klientowi na zbudowanie własnego graficznego interfejsu w oparciu o informacje dostarczane przez API. Ponadto API pozwoli klientowi na korzystanie ze standardów branżowych, takich jak IAB TCF lub IAB GPP, bez konieczności implementowania własnych koderów/dekoderów.

Wdrożenie

Wdrożenie składa się z czterech części:

1. API telewizji
   Umożliwia ona zapytanie o informacje dotyczące tekstu, kolorów, przycisków i linków, które powinny być wyświetlane w interfejsie zgody.
   Interfejs API TV jest dostarczany przez consentmanager.
   
   
2. Interfejs zgody
   Wyświetla komunikat o zgodzie, aby umożliwić użytkownikowi końcowemu dokonanie wyboru.
   Jest to zadanie dla twórcy aplikacji.
   
   
3. Przechowywanie zgody
   Po dokonaniu wyboru, pamięć podręczna zgód będzie przechowywać wybrane opcje, aby w razie potrzeby wykorzystać te informacje.
   Jest to zadanie dla twórcy aplikacji.
   
   
4. Interfejs kodu QR/ustawień niestandardowych
   Jeśli użytkownik końcowy chce dokonać niestandardowych wyborów oprócz zaakceptowania lub odrzucenia, aplikacja może wyświetlić określony kod QR, który użytkownik końcowy może zeskanować za pomocą telefonu komórkowego. Użytkownik końcowy zostanie przekierowany na stronę internetową, na której może dokonać wyboru. Po dokonaniu wyboru wybory są odsyłane z powrotem do urządzenia TV za pomocą interfejsu API TV, a użytkownik końcowy może kontynuować korzystanie z aplikacji.
   Zapewnia to consentmanager.

Ograniczenia

Ponieważ klient zaimplementuje własny interfejs, API nie zapewnia pełnej funkcjonalności w porównaniu do normalnej integracji webowej lub aplikacji. Między innymi, następujące funkcje nie są częścią API (między innymi):

Uwaga: Powyższe ustawienia nie są wysyłane za pośrednictwem interfejsu API, ale mogą zostać ręcznie zaimplementowane przez programistę aplikacji.

Brak ograniczeń ustawień

Oprócz wyżej wymienionych ograniczeń, istnieje wiele funkcji, które są częścią API (gdy są w pełni zaimplementowane w Twojej aplikacji) i mogą być używane jak zwykle. Są to między innymi:

• Automatyczne dopasowanie tekstów do języka użytkownika
• Wyświetlanie warstwy zgody w kolorach ustawionych za pomocą CMP/Design
• Obsługa IAB TCF, IAB GPP i trybu zgody Google
• Testowanie A/B i uczenie maszynowe różnych projektów
• Kierowanie projektów do użytkowników końcowych na podstawie języka, kraju lub innych atrybutów
• (ograniczone) Raportowanie użytkowników, wyświetlanych ekranów zgody i wyborów

ustawienie

Wymagania wstępne

Aby móc korzystać z API, musisz mieć consentmanager konto z włączoną funkcją „TV SDK” (zwykle włączoną w wyższych pakietach). Możesz sprawdzić, czy funkcja jest włączona, logując się na swoje konto i przechodząc do Menu > CMP > Telewizja. Jeśli nie widzisz pozycji menu „TV”, skontaktuj się ze swoim menedżerem konta, aby uaktualnić swoje konto.

Włącz API TV

Aby rozpocząć korzystanie z interfejsu API, musisz utworzyć CMP w swoim systemie. consentmanager konto i włącz API TV. CMP będzie stosować te same ustawienia, które normalnie stosujesz w środowisku internetowym, co oznacza, że ​​będziesz musiał ustawić ogólne ustawienia CMP i dodać cele i dostawców. Po wykonaniu tej czynności przejdź do Menu > CMP > Telewizja i aktywuj przełącznik Włącz API TV.

Po włączeniu API zobaczysz API-Endpoint poniżej przełącznika. Skopiuj adres URL Endpoint do dalszego wykorzystania w implementacji.

Uwaga: Po włączeniu interfejsu API zajmie do 1 godziny zanim API-Endpoint stanie się użyteczny. Należy również pamiętać, że zmiany w ustawieniach CMP lub Design będą odzwierciedlać tylko na co dzień w ramach API TV.

Przepływ API

Aby zaimplementować interfejs zgody w aplikacji, programista aplikacji wywoła API TV, aby otrzymać informacje o tym, czy ekran zgody powinien zostać wyświetlony temu konkretnemu użytkownikowi. API będzie również zawierać informacje o kolorach i tekstach, które mają zostać zaprezentowane użytkownikowi końcowemu, a także o tym, które przyciski i łącza mają zostać wyświetlone. Gdy użytkownik końcowy dokona wyboru, aplikacja poinformuje go o tym. consentmanager system za pośrednictwem API TV o tym wyborze i w zamian otrzyma dane zgody (np. ciąg zgody IAB TCF, ciąg IAB GPP, listę aktywowanych dostawców, listę celów itd.). Następnie aplikacja może wykorzystać te dane zgody do określenia działań związanych z przetwarzaniem danych lub udostępnić je osobom trzecim (np. ciąg zgody IAB TCF).

Szczegółowy schemat blokowy

Poniżej znajdziesz szczegółowy schemat blokowy implementacji API TV. Kroki są następujące:

1. Uruchomienie aplikacji
2. Aplikacja pobiera dane z magazynu zgód (jeśli istnieje)
3. Aplikacja wywołuje punkt końcowy interfejsu API TV „AppStart” i przekazuje istniejący ciąg zgody
4. Interfejs API TV odpowiada, ustawiając parametr „displayLayer” na „true” lub „false”, aby wskazać, że interfejs zgody ma zostać wyświetlony
5. (Jeśli displayLayer = true) Aplikacja wyświetla interfejs zgody, korzystając z informacji z interfejsu API TV
6. Użytkownik klika Akceptuj: aplikacja wywołuje punkt końcowy API TV „Opinie” w celu zaakceptowania
   -> Aplikacja przechowuje dane dotyczące zgody i kontynuuje działanie normalnie
7. Użytkownik klika Odrzuć: aplikacja wywołuje punkt końcowy interfejsu API TV „Opinie” w celu odrzucenia
   --> Aplikacja przechowuje dane dotyczące zgody i kontynuuje działanie normalnie
8. Użytkownik klika Ustawienia: Aplikacja wyświetla kod QR
9. Aplikacja wywołuje punkt końcowy API TV „QR-Status” co 3 sekundy w celu aktualizacji statusu
10. Po zakończeniu statusu QR (lub kliknięciu przez użytkownika przycisku „wstecz”) aplikacja przechowuje dane dotyczące zgody i kontynuuje działanie normalnie

Punkt końcowy AppStart

Adres URL punktu końcowego AppStart można znaleźć w consentmanager Obszar logowania (patrz sekcja o konfiguracji powyżej). Punkt końcowy zwróci obiekt JSON i poda dwie informacje:

1. Czy interfejs zgody ma być wyświetlany
   Informuje o tym właściwość „displayLayer” o wartości „true” (wyświetlanie interfejsu zgody) lub „false” (brak konieczności wyświetlania interfejsu zgody).
   
   
2. Jaki styl należy zastosować, jeśli musisz/chcesz wyświetlić interfejs zgody
   Sygnalizuje to właściwość „display”

Wywoływanie punktu końcowego AppStart

Podczas wywoływania punktu końcowego AppStart należy używać adresu URL podanego w aplikacji. consentmanager Obszar logowania. Ponadto należy rozszerzyć adres URL, dodając następujące parametry:

Odpowiedź punktu końcowego AppStart

Odpowiedź API będzie obiektem zakodowanym w formacie JSON w następującym formacie:

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

Stylizowanie interfejsu zgody

Szczególnie w przypadku stosowania standardów branżowych, takich jak IAB TCF lub IAB GPP, consentmanager jest zobowiązana przez politykę do zapewnienia, że ​​określone standardy są przestrzegane przez jej klientów. My musi w związku z tym wymagaj od wszystkich klientów, aby wykorzystywali informacje dostarczone za pośrednictwem punktu końcowego AppStart do projektowania interfejsu zgody.

Ważne: Aby mieć pewność, że wszystkie zasady są przestrzegane, wymagać wszyscy klienci są zobowiązani do przesłania przykładowego zrzutu ekranu interfejsu zgody, który utworzyli, w celu zatwierdzenia.

Zgodność z IAB TCF i GPP

Aby zapewnić zgodność z wytycznymi IAB TCF i GPP, musimy wymagać od wszystkich klientów korzystania z elementów dostarczanych za pośrednictwem punktu końcowego AppStart, a konkretnie:

1. Interfejs zgody musi wyświetlać nagłówek i tekst na pierwszym ekranie. Nagłówek i tekst muszą być pobrane z API i wyświetlane w całości. Nie mogą być zaciemnione, skrócone ani w inny sposób niewidoczne.
2. Interfejs zgody musi wyświetlać przyciski wskazane przez API i z tekstem etykiety podanym przez API. Przyciski muszą być widoczne natychmiast i nie mogą być przysłonięte.
3. Interfejs zgody musi wyświetlać linki wskazane przez API. Linki muszą być dostępne dla klienta, ale nie muszą być natychmiast widoczne. W każdym razie zalecamy, aby zawsze wszystkie linki były widoczne.
4. Interfejs zgody powinien używać kolorów wskazanych przez API. Jeśli nie jest to możliwe ze względu na ograniczenia urządzenia, interfejs zgody musi być zaprojektowany w sposób, który zapewnia, że ​​wszystkie przyciski mają takie samo znaczenie.

Punkt końcowy opinii

Odpowiedź AppStart Endpoint będzie zawierać dwa adresy URL za pośrednictwem „feedback.accept” i „feedback.reject”. Te adresy URL zostaną wywołane przez aplikację, gdy użytkownik zdecyduje się zaakceptować lub odrzucić ustawienia prywatności.

Wywołanie punktu końcowego opinii

Adresy URL Feedback Endpoint są już wstępnie skonstruowane przez wywołanie AppStart Endpoint API i nie muszą być zmieniane ani dołączane. Wywołaj poprawny adres URL odpowiadający wyborowi użytkownika.

Odpowiedź punktu końcowego opinii

Odpowiedź API będzie obiektem zakodowanym w formacie JSON w następującym formacie:

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

Punkt końcowy kodu QR

W przypadku kliknięcia przez użytkownika ustawień aplikacja wyświetli drugi ekran zgody, wyświetlając kod QR (i opcjonalny adres URL). Następnie użytkownik zeskanuje kod QR i będzie kontynuował dokonywanie wyborów dotyczących prywatności na swoim telefonie komórkowym. Podczas gdy użytkownik to robi, aplikacja sprawdzi aktualny status procedury.

W tym celu odpowiedź AppStart Endpoint będzie zawierać adres URL za pośrednictwem „customsettings.statusurl”. Ten adres URL zostanie wywołany przez aplikację po wyświetleniu użytkownikowi kodu QR. Zalecamy wywoływanie adresu URL co 3 sekundy w celu sprawdzenia dostępności aktualizacji.

Wywołanie punktu końcowego opinii

Adres URL punktu końcowego kodu QR jest już wstępnie skonstruowany przez wywołanie interfejsu API punktu końcowego AppStart i nie trzeba go zmieniać ani dołączać. Wywołuj co 3 sekundy, gdy użytkownik dokonuje wyboru.

Odpowiedź punktu końcowego kodu QR

Odpowiedź API będzie obiektem zakodowanym w formacie JSON w następującym formacie:

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

Inne informacje dotyczące wdrożenia

Przechowywanie zgody

Za każdym razem, gdy użytkownik dokona wyboru lub proces QR-Code się zakończy, API zwróci obiekt feedback ze wszystkimi szczegółami. Zalecamy twórcom aplikacji przechowywanie pełnego obiektu.

Obsługa błędów

Ponieważ aplikacja opiera się na wywołaniu zewnętrznego interfejsu API, zalecamy stosowanie różnych strategii obsługi błędów, aby uniknąć problemów i negatywnych doświadczeń użytkownika:

• Błędy API
  W przypadku, gdy API zwróci nieoczekiwany kod statusu HTTP (np. 4xx, 5xx lub 6xx), aplikacja potraktuje to jako błąd. Aplikacja powinna powrócić do domyślnego stanu lub logiki i pominąć kolejne kroki procesu. W przypadku, gdy zostanie wysłany kod statusu HTTP 3xx lub w inny sposób zostanie zasygnalizowana zmiana lokalizacji, aplikacja podąży za zasygnalizowanym adresem URL (Uwaga: Zastosuj regułę maksymalnego śledzenia, aby uniknąć nieskończonych pętli).
  
  
• Limit czasu
  Wszystkie wywołania API muszą mieć maksymalny limit czasu, np. 15 sekund. Jeśli API nie odpowie w tym przedziale czasowym, należy uznać je za offline. Aplikacja powinna powrócić do domyślnego stanu lub logiki i pominąć kolejne kroki procesu.
  
  
• Walidacja SSL
  Zwłaszcza w przypadku starszych urządzeń walidacja SSL może powodować problemy, gdy wersje certyfikatów lub metody szyfrowania nie są już obsługiwane. Jeśli tak jest, programiści aplikacji mogą wywoływać punkty końcowe API przez http zamiast https.
  
  
• Błędy analizy
  Wszystkie punkty końcowe interfejsu API zwracają obiekty JSON jako ciągi zakodowane w formacie UTF-8. Podczas analizowania ciągu aplikacja powinna zweryfikować, czy analiza przebiegła zgodnie z oczekiwaniami. Ponadto aplikacja powinna:
  • Wszystkie właściwości obiektów traktuj jako opcjonalne i zawsze sprawdzaj, czy dana właściwość istnieje, zanim uzyskasz do niej dostęp.
  • Sprawdź, czy zwrócona wartość właściwości ma oczekiwany typ danych (np. ciąg znaków, wartość logiczna lub liczba całkowita).
  • Bądź elastyczny w kwestii struktury obiektu. Niektóre obiekty mają dynamiczną strukturę i mogą występować z większą lub mniejszą liczbą właściwości. Jeśli aplikacja nie zna właściwości, powinna ją zignorować.
    
    
• Błąd statusu kodu QR
  W przypadku gdy punkt końcowy statusu kodu QR zwróci status=error, aplikacja powinna przerwać zbieranie zgód i wznowić je normalnie.
  
  
• Porzucony kod QR

W przypadkach, gdy kod QR jest wyświetlany, ale przez dłuższy czas nie obserwuje się żadnej zmiany statusu, aplikacja powróci do początkowego interfejsu zgody (pierwszy ekran) i umożliwi użytkownikowi ponowny wybór. Zalecamy maksymalny czas oczekiwania 5 minut przed powrotem do pierwszego ekranu.

Zarządzanie wersjami

Wersje API są zarządzane za pośrednictwem adresu URL punktu końcowego AppStart. W przypadku zmiany API zaktualizujemy adres URL punktu końcowego AppStart do nowej wersji, aby umożliwić jednoczesne posiadanie wielu wersji aktywnych.