Stabilire il CPID

GTAF utilizza la chiave utente per identificare un abbonato quando comunica con il DPA. Le applicazioni che hanno accesso all'MSISDN dell'utente possono utilizzarlo come user_key. D'altra parte, le applicazioni che non hanno accesso all'MSISDN devono stabilire un identificatore del piano dell'operatore (CPID) senza scoprire l'MSISDN dell'utente. Di seguito, descriviamo il meccanismo che stabilisce un CPID.

Flusso di chiamata CPID

Figura 2: flusso di chiamata per stabilire il CPID.

1. Un'applicazione Google nell'UE utilizza un'API interna di Google per recuperare l'URL dell'endpoint CPID da GTAF. L'operatore viene identificato utilizzando l'indirizzo IP pubblico del client e il codice paese + codice rete mobile della scheda SIM attiva. Nel caso degli MVNO, Google utilizzerà lo SPN e il GID1 per determinare l'MVNO
2. Il client invia una richiesta HTTP GET all'endpoint CPID. L'operatore POTREBBE supportare l'invio della richiesta tramite HTTPS.
3. L'operatore PUÒ utilizzare la funzione di ispezione approfondita dei pacchetti per identificare la richiesta e inserire il numero di telefono dell'utente nella richiesta come intestazione HTTP.
4. L'endpoint CPID riceve la richiesta, crea il CPID e lo restituisce all'UE con un time to live (TTL) che indica per quanto tempo l'UE può utilizzare questo CPID.

L'operatore PUÒ anche utilizzare indirizzi IP anziché nomi di dominio nell'URL dell'endpoint CPID, se preferisce. Gli indirizzi IP POSSONO trovarsi nello spazio di indirizzi privati, ma devono essere raggiungibili dai client Google all'interno della rete degli operatori.

Nell'ambito della procedura di onboarding, l'operatore DEVE fornire a Google le seguenti informazioni:

1. L'URL CPID_URL che le applicazioni contatteranno per acquisire i CPID. È obbligatorio un CPID_URL, ma l'operatore può fornire più URL per aumentare la disponibilità.
2. L'elenco dei prefissi IP di proprietà dell'operatore e il codice paese mobile (MCC) e i codici di rete mobile (MNC) che l'operatore vuole mappare agli URL CPID forniti. Se l'operatore utilizza SPN o GID1 per distinguere gli MVNO nella propria rete, l'operatore DEVE fornire anche queste informazioni. Google utilizzerà queste informazioni per associare i client agli endpoint CPID corrispondenti, come mostrato nel passaggio 1 della Figura 2.

Il formato della richiesta è: GET CPID_URL Per motivi legacy, l'endpoint CPID deve essere in grado di supportare una richiesta come la seguente:

GET CPID_URL?app={app_id}

L'endpoint CPID può ignorare il parametro URL {app_id} durante la generazione dell'ID CPID. Tuttavia, DEVE essere in grado di gestire una richiesta che contiene il parametro.

La richiesta all'endpoint CPID PUÒ includere l'intestazione Accept-Language. Se l'intestazione è inclusa, le stringhe leggibili dagli utenti negli aggiornamenti inviati dal DPA utilizzando l'API Mobile Data Plan Sharing DEVONO utilizzare le impostazioni fornite nella richiesta CPID.

Ogni volta che il client invia una richiesta GET CPID_URL, DEVE ricevere un nuovo CPID. Se la creazione del CPID ha esito positivo, l'endpoint CPID DEVE restituire una risposta 200 OK. Il corpo della risposta DEVE contenere un'istanza di CPIDResponse.

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

Il CPID restituito DEVE essere valido per ttlSeconds secondi anche se un abbonato ha richiesto altri CPID in seguito. Google consiglia di utilizzare un valore TTL di 30 giorni, ma non inferiore a 14 giorni, per un'esperienza utente ottimale. GTAF codificherà l'ID CPID in base allo standard RFC2396 nelle chiamate successive al DPA.

Generazione CPID

