Pierwsze kroki z udostępnianiem abonamentu na mobilną transmisję danych

Terminologia

  • GTAF: Google Traffic Application Function. Usługa Google, która implementuje interfejs Data Plan Sharing API i wchodzi w interakcje z dostawcami danych w imieniu aplikacji Google. Aplikacje Google mogą wysyłać do GTAF zapytania o informacje o abonamencie użytkownika. Jeśli aplikacje Google zarejestrują się w GTAF, GTAF może wysyłać aktualizacje dotyczące pakietu danych użytkownika.
  • MSISDN: Mobile Station International Subscriber Directory Number, czyli numer jednoznacznie identyfikujący subskrypcję w sieci komórkowej. Bardziej znany jako numer telefonu.
  • Punkt końcowy CPID: usługa wdrożona przez operatorów sieci komórkowych, która generuje identyfikator abonamentu operatora (CPID), którego można użyć do wyszukania informacji o abonamencie użytkownika. CPID umożliwia aplikacji wysyłanie zapytań o szczegóły pakietu danych użytkownika bez uzyskiwania dostępu do jego numeru MSISDN. Poniżej opisujemy procedurę generowania identyfikatorów CPID.
  • Klucz użytkownika: klucz użytkownika to ciąg znaków, który może służyć do identyfikowania pakietu danych użytkownika. Może to być identyfikator CPID lub numer MSISDN w przypadku aplikacji, które mają do niego dostęp.
  • DPA: Data Plan Agent, usługa wdrożona przez operatorów sieci komórkowych, która udostępnia GTAF informacje o pakietach danych użytkowników. Dostawca danych może udostępniać informacje usłudze GTAF, wysyłając dane za pomocą interfejsu Google Mobile Data Plan Sharing API i wdrażając interfejs Data Plan Agent API. Platforma DPA może opcjonalnie pełnić też funkcję punktu końcowego CPID.
  • UE: User Equipment, urządzenie używane przez użytkownika.

Język wymagań

Słowa kluczowe „MUSI”, „NIE MOŻE”, „WYMAGANE”, „POWINIEN”, „NIE POWINIEN”, „ZALECANE”, „MOŻE” i „OPCJONALNE” w tych przewodnikach należy interpretować zgodnie z opisem w RFC 2119.

Udostępnianie mobilnej transmisji danych

Ogólnie udostępnianie pakietu mobilnej transmisji danych składa się z 3 części:

  1. Mechanizm ustalania i aktualizowania identyfikatora planu operatora (CPID), który może być używany jako klucz użytkownika. Aplikacje, które mają dostęp do numeru MSISDN, mogą go używać jako klucza użytkownika.
  2. Interfejs Google Mobile Data Plan Sharing API, który umożliwia DPA wysyłanie do Google informacji o abonamencie użytkownika na mobilną transmisję danych. Jeśli np. dostawca platformy chce powiadomić użytkownika o ofercie, może wysłać powiadomienie do GTAF, która z kolei powiadomi użytkownika.
  3. Interfejs API agenta planu danych wdrożony przez dostawcę planu danych, który umożliwia GTAF wysyłanie zapytań do dostawcy planu danych o informacje o planie danych użytkownika. Jeśli na przykład aplikacja chce wyświetlić użytkownikowi aktualne saldo pakietu danych, może wysłać zapytanie do GTAF, który z kolei wyśle zapytanie do DPA.

W dalszej części tej strony znajdziesz terminologię dotyczącą planów transmisji danych oraz szczegółowe informacje o tym, jak uzyskać CPID. Poniżej znajdziesz specyfikację interfejsu Google Mobile Data Plan Sharing API i interfejsu Data Plan Agent API.

Terminologia dotycząca pakietów danych

