[CTV-API] Integracja - Consentmanager Staging

Ogólny przegląd

Celem API jest umożliwienie klientom opracowania własnego interfejsu zgody na wypadek, gdyby SDK dostarczone przez ConsentManager okazały się niewystarczające. API pozwoli zatem klientowi na zbudowanie własnego interfejsu graficznego 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 wdrażania własnych koderów/dekoderów.

Wdrożenie

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

TV API
Umożliwia wyszukiwanie informacji o tekście, kolorach, przyciskach i linkach, które powinny być wyświetlane w interfejsie zgody.
TV API jest dostarczane przez consentmanager.
Interfejs
zgody Wyświetla komunikat o zgodzie, aby umożliwić użytkownikowi końcowemu dokonanie wyboru. Ma to zostać stworzone przez twórcę aplikacji.
Przechowywanie
zgód Po dokonaniu wyboru system przechowywania zgód zapisze te wybory, aby wykorzystać te informacje w razie potrzeby. Ma to zostać stworzone przez twórcę aplikacji.
Kod QR / Interfejs
ustawień niestandardowych Jeśli użytkownik końcowy chce dokonać niestandardowych wyborów poza akceptacją lub odrzuceniem, aplikacja może wyświetlić konkretny 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 będzie mógł dokonać wyboru. Po dokonaniu wyboru opcje są wysyłane z powrotem do urządzenia telewizyjnego za pomocą interfejsu API telewizora, a użytkownik końcowy może kontynuować korzystanie z aplikacji.
Usługę tę zapewnia Consentmanager.

Ograniczenia

Ponieważ klient wdroży własny interfejs, API nie zapewnia pełnej funkcjonalności w porównaniu ze zwykłą integracją z witryną internetową lub aplikacją. Wśród innych funkcji, następujące nie są częścią API (między innymi):

Ustawienia CMP

· Integracje (np. Adobe, Awin, etracker itp.)

· API dotyczące prywatności (DNT, GPC, ADPC, …)

· Automatyczne blokowanie

· Weryfikacja wieku

· Ograniczone funkcje raportowania

Ustawienia projektu

· Rozmiar i położenie ramki

· Rozmiar i rodzaj czcionki

· Przełączniki / pola wyboru na pierwszej warstwie

· Ikony funkcji, przyciski i linki

· Obsługa WCAG

· Logika działania i efekty

Uwaga: Wyżej wymienione ustawienia nie są przesyłane przez API, ale mogą być wdrożone ręcznie przez twórcę aplikacji.

Brak ograniczeń dotyczących ustawień

Oprócz wyżej wymienionych ograniczeń, nadal istnieje wiele funkcji, które są częścią API (po pełnym wdrożeniu w aplikacji) i mogą być używane w zwykły sposób. Są to między innymi:

Automatyczne dostosowanie tekstów do języka użytkownika
Wyświetlanie warstwy zgody w kolorach ustawionych za pośrednictwem CMP / Design
Obsługa IAB TCF, IAB GPP, trybu zgody Google
Testy A/B i uczenie maszynowe różnych projektów
Dostosowywanie projektów do użytkowników końcowych na podstawie języka, kraju lub innych atrybutów
(ograniczone) Raportowanie użytkowników, wyświetlone ekrany zgody i wybory

Konfiguracja

Wymagania wstępne

Aby korzystać z API, musisz posiadać konto ConsentManager z włączoną funkcją „TV SDK” (zwykle dostępną w wyższych pakietach). Możesz sprawdzić, czy funkcja ta jest dostępna, logując się na swoje konto i przechodząc do Menu > CMPs > TV. Jeśli nie widzisz pozycji menu „TV”, skontaktuj się ze swoim opiekunem klienta w celu aktualizacji konta.

Włącz API TV

Aby rozpocząć korzystanie z API, musisz utworzyć CMP na swoim koncie ConsentManager i włączyć API TV. CMP powinno mieć takie same ustawienia, jakie zwykle stosuje się w środowisku internetowym, co oznacza, że musisz skonfigurować ogólne ustawienia CMP oraz dodać cele i dostawców. Gdy to zrobisz, przejdź do Menu > CMP > TV i włącz przełącznik przy opcji Włącz API TV.

Po włączeniu API pod przełącznikiem zobaczysz punkt końcowy API. Skopiuj adres URL punktu końcowego do dalszego wykorzystania w swojej implementacji.

Uwaga: Po włączeniu API minie do 1 godziny, zanim punkt końcowy API będzie gotowy do użycia. Należy również pamiętać, że zmiany w ustawieniach CMP lub Design będą odzwierciedlane w API TV tylko raz dziennie.

Przepływ API