Il modo CONSIGLIATO per creare un CPID tramite l'endpoint CPID è:

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

L'endpoint CPID concatena MSISDN, la lingua inviata dal client nell'intestazione Accept-Language e un timestamp ad alta risoluzione e lo cripta tramite AES utilizzando la chiave secret. Il timestamp DEVE corrispondere all'ora di scadenza dell'ID contenuto. L'output criptato è codificato in Base64. Inoltre, quando il CPID viene utilizzato in un URL, DEVE essere codificato in URL per gestire i caratteri speciali (/+=) utilizzati in Base64. In particolare, quando GTAF chiama la DPA o quando la DPA chiama l'API Mobile Data Plan Sharing, il CPID DEVE essere codificato come URL.

A seconda della situazione di un determinato operatore, l'implementazione dell'endpoint CPID potrebbe non essere semplice. Una sfida particolare che si è presentata di frequente è l'accesso all'MSISDN all'endpoint CPID. Siamo felici di condividere le lezioni apprese durante l'onboarding degli operatori. Contattaci se riscontri difficoltà.

Archiviazione CPID

Un CPID generato utilizzando il meccanismo descritto sopra non deve essere memorizzato in un database. Le informazioni pertinenti per la gestione delle chiamate al DPA possono essere dedotte dal CPID.

1. Quando il DPA riceve una chiamata da GTAF per lo stato di un piano o le offerte, l'MSISDN può essere derivato decriptando il CPID ed estraendo l'MSISDN.
2. Il tempo di scadenza del CPID può essere derivato decriptando il CPID ed estraendo il timestamp di scadenza.

Requisiti di disponibilità e capacità

Se i client non riescono a recuperare un CPID, non possono accedere ad alcuna informazione dall'API Mobile Data Plan. Per questo motivo, l'operatore DEVE adottare le misure necessarie per garantire la disponibilità dell'endpoint CPID. Queste misure includono più istanze dell'endpoint CPID e delle funzioni DPI, nonché ridondanza fisica, del sito e della rete per entrambe le funzioni e garantiscono che le risorse e la capacità del sistema siano adeguate. Inoltre, l'endpoint CPID e la funzione DPI che inserisce l'intestazione devono avere una capacità adeguata per gestire il carico di tutti i client Google che richiedono CPID. L'endpoint CPID può utilizzare valori più grandi nel campo ttlSeconds per ridurre la frequenza con cui genera CPID.

Casi di errore

Se si verifica un errore, l'endpoint CPID DEVE restituire un errore HTTP con un corpo della risposta che DEVE contenere un'istanza di ErrorResponse. Un buon messaggio di errore include informazioni che possono aiutare a eseguire il debug della causa dell'errore. Ad esempio, in caso di CPID scaduto, l'inclusione della generazione e dell'ora di scadenza del CPID ci aiuterebbe a confermare che l'endpoint CPID funziona come previsto.

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

A seconda dello scenario, l'endpoint CPID DEVE restituire quanto segue:

1. Se viene ricevuta una richiesta CPID per un utente che non appartiene alla rete dell'operatore (ad es. un utente che appartiene a un altro operatore ma in roaming sulla rete servita da questo endpoint CPID) o che non ha acconsentito alla condivisione dei dati del piano dati con Google, l'endpoint CPID DEVE restituire il codice di stato HTTP 403 con USER_ROAMING, USER_OPT_OUT o INELIGIBLE_FOR_SERVICE come causa.
2. Se viene ricevuta una richiesta CPID con un numero di telefono non valido, l'endpoint CPID DEVE restituire HTTP 400 con la causa dell'errore INVALID_NUMBER.
3. Se la richiesta all'endpoint CPID è malformata in qualsiasi altro modo, l'endpoint CPID DEVE restituire HTTP 400 con ERROR_CAUSE_UNSPECIFIED come causa.
4. Per altre cause di errore, è accettabile qualsiasi codice di errore HTTP compatibile. In particolare, l'errore HTTP 500 è una causa di errore adatta per qualsiasi errore interno nell'endpoint CPID.