Motivazione
Come menzionato nella panoramica, a seconda dei casi d'uso che l'operatore vuole supportare, l'ETD deve implementare una combinazione dell'API Google Mobile Data Plan Sharing e dell'API del piano dati. In questo documento viene descritta l'API dell'agente per il piano dati che Google utilizzerà per identificare i piani dati mobili dell'utente, recuperare informazioni su questi piani e acquistare piani dati.
Autenticazione
Per poter chiamare GTAF, l'ETD 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. Consulta la sezione Autenticazione agente piano dati per maggiori dettagli su come GTAF esegue l'autenticazione con la DPA.
Internazionalizzazione
Le richieste GTAF all'ETD includono un'intestazione Accept-Language che indica la lingua in cui devono essere incluse le stringhe leggibili (ad esempio, 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 l'ETD non supporta la lingua richiesta dall'utente, può utilizzare una lingua predefinita e usare il campo languageCode per indicare la propria scelta.
Descrizione API
GTAF utilizza la chiave utente, che identifica un abbonato all'operatore, quando esegue una query sull'ETD dell'operatore. Quando GTAF esegue una query sull'ETD per conto delle applicazioni che hanno accesso all'MSIDN, GTAF POTREBBE utilizzare l'MSIDN. A livello generale, l'API del piano dati proposta è composta dai seguenti componenti:
- Meccanismo per eseguire query sullo stato del piano dati dell'utente.
- Meccanismo per interrogare l'ETD per le offerte di piani dati per l'utente.
- Meccanismo per apportare modifiche al piano dati dell'utente (ad es. acquistare un nuovo piano).
- Meccanismo per condividere i CPID utilizzabili per inviare notifiche agli utenti.
- Meccanismo per condividere le scelte degli utenti sull'iscrizione al nostro servizio.
Il resto del documento approfondisce ciascuno di questi componenti dell'API. Salvo indicazione esplicita, tutte le comunicazioni DEVONO avvenire su HTTPS (con un certificato SSL DPA valido). A seconda delle funzionalità supportate, un operatore POSSONO scegliere di implementare tutti o alcuni 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 chiamata associato a un client che esegue query sullo stato del piano dati dell'utente e su altre informazioni relative al piano dati. Questo flusso di chiamata è condiviso per le chiamate API attivate dal client in UE.
- Il client richiede lo stato del piano dati e/o altre informazioni chiamando un'API privata di Google. Il client include la chiave utente nella richiesta a GTAF.
- GTAF utilizza la chiave utente e un identificatore client per eseguire query sull'ETD dell'operatore. Gli identificatori client supportati sono mobiledataplan e youtube. Quando la DPA riceve una chiamata con uno di questi identificatori client, DEVE rispondere con 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 da GTAF fino alla scadenza specificata dall'ETD.
I passaggi 1 e 3 nella Figura 4 sono API di Google private e pertanto non sono
descritti ulteriormente. Il passaggio 2 è un'API pubblica descritta di seguito. La DPA DEVE rispettare l'intestazione HTTP Cache-Control: no-cache quando gestisce queste chiamate API da GTAF.
Query sullo stato del piano dati
GTAF emette 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 sta contattando l'ETD viene identificato tramite CLIENT_ID. A seconda dell'accordo tra il client e l'operatore Google, la DPA può personalizzare la risposta a GTAF. In caso di esito positivo, l'ETD DEVE restituire HTTP 200 OK con un corpo di risposta che rappresenta un PlanStatus. Consulta le casi di errore per informazioni sulla 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 con pagamento posticipato, expirationTime DEVE essere la data di ricorrenza del piano (ovvero quando il saldo dei dati viene aggiornato o ricaricato).
Ogni modulo del piano può contenere più categorie di traffico del modulo del piano (PMTCs)per
definire il caso in cui un modulo del piano è condiviso tra più app, ad esempio 500 MB
per giochi e musica). I seguenti PMTC sono predefiniti: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING.
Si prevede che gli operatori contatteranno i singoli team di Google per concordare l'insieme di categorie di traffico e la relativa semantica pertinenti per diverse applicazioni Google.
Esecuzione di query sulle offerte relative ai piani
GTAF emette la seguente richiesta HTTP per ricevere offerte di piano dall'operatore:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Il cliente per conto del quale GTAF sta contattando l'ETD viene identificato tramite CLIENT_ID. A seconda dell'accordo tra il client e l'operatore Google, la 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, la DPA DEVE restituire HTTP 200 OK con un corpo di risposta che rappresenta un PlanOffer. Consulta Richieste di errore per informazioni sulla 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 o i piani dati nell'array offers POSSONO determinare l'ordine in cui i piani dati vengono presentati agli utenti. Inoltre, se l'applicazione può presentare solo i piani x a causa della UI o di altre limitazioni e la risposta contiene piani y > x, verranno presentati solo i primi x piani. GTAF condivide soltanto fino a 50 piani se l'applicazione che esegue query per le offerte è un modulo Piano dati mobili che fa parte di Google Play Services. Questo serve a garantire una buona esperienza utente agli utenti di Google Play Services.
Le offerte di upsell includono filterTag come parametro facoltativo, ovvero un array di tag associati a ogni piano. Tutti questi tag tag devono corrispondere al tag, che è un oggetto all'interno del filtro. Filter è un oggetto di primo livello che contiene
tuple<tag, displaytext/#quot;">. Filter è un elenco consolidato di filtri che verranno visualizzati
nell'interfaccia utente. L'utente può filtrare facendo clic su DisplayText. Il tag corrispondente al 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 attraverso il quale l'utente verrà addebitato per qualsiasi acquisto può essere comunicato con GTAF utilizzando l'opzione formOfPayment nella risposta.
Acquisto dati
L'API purchase plan definisce il modo in cui GTAF può acquistare piani tramite l'ETD. GTAF avvia la transazione per acquistare un piano dati all'ETD. La richiesta DEVE includere un identificatore univoco della transazione (transactionId) per monitorare le richieste ed evitare l'esecuzione di transazioni duplicate. L'ETD DEVE rispondere con una risposta di operazione riuscita o non riuscita.
Richiesta di transazione
Una volta ricevuta la richiesta da un client, GTAF invia una richiesta POST all'ETD. L'URL della richiesta è:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dove userKey è un 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 transazione
L'ETD DEVE generare una risposta 200-OK solo per una transazione eseguita correttamente o una transazione in coda. Consulta le richieste di assistenza per informazioni sulle risposte previste in caso di errori. In caso di transazione in coda, l'ETD riempirà solo lo stato della transazione e lascerà gli altri campi nella risposta. L'DPA DEVE richiamare GTAF fornendo una risposta dopo aver gestito 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 DEVE presumere 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 consentono a GTAF di farlo. Se il client registra il CPID correttamente con GTAF, GTAF lo registrerà 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 tempo dopo il quale il CPID non può essere utilizzato per inviare notifiche e ha questo 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, la DPA POSSONO archiviare l'ultimo CPID registrato per ogni utente. Consulta Scelta del CPID per indicazioni su come utilizzare il CPID registrato per l'invio delle notifiche.
La DPA genera una risposta di 200 OK se associa con successo il CPID all'utente e lo archivia in modo permanente. Consulta Richieste di errore per informazioni sulla risposta prevista in caso di errori.
Consenso
GTAF POSSONO emettere la seguente richiesta per trasmettere la preferenza relativa al consenso dell'utente all'operatore.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
dove userKey è un CPID o MSISDN. Il corpo della richiesta è un'istanza di SetConsentStatusRequest. Se l'operazione ha esito positivo, il corpo della risposta deve essere vuoto.
Ogni chiamata da GTAF alla DPA segue i termini di servizio del client Google che effettua la chiamata. A seconda delle applicazioni che l'ETD intende supportare, è compito dell'operatore decidere se l'ETD implementa questa API. Se l'ETD sceglie di implementare l'API di consenso, DPA DEVE archiviare lo stato del consenso più recente per ogni utente. Consulta Scelta del CPID per indicazioni su come utilizzare le informazioni sullo stato del consenso.
In caso di esito positivo, la DPA DEVE restituire HTTP 200 OK con un corpo di risposta vuoto. Consulta le casi di errore per informazioni sulla risposta prevista in caso di errori.