Schemat planStatus zdefiniowany w interfejsie API MUSI umożliwiać reprezentowanie planów transmisji danych oferowanych przez operatorów użytkownikom. Interfejs API umożliwia definiowanie pakietów danych, w których użytkownicy są obciążani według innej stawki za cały ruch do określonego zestawu adresów URL (np. cały ruch do *.acmefake.com jest obciążany według innej stawki). Interfejs API obsługuje też pakiety danych, które oferują różne stawki za określone typy działań w aplikacji. Nazywamy je pakietami danych sub-app. Przykładem pakietu danych sub-app może być bezpłatne (czyli o zerowej stawce) przeglądanie filmów, podczas gdy oglądanie filmów w aplikacji powoduje odliczenie danych z konta abonenta. Aplikacja wideo MUSI mieć możliwość uzyskania tych informacji podczas wysyłania zapytania o informacje o pakiecie danych.

Wprowadzamy tu kilka terminów związanych z pakietami danych. Na rysunku 1 przedstawiamy przykłady pakietów danych, które ilustrują koncepcje, które chcemy uwzględnić.

Abonament na transmisję danych: pakiet usług mobilnych najwyższego poziomu, który kupuje subskrybent. Może to być prosta oferta, np. „10 GB danych mobilnych na 30 dni”, lub zbiór komponentów, czyli modułów. Pakiet danych:

  • Nazwa pakietu danych, np. „ACME Red”.
  • Identyfikator pakietu danych, używany do odwoływania się do pakietu, np. podczas zakupów.
  • Czas wygaśnięcia, czyli data wygaśnięcia pakietu danych.
  • Kategoria abonamentu, czyli czy jest to abonament przedpłacony czy abonament z płatnością z dołu.

Moduł abonamentu: komponent abonamentu na transmisję danych. Moduł planu zawiera:

  • Nazwa modułu, np. „Bezpłatne wieczory filmowe”.
  • Maksymalna szybkość, czyli przepustowość oferowana użytkownikowi przez ten moduł.
  • Elastyczne przedziały czasowe, czyli przedziały czasowe, w których użytkownikowi można zaoferować zniżkę.

  • Kategoria ruchu modułu planu (PMTC), czyli opis ruchu danych, do którego moduł ma zastosowanie. PMTC może być tak ogólny jak *cały ruch internetowy *lub tak szczegółowy jak ruch generowany/wykorzystywany przez co najmniej 1 aplikację, witrynę lub nawet ścieżki użytkownika w ramach jednej aplikacji. Przykłady tego typu to „nieograniczona muzyka”, „pakiet danych wideo 100 MB (VDP)”, „nieograniczone dane do gier” i „nieograniczone przeglądanie filmów”. Aby ułatwić określanie PMTC, zdefiniowaliśmy te PMTC: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING i PMTC_UNSPECIFIED.

  • Limit danych lub limit czasu: po aktywacji moduł planu wygasa, gdy zostanie osiągnięty limit danych lub limit czasu (w przypadku planów opartych na czasie, np. 600 minut dostępu do internetu w ciągu najbliższych 7 dni). Na ilustracji 1 poniżej abonent może kupić moduł planu w ramach „ACME Blue”, który zapewnia 1 GB ruchu użytkowników ogólnych. Musi on zostać wykorzystany w ciągu tygodnia od aktywacji, zanim wygaśnie.

Przykładowy abonament interfejsu Data Plan API

Rysunek 1. Przykładowe pakiety danych.

Ustalanie identyfikatora CPID

GTAF używa klucza użytkownika do identyfikowania subskrybenta podczas komunikacji z platformą DPA. Aplikacje, które mają dostęp do numeru MSISDN użytkownika, mogą używać go jako klucza user_key. Z drugiej strony aplikacje, które nie mają dostępu do numeru MSISDN, muszą ustalić identyfikator planu operatora (CPID) bez wykrywania numeru MSISDN użytkownika. Poniżej opisujemy mechanizm, który ustala identyfikator CPID.

Przebieg rozmowy CPID

