Motivazione
Come indicato nella panoramica, a seconda dei casi d'uso che l'operatore vuole supportare, il DPA deve implementare una combinazione dell'API Google Mobile Data Plan Sharing e dell'API Data Plan Agent. Questo documento descrive l'API Data Plan Agent che Google utilizzerà per identificare i piani tariffari per i dati mobili dell'utente, recuperare informazioni su questi piani e acquistare piani tariffari per i dati.
Autenticazione
Prima che GTAF possa chiamare, il DPA deve autenticare GTAF. Nell'ambito della procedura di onboarding dell'operatore, verificheremo la validità del certificato SSL DPA. Al momento RICHIEDIAMO l'utilizzo di OAuth2 per l'autenticazione reciproca. Per informazioni dettagliate su come GTAF si autentica con il DPA, consulta Autenticazione dell'agente del piano dati.
Internazionalizzazione
Le richieste GTAF al DPA includono un'intestazione Accept-Language che indica la lingua in cui devono essere le stringhe leggibili (ad es. le descrizioni dei piani). Inoltre, le risposte DPA (PlanStatus, PlanOffers) includono un campo languageCode obbligatorio il cui valore è il codice lingua BCP-47 (ad es. "en-US") della risposta.
Se il DPA non supporta la lingua richiesta dall'utente, può utilizzare una lingua predefinita e utilizzare il campo languageCode per indicare la sua scelta.
Descrizione API
GTAF utilizza la chiave utente, che identifica un abbonato all'operatore, quando interroga il DPA dell'operatore. Quando GTAF esegue query sul DPA per conto di applicazioni che hanno accesso all'MSISDN, GTAF PUÒ utilizzare l'MSISDN. A livello generale, l'API Data Plan Agent proposta comprende i seguenti componenti:
- Meccanismo per eseguire query sullo stato del piano dati utente.
- Meccanismo per eseguire query sul DPA per le offerte di piani dati per l'utente.
- Meccanismo per apportare modifiche al piano dati dell'utente (ad es. acquisto di un nuovo piano).
- Meccanismo per condividere gli ID cliente che possono essere utilizzati per inviare notifiche agli utenti.
- Meccanismo per condividere le scelte degli utenti in merito alla registrazione al nostro servizio.
Il resto di questo documento descrive in dettaglio ciascuno di questi componenti dell'API. Se non indicato esplicitamente, tutte le comunicazioni DEVONO avvenire tramite HTTPS (con un certificato SSL DPA valido). A seconda delle funzionalità effettive supportate, un operatore PUÒ scegliere di implementare tutti o un sottoinsieme di questi componenti API.
Interazione GTAF-DPA
Figura 4. Flusso di chiamata per richiedere e ricevere informazioni sul piano dati dell'utente.
La figura 4 illustra il flusso di chiamate associato a un client che esegue una query sullo stato del piano dati dell'utente e su altre informazioni del piano dati. Questo flusso di chiamate è condiviso per le chiamate API attivate dal client sull'UE.
- Il client richiede lo stato del piano dati e/o altre informazioni chiamando un'API Google privata. Il client include la chiave utente nella richiesta a GTAF.
- GTAF utilizza la chiave utente e un identificatore client per eseguire query sul DPA dell'operatore. Gli identificatori client supportati sono mobiledataplan e youtube. Quando il DPA riceve una chiamata con uno di questi identificatori client, DEVE rispondere con le informazioni sul piano che possono essere utilizzate dal client.
- GTAF restituisce le informazioni richieste al client e le informazioni sul piano vengono memorizzate nella cache di GTAF fino alla scadenza specificata dal DPA.
I passaggi 1 e 3 della Figura 4 sono API Google private e pertanto non
vengono descritti ulteriormente. Il passaggio 2 è un'API pubblica descritta di seguito. Il DPA DEVE
rispettare l'intestazione HTTP Cache-Control: no-cache quando pubblica queste chiamate API
da GTAF.
Esecuzione di query sullo stato del piano dati
GTAF invia la seguente richiesta HTTP per ottenere lo stato del piano:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Il cliente per conto del quale GTAF contatta l'autorità per la protezione dei dati viene identificato utilizzando CLIENT_ID. A seconda dell'accordo tra il cliente Google e l'operatore, il DPA può personalizzare la risposta a GTAF. In caso di esito positivo, il DPA DEVE restituire HTTP 200 OK con un corpo della risposta che rappresenta un PlanStatus. Consulta la sezione Error Cases (Casi di errore) per la risposta prevista in caso di errori.
{
"plans": [{
"planName": "ACME1",
"planId": "1",
"planCategory": "PREPAID",
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"planModules": [{
"moduleName": "Giga Plan", // req.
"trafficCategories": ["GENERIC"],
"expirationTime": "2017-01-29T01:00:03.14159Z", // req.
"overUsagePolicy": "BLOCKED",
"maxRateKbps": "1500",
"description": "1GB for a month", // req.
"coarseBalanceLevel": "HIGH_QUOTA"
}]
}],
"languageCode": "en-US", // req.
"expireTime": "2018-06-14T08:41:27-07:00", // req.
"updateTime": "2018-06-07T07:41:22-07:00", // req.
"title": "Prepaid Plan"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
Per i piani postpagati, expirationTime DEVE essere la data di ricorrenza del piano (ovvero
quando il saldo dei dati viene aggiornato/ricaricato).
Ogni modulo del piano può contenere più categorie di traffico del modulo del piano (PMTCs)to
per modellare il caso in cui un modulo del piano è condiviso tra più app (ad es. 500 MB
per giochi e musica). I seguenti PMTC sono predefiniti: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Gli operatori
contatteranno i singoli team di Google per concordare l'insieme
di categorie di traffico e la relativa semantica pertinenti per le diverse applicazioni
Google.
Esecuzione di query sulle offerte di piani
GTAF invia la seguente richiesta HTTP per ottenere le offerte dei piani dall'operatore:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Il cliente per conto del quale GTAF contatta l'autorità per la protezione dei dati viene identificato utilizzando CLIENT_ID. A seconda dell'accordo tra il cliente Google e l'operatore, il DPA può personalizzare la risposta a GTAF. Il parametro di contesto facoltativo fornisce il contesto dell'applicazione in cui viene effettuata la richiesta. Di solito si tratta di una stringa che l'applicazione passa all'operatore tramite GTAF.
In caso di esito positivo, il DPA DEVE restituire HTTP 200 OK con un corpo della risposta che rappresenta un PlanOffer. Consulta la sezione Scenari di errore per la risposta prevista in caso di errori.
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"expireTime": "2019-03-04T00:06:07Z" // req.
}
L'ordine dei piani tariffari nell'array offers POTREBBE determinare l'ordine in cui vengono presentati agli utenti. Inoltre, se l'applicazione può
presentare solo x piani a causa di limitazioni dell'interfaccia utente o di altro tipo e la risposta contiene
y > x piani, verranno presentati SOLO i primi x piani. GTAF condivide solo fino a
50 piani se l'applicazione che esegue query per le offerte è il modulo Piano dati mobili, che
fa parte di Google Play Services. Questo serve a garantire una buona esperienza utente
per gli utenti di Google Play Services.
Le offerte di upselling hanno filterTags come parametro facoltativo, ovvero un array di
tag collegati a ogni piano. Tutti questi filterTags devono corrispondere al tag che è
un oggetto all'interno di Filter. Filter è un oggetto di primo livello che contiene
la tupla<tag, displaytext="">. Filter è un elenco consolidato di filtri che verranno
visualizzati nell'interfaccia utente. L'utente può filtrare facendo clic su DisplayText. Il tag
corrispondente a displayText viene utilizzato per filtrare le offerte.</tag,>
Tieni presente che l'operatore DEVE disporre di un meccanismo per soddisfare una richiesta di acquisto per qualsiasi offerta estesa all'utente. Il meccanismo tramite il quale all'utente verranno addebitati eventuali acquisti può essere comunicato a GTAF utilizzando l'opzione formOfPayment nella risposta.
Acquisto di dati
L'API per i piani di acquisto definisce in che modo GTAF può acquistare piani tramite il DPA. GTAF avvia la transazione per l'acquisto di un piano dati per il DPA. La richiesta DEVE includere un identificatore di transazione univoco (transactionId) per tracciare le richieste ed evitare l'esecuzione di transazioni duplicate. La DPA DEVE rispondere con una risposta di esito positivo/negativo.
Transaction Request
Una volta ricevuta una richiesta da un client, GTAF invia una richiesta POST al DPA. L'URL della richiesta è:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dove userKey è CPID o MSISDN. Il corpo della richiesta è un'istanza di TransactionRequest che include i seguenti campi:
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
Risposta della transazione
Il DPA deve generare una risposta 200 OK solo per una transazione eseguita correttamente o una transazione in coda. Consulta la sezione Error Cases per la risposta prevista in caso di errori. In caso di transazione in coda, il DPA deve compilare solo lo stato della transazione e lasciare vuoti gli altri campi della risposta. Il DPA DEVE richiamare GTAF con una risposta una volta gestita una transazione in coda. Il corpo della risposta è un'istanza di TransactionResponse che include i seguenti dettagli:
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
Se planActivationTime non è presente, GTAF PRESUME che il piano sia stato
attivato.
Registra CPID
Quando un client che supporta le notifiche riceve un nuovo CPID dall'endpoint CPID, lo registra con GTAF se i termini del client lo consentono. Se il client registra correttamente il CPID con GTAF, GTAF lo registra con il DPA utilizzando la seguente chiamata API:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dove userKey è il CPID e l'unico CLIENT_ID supportato è
mobiledataplan. Il corpo della richiesta è un'istanza di
RegisterCpidRequest e contiene il
periodo di tempo dopo il quale il CPID non può essere utilizzato per inviare notifiche e ha il seguente aspetto:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Questa API è pertinente solo per gli operatori che vogliono supportare il modulo Piano dati mobili in Google Play Services. Per inviare notifiche in modo affidabile all'utente, il DPA PUÒ memorizzare l'ultimo CPID registrato per ogni utente. Consulta Scegliere l'ID CP per indicazioni su come utilizzare l'ID CP registrato per l'invio di notifiche.
Il DPA genera una risposta 200-OK se associa correttamente il CPID all'utente e lo memorizza in modo permanente. Consulta la sezione Scenari di errore per la risposta prevista in caso di errori.
Consenso
GTAF MAY issue the following request to pass the user consent preference to the carrier.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dove userKey è CPID o MSISDN. Il corpo della richiesta è un'istanza di SetConsentStatusRequest. In caso di esito positivo, il corpo della risposta deve essere vuoto.
Ogni chiamata da GTAF al DPA segue i termini di servizio del client Google che effettua la chiamata. A seconda delle applicazioni che il DPA intende supportare, spetta all'operatore decidere se implementare questa API. Se il DPA sceglie di implementare l'API per il consenso, DEVE memorizzare l'ultimo stato del consenso per ogni utente. Consulta la sezione Scegliere l'ID consenso per indicazioni su come utilizzare le informazioni sullo stato del consenso.
In caso di esito positivo, il DPA DEVE restituire HTTP 200 OK con un corpo della risposta vuoto. Consulta la sezione Error Cases per la risposta prevista in caso di errori.