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.
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 verificare se un utente è idoneo ad acquistare un determinato piano dati.
- Meccanismo per GTAF per la registrazione di MSISDN all'ETD.
- Meccanismo per GTAF per verificare se la DPA è in stato integro.
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.
Query sullo stato del piano dati
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.
Stato piano
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 del contratto tra il client Google e l'operatore, l'ETD può personalizzare la risposta a GTAF. Il formato della risposta è un oggetto JSON che rappresenta un PlanStatus.
{
"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
}
}
}
}
La richiesta DEVE includere un'intestazione Accept-Language che indichi la lingua in cui devono essere incluse le stringhe leggibili (ad esempio, le descrizioni dei piani).
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 del contratto tra il client Google e l'operatore, l'ETD 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.
Il corpo della risposta contiene un'istanza di PlanOffer.
{
"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"
}
],
"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 10 piani se l'applicazione che esegue query per le offerte è un'UI del 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 stringhe in offerInfo hanno lo scopo di consentire all'utente di leggere maggiori informazioni sull'offerta e includono anche un modo per disattivare la ricezione di più offerte all'interno delle applicazioni. Il motivo per cui questi campi vengono visualizzati è che alcuni operatori non richiedono il consenso dell'utente finale per consentire gli acquisti in-app, ma richiedono un meccanismo che consenta agli utenti di procedere alla disattivazione. Tieni presente che l'operatore DEVE avere un meccanismo per soddisfare una richiesta di acquisto per qualsiasi offerta estesa all'utente. Il meccanismo attraverso il quale viene addebitato all'utente un addebito per qualsiasi acquisto può essere comunicato con GTAF utilizzando l'opzione formOfPayment nella risposta.
La richiesta DEVE includere un'intestazione Accept-Language che indichi la lingua in cui devono essere incluse le stringhe leggibili (ad esempio, le descrizioni dei piani).
Acquisto dati
L'API purchase plan definisce il modo in cui GTAF può acquistare piani tramite l'ETD. Il 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
La DPA DEVE restituire le cause degli errori più comuni in caso di errore. Inoltre, i seguenti codici di errore rappresentano risultati di transazione non riusciti:
- L'ETD restituisce un codice di errore 400 BAD REQUEST che indica a GTAF che l'ID piano acquistato non è valido.
- L'ETD restituisce un codice di errore 402 PAYMENT REQUIRED che indica a GTAF che l'utente non ha un saldo sufficiente per completare l'acquisto.
- L'ETD restituisce un codice di errore 409 CONFLICT che indica a GTAF che il piano da acquistare non è compatibile con il mix di prodotti corrente dell'utente. Ad esempio, se il criterio del piano dati dell'operatore non consente di combinare i piani con pagamento posticipato e prepagato, il tentativo di acquistare un piano prepagato per un utente con pagamento posticipato comporterà un errore CONFLICT 409.
- L'ETD restituisce un codice di errore 403 FORBIDDEN che indica a GTAF che la transazione corrente è un duplicato di una precedente transazione emessa. La DPA DEVE restituire le seguenti cause di errore in risposta:
- Se la transazione precedente non è andata a buon fine, la causa dell'errore indica il motivo dell'errore.
- Se la transazione precedente è andata a buon fine, DUPLICATE_TRANSACTION.
- Se la transazione precedente è ancora in coda, REQUEST_QUEUED.
L'ETD DEVE generare una risposta 200-OK solo per una transazione eseguita correttamente o una transazione in coda. 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.
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.
Idoneità
GTAF POSSONO emettere la seguente richiesta di idoneità per verificare l'idoneità dell'utente all'acquisto di un piano.
GET DPA/{userKey}/Eligibility/{planId}?key_type={CPID,MSISDN}
Tieni presente che planId è l'identificatore univoco del piano che può essere utilizzato per acquistare il piano per conto dell'utente (consulta la sezione Acquisto dati).
Se planId non è specificato, l'DPA DEVE restituire tutti i piani acquistabili dall'utente.
La DPA DEVE restituire le cause degli errori più comuni in caso di errore. Inoltre, la DPA DEVE restituire un errore nei seguenti casi:
- L'ETD restituisce un codice di errore 400 BAD REQUEST che indica a GTAF che
planIdnon è valido. - L'ETD restituisce un codice di errore 409 CONFLICT che indica che
planIdnon è compatibile con il piano dati dell'utente.
In caso contrario, la DPA DEVE restituire una risposta di 200 OK. Il formato di una IdoneitàResponse riuscita è il seguente:
{
"eligiblePlans":
[
{
"planId": string, // Plan identifier. Can be used to
// refer to the plan during
// offers, etc. (req.)
}
]
}
Quando la richiesta include un planId, la risposta include solo quel piano. In caso contrario, l'elenco include tutti i piani che l'utente è idoneo ad acquistare. Se planId è vuoto e l'ETD non supporta la restituzione dell'elenco dei piani idonei, DEVE restituire un errore 400 BAD REQUEST.
Endpoint di registrazione MSISDN
Per pubblicare le applicazioni che hanno accesso a MSISDN, GTAF registra l'MSIDN con l'ETD. GTAF registra MSISDN solo quando sono presenti applicazioni pubblicate dall'API Google Mobile Data Plan Sharing, in cui l'ETD invia informazioni a GTAF utilizzando le API di Google. Per registrare il MSISDN, GTAF invia una richiesta POST alla DPA:
POST DPA_URL/registrazione
Il corpo della richiesta sarà un'istanza di RegistrationRequest.
{
"msisdn": "<msisdn_string>"
}
Se la registrazione del file MSISDN va a buon fine, l'ETD DEVE restituire una risposta 200 OK che includa RegistrationResponse. Il formato del JSON è:
{
// msisdn that was registered.
"msisdn": "<msisdn_string>",
// time after which DPA will not send updates to GTAF.
"expirationTime": string
}
La DPA DEVE quindi inviare aggiornamenti sul piano dati dell'utente a GTAF fino alla scadenza.
Se si verifica un errore, dovrebbe essere restituito ErrorResponse:
{
"error": "<error message>",
"cause": enum(ErrorCause)
}
L'elenco completo dei possibili valori causa e dei codici di stato HTTP per diverse condizioni di errore è disponibile qui. In particolare, se viene ricevuta una richiesta di registrazione MSISDN per un utente in roaming o che non ha scelto di condividere informazioni sul piano dati con Google, l'DPA DEVE restituire il codice di stato HTTP 403.
API Monitoring
In alcuni casi d'uso è necessario che GTAF monitori l'ETD e rilevi errori nell'ETD. Per questi casi d'uso, abbiamo definito un'API di monitoraggio.
Definizione di API
L'API Monitoring dovrebbe essere disponibile tramite richiesta GET HTTP al seguente URL:
DPA_URL/dpaStatus
Se l'ETD e tutti i suoi backend funzionano correttamente, l'ETD deve rispondere a questa query con il codice di stato HTTP 200 e un corpo di risposta con un'istanza di DpaStatus.
{
"status": enum(DpaStatusEnum),
"message": "<optional human-readable status description>"
}
Se l'ETD o uno dei suoi backend non funziona correttamente, deve rispondere con codice di stato HTTP 500 e un corpo di risposta con un'istanza di DpaStatus.
Comportamento DPA
Quando viene rilevato un errore, l'ETD deve restituire lo stato "NON DISPONIBILE" per tutte le query dpaStatus. Inoltre, deve interrompere l'invio di informazioni sul piano dati con lunghi periodi di memorizzazione nella cache. Potrebbe interrompere l'invio di risposte con lunghi periodi di cache in uno dei due modi seguenti:
- Inizia a impostare tempi di scadenza della cache brevi.
- Non inviare più le informazioni del piano dati.
Comportamento GTAF
Il GTAF eseguirà periodicamente il polling di dpaStatus. Quando rileva un errore DPA (in base alla risposta "NON DISPONIBILE") svuota la cache per l'operatore.
Casi di errore
In caso di errore, l'ETD dovrebbe restituire un codice di stato HTTP che corrisponda a una delle seguenti opzioni:
- Al momento l'utente è in roaming e la query DPA è disattivata per questo utente. L'ETD restituisce un errore 403.
- L'ETD restituisce un codice di errore 404 NOT_FOUND che indica a GTAF che la chiave utente non è valida, ovvero la chiave utente non esistente.
- L'ETD restituisce un codice di errore 410 GONE che indica a GTAF che il client deve ricevere una nuova chiave utente se key_type = CPID è scaduta.
- La DPA restituisce un codice di errore 501 NOT_IMPLEMENTED che indica che non supporta la chiamata.
- Servizio temporaneamente non disponibile. L'ETD restituisce un SERVIZIO 503 NON DISPONIBILE con l'intestazione Riprova dopo che è possibile tentare una nuova richiesta.
- La DPA restituisce un codice di errore 500 SERVER SERVER per tutti gli altri errori non specificati.
- L'ETD restituisce un errore TOO_MANY_REQUESTS 429 con l'intestazione Retry-After che indica che GTAF sta inviando troppe richieste all'ETD.
- L'ETD restituisce un errore CONFLICT 409 che indica che la richiesta non può essere completata a causa di un conflitto con l'attuale stato dell'ETD.
In tutti i casi di errore, il corpo della risposta HTTP DEVE includere un oggetto JSON con ulteriori informazioni sull'errore. Il corpo della risposta all'errore DEVE contenere un'istanza di ErrorResponse.
{
"error": string,
"cause": enum(ErrorCause)
}
I valori cause attualmente definiti sono elencati come parte di riferimento dell'API ErrorCause.
In caso contrario, l'ETD restituisce 200 OK. Abbiamo notato che questi valori cause vengono usati per tutte le risposte.
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.