Guida introduttiva alla condivisione del piano dati mobili

Terminologia

  • GTAF: Google Traffic Application Function. Un servizio Google che implementa l'API per la condivisione del piano dati e interagisce con i DPA per conto delle applicazioni Google. Le applicazioni Google possono eseguire query su GTAF per ottenere informazioni sul piano dati dell'utente. In alternativa, se le applicazioni Google si registrano con GTAF, GTAF può inviare aggiornamenti sul piano dati dell'utente.
  • MSISDN: Mobile Station International Subscriber Directory Number, un numero che identifica in modo univoco un abbonamento in una rete mobile. Più comunemente noto come numero di telefono.
  • Endpoint CPID: un servizio implementato dagli operatori di rete mobile che genera un identificatore del piano dell'operatore (CPID) che può essere utilizzato per cercare le informazioni sul piano dati dell'utente. CPID consente a un'applicazione di eseguire query per i dettagli del piano dati di un utente senza accedere al suo MSISDN. Di seguito descriviamo la procedura per generare gli ID contenuti.
  • Chiave utente: la chiave utente è una stringa che può essere utilizzata per identificare il piano dati di un utente. Può essere il CPID o l'MSISDN per le applicazioni che hanno accesso all'MSISDN.
  • DPA: Data Plan Agent, un servizio implementato dagli operatori di rete mobile che condivide le informazioni sul piano dati dell'utente con GTAF. L'agente del piano dati può condividere informazioni con GTAF utilizzando una combinazione di invio di dati tramite l'API Google Mobile Data Plan Sharing e implementando l'API Data Plan Agent. Facoltativamente, l'accordo sulla protezione dei dati può fungere anche da endpoint CPID.
  • UE: apparecchiatura utente, dispositivo utilizzato dall'utente.

Requisiti relativi alla lingua

Le parole chiave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" in queste guide devono essere interpretate come descritto in RFC 2119.

Condivisione del piano dati mobili

A livello generale, la condivisione del piano dati mobili è composta da tre parti:

  1. Meccanismo per stabilire e aggiornare un identificatore del piano dell'operatore (CPID) che può essere utilizzato come chiave utente. Le applicazioni che hanno accesso a MSISDN possono utilizzarlo come chiave utente.
  2. Un'API Google per la condivisione del piano dati mobile che consente al DPA di inviare a Google informazioni sul piano dati di un utente. Ad esempio, se il DPA vuole comunicare un'offerta all'utente, può comunicarla a GTAF, che a sua volta la comunica all'utente.
  3. Un'API Data Plan Agent implementata dal DPA che consente a GTAF di eseguire query sul DPA per informazioni sul piano dati dell'utente. Ad esempio, se un'applicazione vuole mostrare all'utente il saldo attuale del piano dati, può interrogare GTAF, che a sua volta interroga DPA.

Il resto della pagina introduce la terminologia dei piani tariffari e spiega come stabilire un CPID. Di seguito sono riportate le specifiche dell'API Google Mobile Data Plan Sharing e dell'API Data Plan Agent.

Terminologia del piano dati

Lo schema di un planStatus definito nell'API DEVE essere in grado di rappresentare i piani dati offerti dagli operatori agli utenti. L'API supporta la definizione di piani dati che addebitano agli utenti una tariffa diversa per tutto il traffico verso un determinato insieme di URL (ad es. tutto il traffico verso *.acmefake.com viene addebitato a una tariffa diversa). L'API supporta anche i piani dati che offrono tariffe diverse per determinati tipi di azioni in un'app. Li chiamiamo piani dati secondari. Un esempio di piano dati secondario potrebbe essere la navigazione di video senza costi (ovvero a tariffa zero), mentre la visualizzazione di video all'interno dell'applicazione comporta la detrazione dei dati dal saldo dati dell'abbonato. L'app video DEVE quindi essere in grado di apprendere queste informazioni quando esegue query per informazioni sul piano dati.

Di seguito vengono introdotti alcuni termini relativi ai piani dati. La Figura 1 fornisce esempi di piani dati rappresentativi dei concetti che vogliamo acquisire.

