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.
- 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.
- Klient wysyła żądanie HTTP GET do punktu końcowego CPID. Operator MOŻE obsługiwać wysyłanie żądania przez HTTPS.
- 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.
- 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:
- Adres CPID_URL, z którym aplikacje będą się kontaktować w celu uzyskania identyfikatorów CPID. Wymagany jest jeden adres CPID_URL , ale operator może podać kilka adresów URL, aby zwiększyć dostępność.
- Lista prefiksów IP należących do operatora oraz kodów kraju (MCC) i 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 w swojej sieci wirtualnych operatorów komórkowych, 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, nawet jeśli subskrybent poprosił później o inne identyfikatory CPID. Aby zapewnić użytkownikom jak najlepsze wrażenia, Google zaleca stosowanie wartości TTL wynoszącej 30 dni, ale nie mniej niż 14 dni. GTAF będzie kodować identyfikator CPID zgodnie z normą RFC2396 w kolejnych wywołaniach do platformy DPA.
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.
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.
Przechowywanie CPID
Identyfikator CPID wygenerowany za pomocą opisanego powyżej mechanizmu nie musi być przechowywany w bazie danych. Odpowiednie informacje do obsługi połączeń z DPA można uzyskać z CPID.
- Gdy DPA otrzyma od GTAF połączenie dotyczące stanu pakietu lub ofert, numer MSISDN można uzyskać, odszyfrowując CPID i wyodrębniając MSISDN.
- Czas wygaśnięcia identyfikatora CPID można uzyskać, odszyfrowując go, a następnie wyodrębniając sygnaturę czasową wygaśnięcia.
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.
Przypadki błędów
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. Dobry komunikat o błędzie powinien zawierać informacje, które mogą pomóc w debugowaniu przyczyny błędu. Na przykład w przypadku wygasłego identyfikatora CPID podanie czasu jego wygenerowania i wygaśnięcia pomoże nam potwierdzić, że punkt końcowy CPID działa zgodnie z założeniami.
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
Punkt końcowy CPID MUSI zwrócić następujące informacje w zależności od scenariusza:
- 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 z przyczyną USER_ROAMING, USER_OPT_OUT lub INELIGIBLE_FOR_SERVICE.
- Jeśli żądanie CPID zostanie odebrane z nieprawidłowym numerem telefonu, punkt końcowy CPID MUSI zwrócić kod HTTP 400 z przyczyną błędu INVALID_NUMBER.
- Jeśli żądanie do punktu końcowego CPID jest w inny sposób nieprawidłowe, punkt końcowy CPID MUSI zwrócić kod HTTP 400 z przyczyną ERROR_CAUSE_UNSPECIFIED.
- W przypadku innych przyczyn błędów dopuszczalny jest dowolny zgodny kod błędu HTTP. W szczególności kod HTTP 500 jest odpowiednią przyczyną błędu w przypadku każdej wewnętrznej awarii w punkcie końcowym CPID.