Interfejs API agenta Data Data

Motywacja

Jak wspomnieliśmy w omówieniu, w zależności od przypadków użycia, które operator chce obsługiwać, dostawca usług danych musi wdrożyć kombinację interfejsu Google Mobile Data Plan Sharing API i interfejsu Data Plan Agent API. W tym dokumencie opisujemy interfejs Data Plan Agent API, którego Google będzie używać do identyfikowania abonamentów na mobilną transmisję danych użytkownika, pobierania informacji o tych abonamentach i kupowania pakietów danych.

Uwierzytelnianie

Zanim GTAF będzie mogła zadzwonić, DPA musi ją uwierzytelnić. W ramach procesu wdrażania operatora sprawdzimy ważność certyfikatu SSL DPA. Obecnie WYMAGAMY używania protokołu OAuth2 do wzajemnego uwierzytelniania. Szczegółowe informacje o tym, jak GTAF uwierzytelnia się w DPA, znajdziesz w artykule Uwierzytelnianie agenta planu danych.

Internacjonalizacja

Żądania GTAF wysyłane do DPA zawierają nagłówek Accept-Language wskazujący język, w którym mają być wyświetlane ciągi znaków czytelne dla człowieka (np. opisy planów). Dodatkowo odpowiedzi interfejsu DPA (PlanStatus, PlanOffers) zawierają wymagane pole languageCode, którego wartością jest kod języka BCP-47 (np. „en-US”) odpowiedzi.

Jeśli platforma DPA nie obsługuje języka, o który prosi użytkownik, może użyć języka domyślnego i wskazać go w polu languageCode.

Opis interfejsu API

GTAF używa klucza użytkownika, który identyfikuje subskrybenta operatora, podczas wysyłania zapytań do platformy DPA operatora. Gdy GTAF wysyła zapytanie do DPA w imieniu aplikacji, które mają dostęp do numeru MSISDN, MOŻE używać tego numeru. Na najwyższym poziomie proponowany interfejs Data Plan Agent API składa się z tych komponentów:

  1. Mechanizm sprawdzania stanu pakietu danych użytkownika.
  2. Mechanizm wysyłania do dostawcy danych zapytań o oferty pakietów danych dla użytkownika.
  3. Mechanizm wprowadzania zmian w planie danych użytkownika (np. zakup nowego planu).
  4. Mechanizm udostępniania identyfikatorów CPID, których można używać do wysyłania powiadomień do użytkowników.
  5. Mechanizm udostępniania wyborów użytkowników dotyczących rejestracji w naszej usłudze.

W pozostałej części tego dokumentu znajdziesz szczegółowe informacje o każdym z tych komponentów interfejsu API. O ile nie zaznaczono inaczej, cała komunikacja MUSI odbywać się przez protokół HTTPS (z prawidłowym certyfikatem SSL DPA). W zależności od obsługiwanych funkcji operator MOŻE wdrożyć wszystkie lub tylko niektóre z tych komponentów interfejsu API.

GTAF-DPA Interaction

GTAF-DPA Interaction

Rysunek 4. Schemat połączenia umożliwiający wysyłanie próśb o informacje o pakiecie danych użytkownika i ich otrzymywanie.

Ilustracja 4 przedstawia przepływ wywołań związany z zapytaniem klienta o stan abonamentu użytkownika i inne informacje o abonamencie. Ten przepływ wywołań jest wspólny dla wywołań interfejsu API wywoływanych przez klienta na urządzeniu UE.

  1. Klient wysyła żądanie dotyczące stanu pakietu danych lub innych informacji, wywołując prywatny interfejs API Google. Klient dołącza do żądania wysyłanego do GTAF klucz użytkownika.
  2. GTAF używa klucza użytkownika i identyfikatora klienta do wysyłania zapytań do platformy DPA operatora. Obsługiwane identyfikatory klientów to mobiledataplan i youtube. Gdy DPA otrzyma wywołanie z jednym z tych identyfikatorów klienta, MUSI odpowiedzieć informacjami o abonamencie, które mogą być używane przez klienta.
  3. GTAF zwraca klientowi żądane informacje, a informacje o planie są buforowane przez GTAF do czasu wygaśnięcia określonego przez DPA.