Piano dati:il pacchetto di servizi mobili di primo livello acquistato da un abbonato. Può essere semplice come "10 GB di dati mobili per 30 giorni" o può essere definita come una raccolta di componenti, noti anche come moduli. Un piano dati ha:

  • Nome del piano dati, ad esempio "ACME Red".
  • Identificatore del piano dati, utilizzato per fare riferimento al piano, ad esempio durante gli acquisti.
  • Ora di scadenza, ovvero quando scade il piano dati.
  • Categoria del piano, se il piano è prepagato o postpagato.

Modulo del piano:un componente di un piano dati. Nello specifico, un modulo del piano ha:

  • Nome modulo, ad esempio "Notti di video senza costi".
  • Tariffa massima, larghezza di banda offerta all'utente da questo modulo.
  • Finestre temporali flessibili, finestre temporali durante le quali è possibile offrire uno sconto all'utente.

  • Categoria di traffico del modulo di pianificazione (PMTC), una descrizione del traffico di dati a cui si applica un modulo. Il PMTC può essere generico come *tutto il traffico internet *o specifico come il traffico generato/consumato da una o più applicazioni, siti web o persino percorsi utente all'interno di una singola applicazione. Esempi di quest'ultimo tipo sono "musica illimitata", "pacchetto di dati video da 100 MB (VDP)", "dati di gioco illimitati" e "navigazione video illimitata". Per facilitare la definizione dei PMTC, abbiamo definito i seguenti PMTC: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING e PMTC_UNSPECIFIED.

  • Volume di dati o limite di tempo: una volta attivato, il modulo del piano scade quando viene raggiunto il volume di dati o il limite di tempo (nel caso di piani basati sul tempo, ad es. 600 minuti di accesso a internet nei prossimi 7 giorni) è superato. Nella Figura 1 di seguito, un abbonato può acquistare un modulo del piano, come parte di "ACME Blue", che fornisce 1 GB di traffico utente generale da utilizzare entro una settimana dall'attivazione prima della scadenza.

Piano di esempio dell'API Data Plan

Figura 1. Piani dati di esempio.

Stabilire l'ID cliente

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.

L'operatore DEVE fornire a Google le seguenti informazioni nell'ambito della procedura di onboarding: 1. L'URL CPID_URL che le applicazioni contatteranno per acquisire i CPID. Un CPID_URL è obbligatorio, ma l'operatore può fornire più URL per aumentare la disponibilità. 1. 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, DEVE fornire anche queste informazioni. Google utilizzerà queste informazioni per abbinare 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. GTAF codificherà l'ID CPID in base allo standard RFC2396 nelle chiamate successive al DPA.

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. L'elenco dei possibili valori di cause e dei codici di errore HTTP è disponibile qui.

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

In particolare, 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 delle informazioni sul piano dati con Google, l'endpoint CPID DEVE restituire il codice di stato HTTP 403.

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. Un vantaggio della generazione di CPID utilizzando questo approccio è che l'endpoint DPA e CPID non deve avere un database di CPID e MSISDN validi.

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à.

Requisiti di sicurezza

L'operatore DEVE adottare tutte le precauzioni necessarie per proteggere le informazioni private dei propri abbonati. Nello specifico, per ridurre al minimo l'esposizione dei numeri di telefono degli abbonati, l'endpoint CPID DOVREBBE trovarsi all'interno del perimetro di sicurezza. Inoltre, nei casi in cui l'operatore utilizza l'ispezione approfondita dei pacchetti, l'operatore DEVE criptare l'MSISDN prima di inserirlo nella richiesta HTTP. Se l'endpoint CPID non è il tuo perimetro di sicurezza (ad es. quando l'endpoint CPID è implementato su un cloud pubblico), l'operatore NON DEVE trasmettere l'MSISDN su internet pubblico in chiaro. L'operatore può stabilire una VPN tra il DPI e l'endpoint CPID (vedi Figura 1) o criptare l'MSISDN prima di inserirlo nell'intestazione. Il secondo approccio presuppone che l'endpoint CPID possa decriptare l'intestazione inserita per recuperare l'MSISDN prima di generare il CPID. Inoltre, l'operatore DEVE proteggere la chiave segreta utilizzata per generare il CPID e ruotarla in base alle norme di sicurezza dell'operatore.

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. Google consiglia di utilizzare un valore TTL di 30 giorni.

Note

  1. VIDEO_OFFLINE PMTC significa che questo piano è valido solo per la modalità offline (ad es. QoE di streaming molto scadente). È indipendente dalla finestra FlexTime. ↩