Aby wdrożyć interfejs zgody w aplikacji, programista wywoła API TV, aby otrzymać informację, czy ekran zgody powinien zostać wyświetlony dla tego konkretnego użytkownika. API będzie również zawierało informacje na temat kolorów i tekstów, które mają być prezentowane użytkownikowi końcowemu, a także na temat przycisków i linków, które mają być wyświetlane. Gdy użytkownik końcowy dokona wyboru, aplikacja poinformuje system ConsentManager za pośrednictwem API TV o tym wyborze i w zamian otrzyma dane dotyczące zgody (np. ciąg znaków zgody IAB TCF, ciąg znaków IAB GPP, listę aktywowanych dostawców, listę celów itp.). Następnie aplikacja może wykorzystać te dane dotyczące zgody do określenia działań związanych z przetwarzaniem danych lub udostępnić je stronom trzecim (np. ciąg znaków zgody IAB TCF).

Szczegółowy schemat blokowy

Poniżej znajduje się szczegółowy schemat blokowy wdrożenia API TV. Kroki są następujące:

Uruchom aplikację
Aplikacja pobiera dane z magazynu zgód (jeśli istnieje)
Aplikacja wywołuje punkt końcowy API TV o nazwie „AppStart” i przekazuje istniejący ciąg znaków zgody
TV API odpowiada z „displayLayer” ustawionym na „true” lub „false”, aby wskazać, że interfejs zgody ma zostać wyświetlony
(Jeśli displayLayer = true) Aplikacja wyświetla interfejs zgody, wykorzystując informacje z TV API
Użytkownik klika „Akceptuj”: aplikacja wywołuje punkt końcowy API TV „Feedback” w celu
akceptacji –> aplikacja zapisuje dane dotyczące zgody i działa dalej jak zwykle
Użytkownik klika „Odrzuć”: aplikacja wywołuje punkt końcowy API TV „Feedback” dla
odrzucenia –> aplikacja zapisuje dane dotyczące zgody i działa dalej jak zwykle
Użytkownik klika Ustawienia: aplikacja wyświetla kod QR
Aplikacja wywołuje punkt końcowy API TV „QR-Status” co 3 sekundy w celu aktualizacji statusu
Gdy status QR jest „zakończony” (lub użytkownik kliknie przycisk „Wstecz”), aplikacja zapisuje dane zgody i działa normalnie

Punkt końcowy AppStart

Adres URL punktu końcowego AppStart można znaleźć w obszarze logowania ConsentManager (patrz sekcja „Konfiguracja” powyżej). Punkt końcowy zwróci obiekt JSON i poda dwie informacje:

Czy interfejs zgody ma być wyświetlany
, czy nie? Sygnalizuje to właściwość „displayLayer” o wartości „true” (wyświetl interfejs zgody) lub „false” (nie ma potrzeby wyświetlania interfejsu zgody).
Jakiego stylu należy użyć, jeśli musisz/chcesz wyświetlić interfejs
zgody? Wskazują na to właściwości „display”

Wywołanie punktu końcowego AppStart

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

Parametr	Opis
`&l=…`	(opcjonalnie, zalecane) Żądany język wyświetlania. Np. &l=DE lub &l=EN-US. API zwróci teksty w tym języku.
`&appid=…`	(opcjonalnie, zalecane) Identyfikator aplikacji. Np. &appid=123456 lub &appid=my-app-name
`&cs=…`	(opcjonalne, wymagane, jeśli występuje) Zapisany ciąg znaków zgody z ostatniego wyboru użytkownika. Ciąg znaków zgody jest przekazywany do aplikacji przez: a) punkt końcowy Feedback w ramach właściwości „consentstring” lub b) punkt końcowy QR-Status w ramach właściwości „feedbackobject.consentstring”
`&ip=…`	(opcjonalnie) Adres IP użytkownika, który ma być użyty do celów geolokalizacji. Jeśli nie przekazano adresu IP, używany jest adres IP źródła żądania. Np. &ip=123.123.123.123

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

Stylizacja interfejsu zgody

Zwłaszcza w przypadku stosowania standardów branżowych, takich jak IAB TCF lub IAB GPP, firma consentmanager jest zobowiązana zgodnie z polityką do zapewnienia, że jej klienci przestrzegają określonych standardów. Musimy zatem wymagać od wszystkich klientów, aby do tworzenia interfejsu zgody wykorzystywali informacje dostarczane za pośrednictwem punktu końcowego AppStart.

Ważne: Aby zapewnić przestrzeganie wszystkich zasad, wymagamy od wszystkich klientów przesłania do zatwierdzenia przykładowego zrzutu ekranu z interfejsem zgody, który stworzyli.

Zgodność z IAB TCF i GPP

Aby zapewnić zgodność z IAB TCF i GPP, musimy wymagać od wszystkich klientów korzystania z elementów dostarczanych przez AppStart Endpoint, a konkretnie:

Interfejs zgody musi wyświetlać nagłówek i tekst na pierwszym ekranie. Nagłówek i tekst muszą być pobierane z API i wyświetlane w całości. Nie mogą być zasłonięte, skrócone ani w inny sposób niewidoczne.
Interfejs zgody musi wyświetlać przyciski wskazane przez API oraz tekst etykiety podany przez API. Przyciski muszą być natychmiast widoczne i nie mogą być zasłonięte.
Interfejs zgody musi wyświetlać linki wskazane przez API. Linki muszą być dostępne dla klienta, ale nie muszą być od razu widoczne. W każdym razie zalecamy, aby wszystkie linki były zawsze widoczne.
Interfejs zgody powinien wykorzystywać kolory wskazane przez API. Jeśli nie jest to możliwe ze względu na ograniczenia urządzenia, interfejs zgody musi być zaprojektowany w taki sposób, aby wszystkie przyciski miały takie samo znaczenie.