Kroki 1 i 3 na rysunku 4 to prywatne interfejsy API Google, dlatego nie są one dalej opisywane. Krok 2 to publiczny interfejs API opisany poniżej. Podmiot przetwarzający dane MUSI respektować nagłówek HTTP Cache-Control: no-cache podczas obsługi tych wywołań interfejsu API z GTAF.

Sprawdzanie stanu pakietu danych

Aby uzyskać stan planu, GTAF wysyła to żądanie HTTP:

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 identyfikowany za pomocą parametru CLIENT_ID. W zależności od umowy między klientem Google a operatorem DPA może dostosować odpowiedź do GTAF. W przypadku powodzenia DPA MUSI zwrócić kod stanu HTTP 200 OK z treścią odpowiedzi reprezentującą PlanStatus. W przypadku błędów zapoznaj się z sekcją Error Cases, aby dowiedzieć się, jakiej odpowiedzi możesz się spodziewać.

{
  "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 z płatnością z dołu expirationTime MUSI być datą odnowienia abonamentu (czyli datą odświeżenia lub ponownego załadowania pakietu danych).

Każdy moduł abonamentu może zawierać wiele kategorii ruchu modułu abonamentu (PMTCs), aby modelować przypadek, w którym moduł abonamentu jest współdzielony przez wiele aplikacji, np. 500 MB (w przypadku gier i muzyki). Wstępnie zdefiniowane są te PMTC: 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ę, które są istotne w przypadku różnych aplikacji Google.

Wysyłanie zapytań dotyczących ofert pakietów

GTAF wysyła to żądanie HTTP, aby uzyskać od operatora oferty abonamentów:

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 identyfikowany za pomocą parametru CLIENT_ID. W zależności od umowy między klientem Google a operatorem DPA może dostosować odpowiedź do GTAF. Opcjonalny parametr kontekstu zawiera kontekst aplikacji, w którym wysłano żądanie. Zwykle jest to ciąg znaków, który aplikacja przekazuje operatorowi za pomocą GTAF.

W przypadku powodzenia platforma DPA MUSI zwrócić kod HTTP 200 OK z treścią odpowiedzi reprezentującą PlanOffer. Oczekiwane odpowiedzi w przypadku błędów znajdziesz w sekcji Error Cases (Przypadki błędów).

{
    "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ść abonamentów w tablicy offers MOŻE określać kolejność, w jakiej są one prezentowane użytkownikom. Jeśli aplikacja może wyświetlać tylko x abonamentów z powodu ograniczeń interfejsu lub innych ograniczeń, a odpowiedź zawiera y > x abonamentów, należy wyświetlić tylko pierwsze x abonamentów. GTAF udostępnia tylko do 50 abonamentów, jeśli aplikacją wysyłającą zapytanie o oferty jest moduł pakietu danych mobilnych, który jest częścią Usług Google Play. Dzięki temu użytkownicy Usług Google Play mogą korzystać z nich w wygodny sposób.

Oferty dodatkowej sprzedaży mają parametr opcjonalny filterTags, który jest tablicą tagów dołączonych do każdego planu. Wszystkie te tagi filterTags powinny pasować do tagu, który jest obiektem w filtrze. Filter to obiekt pierwszego poziomu, który zawiera krotkę<tag, displaytext="">. Filter to skonsolidowana lista filtrów, które będą renderowane w interfejsie. Użytkownik może filtrować wyniki, klikając DisplayText. Tag odpowiadający tekstowi displayText służy do filtrowania ofert.</tag,>

Pamiętaj, że operator MUSI mieć mechanizm realizacji prośby o zakup w przypadku każdej oferty skierowanej do użytkownika. Mechanizm, za pomocą którego użytkownik zostanie obciążony za zakup, można przekazać do GTAF za pomocą opcji formOfPayment w odpowiedzi.

Zakup danych

Interfejs Purchase Plan API określa, w jaki sposób GTAF może kupować pakiety za pomocą DPA. GTAF inicjuje transakcję zakupu jednego pakietu danych dla DPA. Żądanie MUSI zawierać unikalny identyfikator transakcji (transactionId), który umożliwia śledzenie żądań i zapobiega wykonywaniu zduplikowanych transakcji. Organ ochrony danych MUSI odpowiedzieć, wysyłając komunikat o sukcesie lub niepowodzeniu.

Żądanie transakcji

Gdy GTAF otrzyma żądanie od klienta, wysyła żądanie POST do DPA. 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 instancja TransactionRequest, która 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

DPA GENERUJE odpowiedź 200-OK TYLKO W PRZYPADKU SKUTECZNIE ZREALIZOWANEJ LUB OCZEKUJĄCEJ NA REALIZACJĘ TRANSAKCJI. W przypadku błędów oczekiwane odpowiedzi znajdziesz w sekcji Przypadki błędów. W przypadku transakcji w kolejce dostawca platformy danych powinien wypełnić tylko stan transakcji, a pozostałe pola w odpowiedzi pozostawić puste. Po obsłużeniu transakcji w kolejce organ ochrony danych MUSI wywołać zwrotnie interfejs GTAF, aby przekazać odpowiedź. Treść odpowiedzi to instancja TransactionResponse, która 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 parametru planActivationTime, GTAF uzna, że subskrypcja została aktywowana.

Rejestracja identyfikatora CPID

Gdy klient obsługujący powiadomienia otrzyma nowy identyfikator CPID z punktu końcowego CPID , zarejestruje go w GTAF, jeśli zezwalają na to warunki klienta. Jeśli klient zarejestruje identyfikator CPID w GTAF, GTAF zarejestruje go w DPA za pomocą tego wywołania interfejsu API:

POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID

gdzie userKey to identyfikator CPID, a jedynym obsługiwanym identyfikatorem CLIENT_ID jest mobiledataplan. Treść żądania jest instancją elementu RegisterCpidRequest i zawiera czas, po którym identyfikator CPID nie może być używany do wysyłania powiadomień. Wygląda on tak:

{"staleTime": "2017-01-29T01:00:03.14159Z"}

Ten interfejs API jest przeznaczony tylko dla operatorów, którzy chcą obsługiwać moduł Mobile Data Plan w Usługach Google Play. Aby niezawodnie wysyłać powiadomienia do użytkownika, dostawca platformy danych MOŻE przechowywać najnowszy zarejestrowany identyfikator CPID każdego użytkownika. Więcej informacji o tym, jak używać zarejestrowanego identyfikatora CPID do wysyłania powiadomień, znajdziesz w artykule Wybieranie identyfikatora CPID.

Jeśli DPA pomyślnie powiąże identyfikator CPID z użytkownikiem i trwale go zapisze, wygeneruje odpowiedź 200-OK. Oczekiwane odpowiedzi w przypadku błędów znajdziesz w sekcji Error Cases (Przypadki błędów).

GTAF MOŻE wysłać to żądanie, aby przekazać operatorowi preferencje użytkownika dotyczące zgody.

POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID

gdzie userKey to CPID lub MSISDN. Treść żądania jest instancją elementu SetConsentStatusRequest. Jeśli operacja się uda, treść odpowiedzi powinna być pusta.

Każde wywołanie z GTAF do DPA jest zgodne z warunkami usługi klienta Google, który je wykonuje. W zależności od aplikacji, które ma obsługiwać DPA, operator decyduje, czy ma zaimplementować ten interfejs API. Jeśli podmiot przetwarzający dane zdecyduje się wdrożyć interfejs API do uzyskiwania zgody użytkowników, MUSI przechowywać najnowszy stan zgody każdego użytkownika. Więcej informacji o korzystaniu z informacji o stanie zgody znajdziesz w artykule Wybieranie identyfikatora CPID.

W przypadku powodzenia platforma DPA MUSI zwrócić kod HTTP 200 OK z pustą treścią odpowiedzi. Oczekiwane odpowiedzi w przypadku błędów znajdziesz w sekcji Przypadki błędów.