Guida introduttiva alla condivisione del piano dati mobili

Terminologia

  • GTAF: funzione Google Traffic Application. Un servizio Google che implementa l'API di condivisione del piano dati e interagisce con le DPA per conto delle applicazioni Google. Le applicazioni Google possono eseguire query su GTAF per le informazioni sul piano dati dell'utente. In alternativa, se le applicazioni Google si registrano a GTAF, GTAF può inviare aggiornamenti sul piano dati dell'utente.
  • MSISDN: numero di directory degli abbonati internazionali di Mobile Station, un numero che identifica in modo univoco un abbonamento in una rete mobile. Chiamato anche numero di telefono,
  • Endpoint CPID: un servizio implementato da operatori di rete mobile che genera un identificatore di piano 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 file MSISDN dell'utente. Di seguito viene descritta la procedura per la generazione di CPID.
  • Chiave utente: Chiave utente è una stringa che può essere utilizzata per identificare il piano dati di un utente. Può essere il CPID o il MSISDN per le applicazioni che hanno accesso al file MSISDN.
  • DPA: agente del piano dati, un servizio implementato da operatori di rete mobile che condivide le informazioni sul piano dati dell'utente con GTAF. L'ETD può condividere le informazioni con GTAF utilizzando una combinazione di invio dei dati tramite l'API Google Mobile Data Plan Sharing e l'implementazione dell'API dell'agente Data Plan. La DPA può anche fungere da endpoint CPID.
  • UE: attrezzatura utente, dispositivo utilizzato dall'utente.

Requisiti relativi alla lingua

Le parole chiave "DEVONO", "DEVONO NON", "OBBLIGATORIO",

Condivisione 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 utilizzare questo codice come chiave utente.
  2. Un'API Google Mobile Data Plan Sharing che consente alla DPA di inviare a Google informazioni relative al piano dati di un utente. Ad esempio, se la DPA vuole notificare l'utente a un'offerta, può informare GTAF, che a sua volta informa l'utente.
  3. Un'API dell'agente per il piano dati implementata dall'ETD che consente a GTAF di eseguire query sull'ETD per ottenere informazioni sul piano dati dell'utente. Ad esempio, se un'applicazione vuole mostrare all'utente il saldo del piano dati corrente, può eseguire query su GTAF, che a sua volta esegue una query sull'ETD.

Il resto di questa pagina introduce la terminologia dei piani di dati e i dettagli su come stabilire un CPID. L'API Google Mobile Data Plan Sharing e la specifica dell'API Data Plan Agent di seguito sono riportate.

Terminologia del piano dati

Lo schema di un planStatus definito nell'API DEVE rappresentare i piani di 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 esempio, tutto il traffico per *.acmefake.com viene addebitato a una tariffa diversa). L'API supporta anche piani dati che offrono tariffe diverse per determinati tipi di azioni in un'app. Questi sono chiamati piani di dati sub-app. Un esempio di piano dati di sub-app sarebbe offrire una navigazione video senza costi (ovvero a frequenza zero), mentre la visione dei video all'interno dell'applicazione detrae i dati dal saldo dati dell'abbonato. L'app video DEVE quindi conoscere queste informazioni quando esegue una query sulle informazioni del piano dati.

Qui presentiamo alcuni termini relativi ai piani di dati. La Figura 1 fornisce esempi di piani di dati rappresentativi dei concetti che vogliamo acquisire.

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

  • Nome piano dati, ad esempio "ACME Red".
  • ID piano dati, utilizzato per fare riferimento al piano, ad esempio durante gli acquisti.
  • Data di scadenza, alla scadenza del piano dati.
  • Categoria del piano, che si tratti di un piano prepagato o di un piano post-pagamento.

Piano del piano: un componente di un piano dati. In particolare, un modulo del piano include:

  • Nome del modulo, ad esempio "Notti video senza costi".
  • Frequenza max, larghezza di banda offerta all'utente da questo modulo.
  • Finestre temporali flessibili, ovvero le finestre temporali durante le quali potrebbe essere offerto uno sconto all'utente.

  • Plan Module Traffic Category (PMTC), una descrizione del traffico dati a cui si applica un modulo. Il PMTC può essere generico quanto *tutto il traffico Internet *o specifico quanto il traffico generato/utilizzato da una o più applicazioni, siti web o anche percorsi degli utenti all'interno di una singola applicazione. Esempi di quest'ultimo tipo sono "musica illimitata", "Video Data Pack (160 MB)" e "dati di gioco illimitati" e "navigazione video illimitata". Per definire la definizione di PMTC abbiamo definito i seguenti: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE1, MUSIC, GAMING, SOCIAL, MESSAGING e PMTC_UNSPECIFIED.

  • Volume o tempo limite, una volta attivato, il modulo del piano scade quando il volume o il limite di dati (nel caso di piani basati sul tempo, ad esempio vengono superati i 600 minuti di accesso a Internet nei prossimi 7 giorni). 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 che deve essere utilizzato entro una settimana dall'attivazione prima della scadenza.

Piano di esempio dell'API Data Plan

Figura 1. Esempi di piani di dati.

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. È obbligatorio specificare un CPID_URL, ma l'operatore può fornire più URL per aumentare la disponibilità. 1. 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. GTAF codifica il CPID in base al documento RFC2396 nelle chiamate successive all'ETD.

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. L'elenco dei possibili valori di causa e 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 esempio, un utente appartenente a un altro operatore, ma in roaming sulla rete gestita da questo endpoint CPID) o che non ha scelto di condividere le informazioni del piano dati con Google, l'endpoint CPID DEVE restituire il codice di stato HTTP 403.

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. Un vantaggio della generazione di CPID con questo approccio è che gli endpoint DPA e CPID non devono necessariamente avere un database di CPID e MSISDN validi.

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.

Requisiti di sicurezza

L'operatore DEVE prendere tutte le precauzioni necessarie per proteggere le informazioni private dei propri abbonati. In particolare, per ridurre al minimo l'esposizione dei numeri di telefono degli abbonati, l'endpoint CPID DEVE essere all'interno del tuo perimetro di sicurezza. Inoltre, nei casi in cui l'operatore utilizza un DPI, l'operatore DEVE criptare il file MSISDN prima di inserirlo nella richiesta HTTP. Se l'endpoint CPID non è il tuo perimetro di sicurezza (ad esempio, quando viene eseguito il deployment dell'endpoint CPID su un cloud pubblico), l'operatore NON deve trasmettere il MSISDN sulla rete Internet pubblica in chiaro. L'operatore può stabilire una VPN tra il DPI e l'endpoint CPID (vedi la Figura 1) o criptare il file MSISDN prima di inserirlo nell'intestazione. Il secondo approccio presuppone che l'endpoint CPID possa decriptare l'intestazione inserita per recuperare il file MSISDN prima di generare il CPID. Inoltre, l'operatore DEVE proteggere la chiave segreta utilizzata per generare il CPID e ruotarla in base ai criteri di sicurezza dell'operatore.

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

Note

  1. Il PMTC VIDEO_OFFLINE indica che il piano è adatto solo per la modalità offline (ad es. QoE davvero in streaming). È indipendente dalla finestra di FlexTime. ↩