Ilustracja 2. Schemat połączenia w celu ustalenia identyfikatora CPID.

  1. Aplikacja Google na urządzeniu UE używa wewnętrznego interfejsu API Google do pobierania z GTAF adresu URL punktu końcowego CPID. Operator jest identyfikowany na podstawie publicznego adresu IP klienta i kodu MCC+MNC aktywnej karty SIM. W przypadku operatorów MVNO Google będzie używać SPN i GID1 do określania operatora MVNO.
  2. Klient wysyła żądanie HTTP GET do punktu końcowego CPID. Operator MOŻE obsługiwać wysyłanie żądania przez HTTPS.
  3. Operator MOŻE użyć funkcji głębokiej inspekcji pakietów, aby zidentyfikować żądanie i wstrzyknąć numer telefonu użytkownika do żądania jako nagłówek HTTP.
  4. Punkt końcowy CPID odbiera żądanie, tworzy identyfikator CPID i zwraca go do urządzenia UE wraz z czasem życia (TTL), który określa, jak długo urządzenie UE może używać tego identyfikatora CPID.

Operator MOŻE też używać adresów IP zamiast nazw domen w adresie URL punktu końcowego CPID, jeśli jest to dla niego wygodniejsze. Adresy IP MOGĄ znajdować się w przestrzeni adresów prywatnych, ale muszą być dostępne dla klientów Google w sieci operatora.

Operator MUSI przekazać Google następujące informacje w ramach procesu wdrażania:1. Adres CPID_URL, z którym aplikacje będą się kontaktować w celu uzyskania identyfikatorów CPID. Jeden adres CPID_URL jest obowiązkowy, ale operator może podać wiele adresów URL, aby zwiększyć dostępność. 1. Lista prefiksów IP należących do operatora oraz kod kraju sieci komórkowej (MCC) i kody sieci komórkowej (MNC), które operator chce przypisać do podanych adresów URL CPID. Jeśli operator używa SPN lub GID1 do rozróżniania MVNO w swojej sieci, musi również podać te informacje. Google będzie używać tych informacji do dopasowywania klientów do odpowiednich punktów końcowych CPID, jak pokazano w kroku 1 na rysunku 2.

Format żądania:GET CPID_URL Ze względu na starsze systemy punkt końcowy CPID powinien obsługiwać żądania takie jak to:

GET CPID_URL?app={app_id}

Punkt końcowy CPID może ignorować parametr adresu URL {app_id} podczas generowania identyfikatora CPID. Musi jednak obsługiwać żądanie zawierające ten parametr.

Żądanie do punktu końcowego CPID MOŻE zawierać nagłówek Accept-Language. Jeśli nagłówek jest uwzględniony, ciągi znaków czytelne dla człowieka w aktualizacjach wysyłanych przez dostawcę danych za pomocą interfejsu Mobile Data Plan Sharing API MUSZĄ używać ustawień podanych w żądaniu CPID.

Za każdym razem, gdy klient wyśle żądanie GET CPID_URL, MUSI otrzymać nowy identyfikator CPID. Jeśli utworzenie identyfikatora CPID się powiedzie, punkt końcowy CPID MUSI zwrócić odpowiedź 200 OK. Treść odpowiedzi MUSI zawierać instancję elementu CPIDResponse.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

Zwrócony identyfikator CPID MUSI być ważny przez ttlSeconds sekund. GTAF będzie kodować identyfikator CPID zgodnie z normą RFC2396 w kolejnych wywołaniach do platformy DPA.

Jeśli wystąpi błąd, punkt końcowy CPID MUSI zwrócić błąd HTTP z treścią odpowiedzi, która MUSI zawierać instancję ErrorResponse. Lista możliwych wartości przyczyny i kodów błędów HTTP jest dostępna tutaj.

{
    "errorMessage": "<error message>",
    "cause": "INVALID_NUMBER"
}

W szczególności, jeśli żądanie CPID zostanie odebrane w przypadku użytkownika, który nie należy do sieci operatora (np. użytkownika innego operatora, który korzysta z roamingu w sieci obsługiwanej przez ten punkt końcowy CPID) lub który nie wyraził zgody na udostępnianie Google informacji o abonamencie na dane, punkt końcowy CPID MUSI zwrócić kod stanu HTTP 403.

Generowanie identyfikatora CPID

ZALECANY sposób tworzenia identyfikatora CPID przez punkt końcowy CPID:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

