Stabilire il CPID

GTAF utilizza la chiave utente per identificare un abbonato quando comunica con l'ETD. Le applicazioni che hanno accesso all'MSIDN dell'utente possono utilizzarlo come chiave utente. Per contro, le applicazioni che non hanno accesso a MSISDN devono stabilire un identificatore di piano dell'operatore (CPID) senza rilevare l'MSIDN dell'utente. Di seguito viene descritto 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 tramite l'indirizzo IP pubblico del client e il Centro clienti (MNC) della scheda SIM attiva. Nel caso di MVNO, Google utilizzerà l'SPN e il GID1 per determinare il 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 POSSONO utilizzare la funzione di ispezione di pacchetti diretti per identificare la richiesta e iniettare nella richiesta il numero di telefono dell'utente come intestazione HTTP.
4. L'endpoint CPID riceve la richiesta, costruisce il CPID e restituisce CPID alla UE con la durata (TTL) che indica per quanto tempo l'UE può utilizzare il CPID.

Se preferisci, l'operatore può anche utilizzare indirizzi IP anziché nomi di dominio nell'URL dell'endpoint CPID. Gli indirizzi IP POSSONO trovarsi in uno spazio di indirizzi privati, ma devono essere raggiungibili dai client di Google all'interno della rete degli operatori.

L'operatore DEVE fornire le seguenti informazioni a Google nell'ambito della procedura di onboarding:

1. Il CPID_URL che le applicazioni contatterà per acquisire i CPID. Un CPID_URL è obbligatorio, ma l'operatore può fornire più URL per aumentare la disponibilità.
2. L'elenco dei prefissi IP di proprietà dell'operatore, insieme ai codici Mobile Country Code (Centro clienti) e Mobile Network Code (MNC), che l'operatore vuole mappare agli URL CPID_URL forniti. Se l'operatore utilizza SPN o GID1 per distinguere gli MVNO nella rete, l'operatore DEVE fornire 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 i motivi precedenti, l'endpoint CPID dovrebbe essere in grado di supportare una richiesta simile alla seguente:

GET CPID_URL?app={app_id}

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

La richiesta all'endpoint CPID POTREBBE includere l'intestazione Accept-Language. Se è inclusa l'intestazione, negli aggiornamenti inviati dalla DPA mediante l'API Mobile Data Plan Sharing DEVE 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. Per un'esperienza utente ottimale, Google consiglia di utilizzare un valore TTL di 30 giorni, ma non inferiore a 14 giorni. GTAF codifica il CPID in base al documento RFC2396 nelle chiamate successive all'ETD.

Generazione CPID

Il metodo CONSIGLIATO per la creazione dell'endpoint CPID consiste nel:

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

L'endpoint CPID concatena MSISDN, il linguaggio inviato dal client nell'intestazione Accept-Language, nonché un timestamp ad alta risoluzione e lo cripta tramite AES utilizzando la chiave secret. Il timestamp DEVE corrispondere alla data di scadenza del CPID. L'output criptato è codificato in Base64. Inoltre, quando il CPID viene utilizzato in un URL, DEVE essere codificato nell'URL per gestire i caratteri speciali (/+=) usati in Base64. In particolare, quando GTAF chiama l'ETD o l'ETD chiama l'API Mobile Data Plan Sharing, il CPID DEVE essere codificato nell'URL.

A seconda della situazione di un determinato operatore, può essere difficile implementare l'endpoint CPID. Una sfida particolare incontrata di frequente è l'accesso a MSISDN all'endpoint CPID. Siamo lieti di condividere le lezioni apprese con gli operatori di onboarding. Non esitare a contattarci in caso di problemi.

Archiviazione CPID

Un CPID generato utilizzando il meccanismo sopra descritto non deve essere memorizzato in un database. Le informazioni pertinenti per la gestione delle chiamate all'ETD possono essere derivate dal CPID.

1. Quando l'ETD riceve una chiamata dal GTAF per uno stato o delle offerte relative al piano, il MSISDN può essere ricavato decriptando il CPID ed estraendo il codice MSISDN.
2. La scadenza del CPID può essere ricavata decriptando il CPID e poi estraendo il timestamp di scadenza.

Requisiti di disponibilità e capacità

Se i client non possono recuperare un CPID, non possono accedere alle informazioni dall'API Mobile Data Plan. Per questo motivo, l'operatore DEVE adottare le misure necessarie per garantire la disponibilità dell'endpoint CPID. Tali misure includono la presenza di più istanze delle funzioni endpoint CPID e DPI e la ridondanza fisica, del sito e della rete per entrambe le funzioni e assicurano 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ù ampi 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 di 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, inclusi la generazione e la scadenza del CPID, ci aiuterai a verificare che l'endpoint CPID funzioni come previsto.

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

L'endpoint CPID DEVE restituire quanto segue, a seconda dello scenario:

1. Se viene ricevuta una richiesta CPID per un utente che non appartiene alla rete dell'operatore (ad esempio, un utente appartenente a un altro operatore, ma in roaming sulla rete pubblicato da questo endpoint CPID) o che non ha scelto di condividere le informazioni sul 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 causa di errore INVALID_NUMBER.
3. Se la richiesta all'endpoint CPID non è valida in nessun 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, HTTP 500 è una causa di errore adatta per qualsiasi errore interno nell'endpoint CPID.