Punkt końcowy informacji zwrotnej

Odpowiedź punktu końcowego AppStart będzie zawierała dwa adresy URL poprzez „feedback.accept” i „feedback.reject”. Adresy te powinny zostać wywołane przez aplikację, gdy użytkownik zdecyduje się zaakceptować lub odrzucić ustawienia prywatności.

Wywołanie punktu końcowego opinii

Adresy URL punktów końcowych informacji zwrotnej są już wstępnie skonstruowane przez wywołanie API punktu końcowego AppStart i nie trzeba ich zmieniać ani do nich niczego dodawać. Proszę wywołać prawidłowy adres URL odpowiadający wyborowi użytkownika.

Odpowiedź punktu końcowego

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

Kod QR – punkt docelowy

W przypadku, gdy użytkownik kliknie na ustawienia, aplikacja wyświetli drugi ekran zgody z kodem QR (i opcjonalnym adresem URL). Użytkownik zeskanuje wówczas 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ź punktu końcowego AppStart będzie zawierała adres URL poprzez „customsettings.statusurl”. Adres ten powinien zostać wywołany przez aplikację po wyświetleniu kodowi QR użytkownikowi. Zalecamy wywoływanie adresu co 3 sekundy w celu sprawdzenia aktualizacji.

Wywołanie punktu końcowego opinii

Adres URL punktu końcowego kodu QR jest już wstępnie skonstruowany przez wywołanie API punktu końcowego AppStart i nie trzeba go zmieniać ani do niego niczego dodawać. Proszę wywoływać co 3 sekundy, podczas 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 zgód

Gdy użytkownik dokona wyboru lub zakończy się proces skanowania kodu QR, API zwróci obiekt z informacją zwrotną zawierającą wszystkie szczegóły. Zalecamy twórcom aplikacji zapisanie pełnego obiektu.

Obsługa błędów

Ponieważ aplikacja opiera się na wywołaniu zewnętrznego API, zalecamy różne strategie obsługi błędów, aby uniknąć problemów i negatywnych wrażeń użytkownika:

Błędy
API W przypadku, gdy API zwraca nieoczekiwany kod statusu HTTP (np. 4xx, 5xx lub 6xx), aplikacja powinna potraktować to jako błąd. Aplikacja powinna przejść do stanu lub logiki domyślnej i pominąć kolejne kroki procesu. W przypadkach, gdy wysyłany jest kod statusu HTTP 3xx lub w inny sposób sygnalizowana jest zmiana lokalizacji, aplikacja powinna przejść do sygnalizowanego adresu URL (Uwaga: zastosuj regułę maksymalnego śledzenia, aby uniknąć pętli nieskończonych).
Limity czasu
Wszystkie wywołania API powinny mieć maksymalny limit czasu, np. 15 sekund. Jeśli API nie odpowie w tym czasie, należy uznać je za niedostępne. Aplikacja powinna przejść do stanu lub logiki domyślnej i pominąć kolejne kroki procesu.
Walidacja
SSL Szczególnie w przypadku starszych urządzeń walidacja SSL może powodować problemy, gdy wersje certyfikatów lub metody szyfrowania nie są już obsługiwane. W takim przypadku twórcy aplikacji mogą wywoływać punkty końcowe API przez http zamiast https.
Błędy
parsowania Wszystkie punkty końcowe API zwracają obiekty JSON jako ciągi znaków zakodowane w formacie UTF-8. Podczas parsowania ciągu znaków aplikacja powinna sprawdzić, czy parsowanie przebiegło zgodnie z oczekiwaniami. Ponadto aplikacja powinna:
- Traktuj wszystkie właściwości wszystkich obiektów jako opcjonalne i zawsze sprawdzaj, czy właściwość istnieje, zanim uzyskasz do niej dostęp.
- Sprawdź, czy zwracana wartość właściwości jest typu oczekiwanego (np. string, bool lub integer).
- Bądź elastyczny w kwestii struktury obiektów. Niektóre obiekty mają strukturę dynamiczną i mogą występować z większą lub mniejszą liczbą właściwości. Jeśli aplikacja nie rozpoznaje danej właściwości, powinna ją zignorować.
Błąd
statusu kodu QR W przypadkach, gdy punkt końcowy statusu kodu QR zwraca status=error, aplikacja powinna przerwać zbieranie zgody i wznowić działanie jak zwykle.
Kod QR porzucony

W przypadkach, gdy wyświetlany jest kod QR, ale przez dłuższy czas nie obserwuje się zmiany statusu, aplikacja powinna powrócić do początkowego interfejsu zgody (pierwszy ekran) i umożliwić użytkownikowi ponowny wybór. Zalecamy maksymalny czas oczekiwania wynoszący 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ć jednoczesną aktywność wielu wersji.