Punkt końcowy CPID łączy numer MSISDN, język wysłany przez klienta w nagłówku Accept-Language i sygnaturę czasową o wysokiej rozdzielczości, a następnie szyfruje go za pomocą algorytmu AES przy użyciu klucza secret. Sygnatura czasowa POWINNA odpowiadać czasowi wygaśnięcia identyfikatora CPID. Zaszyfrowane dane wyjściowe są zakodowane w formacie Base64. Ponadto, gdy identyfikator CPID jest używany w adresie URL, MUSI być zakodowany na potrzeby adresu URL, aby obsługiwać znaki specjalne (/+=) używane w Base64. W szczególności, gdy GTAF wywołuje DPA lub gdy DPA wywołuje interfejs Mobile Data Plan Sharing API, identyfikator CPID MUSI być zakodowany w formacie URL. Zaletą generowania identyfikatora CPID za pomocą tej metody jest to, że punkt końcowy DPA i CPID nie musi mieć bazy danych z prawidłowymi identyfikatorami CPID i numerami MSISDN.

W zależności od sytuacji danego operatora wdrożenie punktu końcowego CPID może być trudne. Często spotykanym problemem jest uzyskanie dostępu do numeru MSISDN w punkcie końcowym CPID. Chętnie podzielimy się wnioskami z procesu wdrażania operatorów. Jeśli napotkasz jakiekolwiek trudności, skontaktuj się z nami.

Wymagania dotyczące bezpieczeństwa

Operator MUSI podjąć wszelkie niezbędne środki ostrożności, aby chronić prywatne informacje swoich subskrybentów. Aby zminimalizować ryzyko ujawnienia numerów telefonów subskrybentów, punkt końcowy CPID POWINIEN znajdować się w Twojej strefie bezpieczeństwa. Ponadto w przypadkach, w których operator stosuje DPI, powinien zaszyfrować MSISDN przed wstrzyknięciem go do żądania HTTP. Jeśli punkt końcowy CPID nie znajduje się w Twojej strefie bezpieczeństwa (np. gdy punkt końcowy CPID jest wdrożony w chmurze publicznej), operator NIE POWINIEN przesyłać numeru MSISDN przez publiczny internet w formie niezaszyfrowanej. Operator może nawiązać połączenie VPN między punktem końcowym DPI a punktem końcowym CPID (patrz rysunek 1) lub zaszyfrować numer MSISDN przed wstawieniem go do nagłówka. To drugie podejście zakłada, że punkt końcowy CPID może odszyfrować wstrzyknięty nagłówek, aby odzyskać numer MSISDN przed wygenerowaniem identyfikatora CPID. Ponadto operator MUSI chronić klucz tajny używany do generowania identyfikatora CPID i wykonywać rotację tego klucza zgodnie z zasadami bezpieczeństwa operatora.

Wymagania dotyczące dostępności i pojemności

Jeśli klient nie może pobrać identyfikatora CPID, nie będzie mieć dostępu do żadnych informacji z interfejsu Mobile Data Plan API. Z tego powodu operator MUSI podjąć niezbędne środki, aby zapewnić dostępność punktu końcowego CPID. Takie środki obejmują posiadanie wielu instancji punktu końcowego CPID i funkcji DPI oraz fizyczną, lokalną i sieciową redundancję obu funkcji, a także zapewnienie odpowiednich zasobów i przepustowości systemu. Ponadto punkt końcowy CPID oraz funkcja DPI, która wstawia nagłówek, muszą mieć wystarczającą przepustowość, aby obsługiwać obciążenie wszystkich klientów Google, którzy wysyłają żądania CPID. Punkt końcowy CPID może używać większych wartości w polu ttlSeconds, aby zmniejszyć częstotliwość generowania identyfikatorów CPID. Google zaleca używanie wartości TTL wynoszącej 30 dni.

Uwagi

  1. Wartość PMTC VIDEO_OFFLINE oznacza, że ten abonament jest przeznaczony tylko do korzystania w trybie offline (np. bardzo niska jakość strumieniowania). Jest on niezależny od okna FlexTime. ↩