Motywacja
Jak wspomnieliśmy w opisie, w zależności od przypadku użycia, który operator chce obsługiwać, organ ochrony danych musi wdrożyć interfejs Google Mobile Data Plan Share API i interfejs Data DataAgent API. W tym dokumencie opisujemy interfejs API Data Data Agent, którego Google używa do identyfikowania planów mobilnej transmisji danych użytkownika oraz pobierania informacji o tych abonamentach i abonamentach.
Uwierzytelnianie
Aby można było wywołać GTAF, organ ochrony danych musi uwierzytelnić GTAF. W ramach procesu rejestracji operatora sprawdzimy poprawność certyfikatu SSL DPA. Obecnie wymagamy używania protokołu OAuth2 do uwierzytelniania wzajemnego. Szczegółowe informacje o uwierzytelnianiu organu ochrony danych przez GTAF znajdziesz w artykule Uwierzytelnianie agenta usługi Data Plan.
Internacjonalizacja
Żądania GTAF do Aneksu o przetwarzaniu danych obejmują nagłówek Accept-Language określający język, w którym powinny znajdować się ciągi zrozumiałe dla człowieka (np. opis planu). Odpowiedzi DPA (PlanStatus, PlanOffers) zawierają wymagane pole languageCode, którego wartość to kod języka BCP-47 (np. "en-US") odpowiedzi.
Jeśli Aneks o przetwarzaniu danych nie obsługuje języka, o który prosi użytkownik, może wybrać język domyślny i wybrać odpowiedni język w polu languageCode.
Opis interfejsu API
GTAF używa klucza użytkownika, który identyfikuje subskrybenta operatora podczas wysyłania zapytania do organu ochrony danych. Gdy GTAF wysyła zapytania do organu ochrony danych w imieniu aplikacji, które mają dostęp do MSISDN, GTAF MAY może używać MSISDN. Ogólnie rzecz biorąc, proponowany interfejs Data Plan Agent API obejmuje te komponenty:
- Mechanizm zapytań o stan planu danych użytkowników.
- Mechanizm zapytań do organu ochrony danych o ofertach pakietu danych dla użytkownika.
- Mechanizm wprowadzania zmian w pakiecie danych użytkownika (np. zakup nowego abonamentu).
- Mechanizm udostępniania CPID, który może służyć do wysyłania powiadomień do użytkowników.
- Mechanizm udostępniania użytkownikom informacji o tym, czy chcą się zarejestrować w naszej usłudze.
Reszta dokumentu zawiera szczegółowe informacje o każdym z tych komponentów interfejsu API. O ile nie stwierdzono inaczej, cała komunikacja MUSI być przeprowadzana przez HTTPS (z ważnym certyfikatem SSL DPA). W zależności od obsługiwanych funkcji operator może wdrożyć wszystkie lub niektóre z tych komponentów API.
Interakcja GTAF-DPA
Rysunek 4. Przebieg rozmowy pozwalający uzyskać informacje o abonamencie użytkownika.
Rysunek 4 przedstawia przepływ połączeń powiązany z klientem, który wysyła zapytania o stan abonamentu użytkownika i inne informacje. Ten przepływ wywołań jest udostępniany w przypadku wywołań interfejsu API wywoływanych przez klienta w UE.
- Klient żąda stanu abonamentu danych lub innych informacji, wywołując prywatny interfejs API Google. Klient zawiera klucz użytkownika w żądaniu wysłanym do GTAF.
- GTAF używa klucza użytkownika i identyfikatora klienta do wysyłania zapytań do operatora. Obsługiwane identyfikatory klienta to mobiledataplan i youtube. Gdy organ ochrony danych odbierze połączenie z jednym z tych identyfikatorów klienta, MUSI odpowiadać na informacje o pakiecie, które może wykorzystać klient.
- GTAF zwraca wymagane dane klientowi, a informacje o abonamencie są przechowywane w pamięci podręcznej przez GTAF do czasu wygaśnięcia określonego przez organ ochrony danych.
Kroki 1 i 3 na rysunku 4 są prywatnymi interfejsami API Google, więc nie są szczegółowo opisane. Krok 2 to publiczny interfejs API opisany poniżej. Podczas wyświetlania tych wywołań interfejsu API GTAF DPA MUSI przestrzegać nagłówka HTTP Cache-Control: no-cache.
Sprawdzanie stanu planu danych
GTAF wysyła to żądanie HTTP, aby uzyskać stan planu:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Klient, w imieniu którego GTAF kontaktuje się z organem ochrony danych, jest rozpoznawany za pomocą CLIENT_ID. W zależności od umowy między klientem Google a operatorem organ ochrony danych może dostosować odpowiedź do GTAF. W przypadku sukcesu organ ochrony danych MUSI zwrócić kod HTTP 200 OK i treść odpowiedzi reprezentującą PlanStatus. W przypadku błędów zapoznaj się z opisem sytuacji błędów.
{
"plans": [{
"planName": "ACME1",
"planId": "1",
"planCategory": "PREPAID",
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"planModules": [{
"moduleName": "Giga Plan", // req.
"trafficCategories": ["GENERIC"],
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"overUsagePolicy": "BLOCKED",
"maxRateKbps": "1500",
"description": "1GB for a month", // req.
"coarseBalanceLevel": "HIGH_QUOTA"
}]
}],
"languageCode": "en-US", // req.
"expireTime": "2018-06-14T08:41:27-07:00", // req.
"updateTime": "2018-06-07T07:41:22-07:00", // req.
"title": "Prepaid Plan"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
W przypadku abonamentów po wykonaniu usługi expirationTime MUSI być datą powtarzania abonamentu (tj. po odświeżeniu lub ponownym przesłaniu danych).
Każdy moduł planu może zawierać wiele kategorii ruchu modułu planu (PMTCs)aby modelować sytuację, w której moduł jest udostępniany wielu aplikacjom (np. 500 MB
na gry i muzykę). Poniższe prognozy dotyczące przejrzystości i zgody na przetwarzanie danych są wstępnie zdefiniowane: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. oczekuje się, że operatorzy skontaktują się z poszczególnymi zespołami Google, aby uzgodnić zestaw kategorii ruchu i ich semantykę odpowiednią dla poszczególnych aplikacji Google.
Zapytania dotyczące planu abonamentowego
GTAF wyświetla następujące żądanie HTTP, aby uzyskać oferty abonamentu od operatora:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Klient, w imieniu którego GTAF kontaktuje się z organem ochrony danych, jest rozpoznawany za pomocą CLIENT_ID. W zależności od umowy między klientem Google a operatorem organ ochrony danych może dostosować odpowiedź do GTAF. Opcjonalny parametr kontekstu dostarcza kontekst aplikacji, w której przesyłane jest żądanie. Zwykle jest to ciąg znaków, który aplikacja przekazuje do operatora przez GTAF.
W przypadku powodzenia organ ochrony danych MUSI zwrócić kod HTTP 200 OK i treść odpowiedzi reprezentującą PlanOffer. W przypadku błędów znajdziesz w sekcji zgłoszeń.
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"expireTime": "2019-03-04T00:06:07Z" // req.
}
Kolejność planów danych w tablicy offers może decydować o kolejności, w jakiej plany danych są wyświetlane użytkownikom. Jeśli aplikacja może wyświetlać tylko plany x ze względu na interfejs lub inne ograniczenia, a odpowiedź zawiera plany y > x, ale widoczne są tylko pierwsze plany x. GTAF udostępnia maksymalnie 50 abonamentów, jeśli zapytanie o oferty to moduł mobilnej transmisji danych, który jest częścią Usług Google Play. Gwarantuje to wygodę użytkownikom
usług Google Play.
Oferty sprzedaży dodatkowej mają parametr filterTag jako opcjonalny parametr, czyli tablicę tagów dołączonych do każdego planu. Wszystkie te filtry powinny być zgodne z tagami, które są obiektem w filtrze. Filter to obiekt pierwszego poziomu zawierający
element tpt.tag, displaytext="">.. Filter to skonsolidowana lista filtrów, które będą renderowane w interfejsie użytkownika. Użytkownik może filtrować dane, klikając opcję DisplayText. Tag odpowiadający parametrowi displayText służy do filtrowania ofert.</tag,>
Pamiętaj, że operator MUSI mieć mechanizm realizacji żądania zakupu dowolnej oferty rozszerzonej dla użytkownika. Mechanizm, za pomocą którego użytkownik będzie obciążany za każdy zakup, można przekazać GTAF za pomocą opcji formOfPayment w odpowiedzi.
Zakup danych
Interfejs API planu zakupów określa sposób, w jaki GTAF może kupować plany przez organ ochrony danych. GTAF inicjuje transakcję zakupu jednego pakietu danych dla organu ochrony danych. Żądanie musi zawierać unikalny identyfikator transakcji (transactionId), aby można było śledzić żądania i uniknąć wykonywania zduplikowanych transakcji. Aneks o przetwarzaniu danych musi reagować na powodzenie lub niepowodzenie.
Żądanie transakcji
Po otrzymaniu żądania od klienta GTAF wysyła żądanie POST do Aneksu o przetwarzaniu danych. Adres URL żądania to:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
gdzie userKey to CPID lub MSISDN. Treść żądania to wystąpienie TransactionRequest, które zawiera te pola:
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
Odpowiedź transakcji
Aneks DPA SHALL generuje odpowiedź 200-OK tylko w przypadku udanej transakcji lub transakcji w kolejce. W przypadku błędów zapoznaj się z opisem sytuacji błędów. W przypadku transakcji w kolejce Aneks o przetwarzaniu danych wypełni tylko stan transakcji i pozostawi pozostałe pola odpowiedzi. Organ ochrony danych musi zwrócić GTAF z odpowiedzią, gdy transakcja zostanie przetworzona. Treść odpowiedzi to wystąpienie parametru TransactionResponse, które zawiera te informacje:
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
Jeśli brakuje planActivationTime, GTAF SHALL zakłada, że abonament został aktywowany.
Zarejestruj CPI
Gdy klient, który obsługuje powiadomienia, otrzyma nowy CPId z punktu końcowego CPID, rejestruje go w GTAF, jeśli warunki klienta na to zezwalają. Jeśli klient zarejestruje CPID za pomocą GTAF, to GTAF zarejestruje go w Aneksie o przetwarzaniu danych za pomocą tego wywołania interfejsu API:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
gdzie userKey to CPId, a jedynym obsługiwanym identyfikatorem klienta CLIENT_ID jest mobiledataplan. Treść żądania to instancja RegisterCpidRequest zawierająca czas, po którym nie można użyć CPID do wysyłania powiadomień, i wygląda tak:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Ten interfejs API jest przeznaczony tylko dla operatorów, którzy chcą obsługiwać moduł mobilnej transmisji danych w Usługach Google Play. Aby rzetelne wysyłanie powiadomień do użytkownika, organ ochrony danych może przechowywać najnowszą zarejestrowaną CPI dla każdego użytkownika. Zapoznaj się z artykułem Wybieranie CPI, by dowiedzieć się, jak wysyłać powiadomienia do CPI.
Organ ochrony danych wygeneruje odpowiedź 200 OK, jeśli identyfikator DPA zostanie powiązany z użytkownikiem i trwale go przechowuje. W przypadku błędów znajdziesz w sekcji zgłoszeń.
Zgoda
GTAF może wysłać poniższe żądanie, aby przekazać operatorowi preferencje dotyczące zgody użytkownika.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
gdzie userKey to CPID lub MSISDN. Treść żądania to wystąpienie SetConsentStatusRequest. Jeśli operacja się uda, treść odpowiedzi powinna być pusta.
Każde połączenie od GTAF do organu ochrony danych odbywa się zgodnie z warunkami korzystania z klienta Google. W zależności od aplikacji, które organ ochrony danych chce wspomóc. Jeśli organ ochrony danych zdecyduje się na wdrożenie interfejsu API do uzyskiwania zgody, musi on mieć aktualny stan zgody każdego użytkownika. Aby dowiedzieć się, jak korzystać z informacji o stanie zgody, przeczytaj artykuł Wybieranie CPI.
W przypadku sukcesu organ ochrony danych MUSI zwrócić kod HTTP 200 bez wartości z pustą treścią. W przypadku błędów zapoznaj się z opisem sytuacji błędów.