Motivation
Comme indiqué dans la présentation, selon les cas d'utilisation que l'opérateur souhaite prendre en charge, le DPA doit implémenter une combinaison de l'API Google Mobile Data Plan Sharing et de l'API Data Plan Agent. Ce document décrit l'API Data Plan Agent que Google utilisera pour identifier les forfaits de données mobiles de l'utilisateur, récupérer des informations sur ces forfaits et en acheter.
Authentification
Avant que GTAF puisse appeler, le DPA doit authentifier GTAF. Lors de la procédure d'intégration des opérateurs, nous vérifions la validité du certificat SSL DPA. Nous EXIGEONS actuellement l'utilisation d'OAuth2 pour l'authentification mutuelle. Pour savoir comment GTAF s'authentifie auprès du DPA, consultez Authentification de l'agent du forfait de données.
Internationalisation
Les requêtes GTAF envoyées au DPA incluent un en-tête Accept-Language indiquant la langue dans laquelle les chaînes lisibles (par exemple, les descriptions des forfaits) doivent être affichées. De plus, les réponses DPA (PlanStatus, PlanOffers) incluent un champ languageCode obligatoire dont la valeur est le code de langue BCP-47 (par exemple, "en-US") de la réponse.
Si le DPA n'est pas compatible avec la langue demandée par l'utilisateur, il peut utiliser une langue par défaut et indiquer son choix à l'aide du champ "languageCode".
Description de l'API
GTAF utilise une clé utilisateur, qui identifie un abonné à l'opérateur, lorsqu'il interroge le DPA de l'opérateur. Lorsque GTAF interroge le DPA au nom des applications ayant accès au MSISDN, il PEUT utiliser le MSISDN. De manière générale, l'API Data Plan Agent proposée comprend les composants suivants :
- Mécanisme permettant d'interroger l'état du forfait de données de l'utilisateur.
- Mécanisme permettant d'interroger le DPA pour obtenir des offres de forfaits de données pour l'utilisateur.
- Mécanisme permettant de modifier le forfait de données de l'utilisateur (par exemple, en souscrivant un nouveau forfait).
- Mécanisme permettant de partager les CPID pouvant être utilisés pour envoyer des notifications aux utilisateurs.
- Mécanisme permettant de partager les choix des utilisateurs concernant leur inscription à notre service.
Le reste de ce document développe chacun de ces composants de l'API. Sauf indication contraire, toutes les communications DOIVENT se faire via HTTPS (avec un certificat SSL DPA valide). Selon les fonctionnalités réellement prises en charge, un opérateur PEUT choisir d'implémenter tout ou partie de ces composants d'API.
Interaction entre GTAF et DPA
Figure 4 Flux d'appel pour demander et recevoir des informations sur le forfait de données de l'utilisateur.
La figure 4 illustre le flux d'appels associé à un client qui interroge l'état du forfait de données de l'utilisateur et d'autres informations sur le forfait de données. Ce flux d'appels est partagé pour les appels d'API déclenchés par le client sur l'UE.
- Le client demande l'état du forfait de données et/ou d'autres informations en appelant une API Google privée. Le client inclut la clé utilisateur dans la requête envoyée à GTAF.
- GTAF utilise la clé utilisateur et un identifiant client pour interroger le DPA de l'opérateur. Les identifiants client acceptés sont mobiledataplan et youtube. Lorsque le DPA reçoit un appel avec l'un de ces identifiants client, il DOIT répondre avec des informations sur le forfait que le client peut utiliser.
- GTAF renvoie les informations demandées au client, et les informations sur le forfait sont mises en cache par GTAF jusqu'à l'expiration spécifiée par le DPA.
Les étapes 1 et 3 de la figure 4 sont des API Google privées et ne sont donc pas décrites plus en détail. L'étape 2 est une API publique décrite ci-dessous. Le DPA DOIT respecter l'en-tête HTTP Cache-Control: no-cache lorsqu'il traite ces appels d'API depuis GTAF.
Interroger l'état du forfait de données
GTAF émet la requête HTTP suivante pour obtenir l'état du forfait :
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
Le client au nom duquel GTAF contacte l'APD est identifié à l'aide de CLIENT_ID. En fonction de l'accord entre le client Google et l'opérateur, le DPA peut personnaliser la réponse à GTAF. En cas de succès, le DPA DOIT renvoyer HTTP 200 OK avec un corps de réponse représentant un PlanStatus. Veuillez consulter la section Cas d'erreur pour connaître la réponse attendue en cas d'erreur.
{
"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
}
}
}
}
Pour les forfaits postpayés, expirationTime DOIT correspondre à la date de récurrence du forfait (c'est-à-dire la date à laquelle le solde de données est actualisé/rechargé).
Chaque module de forfait peut contenir plusieurs catégories de trafic de module de forfait (PMTCs)) pour modéliser le cas où un module de forfait est partagé entre plusieurs applications (par exemple, 500 Mo pour les jeux et la musique). Les PMTC suivants sont prédéfinis : GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING.. Les opérateurs doivent contacter les équipes Google concernées pour définir l'ensemble des catégories de trafic et leur sémantique qui sont pertinentes pour les différentes applications Google.
Interroger les offres de forfait
GTAF envoie la requête HTTP suivante pour obtenir les offres de forfaits de l'opérateur :
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Le client au nom duquel GTAF contacte l'APD est identifié à l'aide de CLIENT_ID. En fonction de l'accord entre le client Google et l'opérateur, le DPA peut personnaliser la réponse à GTAF. Le paramètre de contexte facultatif fournit le contexte d'application dans lequel la requête est effectuée. Il s'agit généralement d'une chaîne que l'application transmet à l'opérateur via GTAF.
En cas de succès, le DPA DOIT renvoyer HTTP 200 OK avec un corps de réponse représentant un PlanOffer. Veuillez consulter la section Cas d'erreur pour connaître la réponse attendue en cas d'erreur.
{
"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'ordre des forfaits de données dans le tableau offers PEUT déterminer l'ordre dans lequel les forfaits de données sont présentés aux utilisateurs. De plus, si l'application ne peut présenter que x forfaits en raison de limitations de l'UI ou d'autres limitations, et que la réponse contient y > x forfaits, seuls les x premiers forfaits DOIVENT être présentés. GTAF ne partage que 50 forfaits maximum si l'application qui interroge les offres est le module de forfait de données mobiles qui fait partie des services Google Play. Cela permet de garantir une bonne expérience utilisateur pour les utilisateurs des services Google Play.
Les offres de vente incitative ont filterTags comme paramètre facultatif, qui est un tableau de tags associés à chaque forfait. Tous ces filterTags doivent correspondre au tag qui est un objet à l'intérieur du filtre. Filter est un objet de premier niveau qui contient un tuple<tag, displaytext="">. Filter est une liste consolidée de filtres qui seront affichés dans l'UI. L'utilisateur peut filtrer les résultats en cliquant sur DisplayText. La balise correspondant à displayText est utilisée pour filtrer les offres.</tag,>
Notez que l'opérateur DOIT disposer d'un mécanisme permettant de répondre à une demande d'achat pour toute offre proposée à l'utilisateur. Le mécanisme par lequel l'utilisateur sera facturé pour tout achat peut être communiqué à GTAF à l'aide de l'option formOfPayment dans la réponse.
Achat de données
L'API Purchase Plan définit la manière dont GTAF peut acheter des forfaits via le DPA. GTAF initie la transaction pour acheter un forfait de données auprès de la DPA. La requête DOIT inclure un identifiant de transaction unique (transactionId) pour suivre les requêtes et éviter l'exécution de transactions en double. La DPA DOIT répondre avec une réponse de réussite/échec.
Demande de transaction
Une fois qu'il reçoit une demande d'un client, GTAF émet une requête POST au DPA. L'URL de la requête est la suivante :
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
où userKey est un CPID ou un MSISDN. Le corps de la requête est une instance de TransactionRequest qui inclut les champs suivants :
{
"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.
}
Réponse de la transaction
Le DPA DOIT générer une réponse 200-OK uniquement pour une transaction exécutée ou mise en file d'attente. Veuillez consulter Cas d'erreur pour connaître la réponse attendue en cas d'erreur. En cas de transaction en file d'attente, le DPA ne doit renseigner que l'état de la transaction et laisser les autres champs de la réponse vides. Le DPA DOIT rappeler GTAF avec une réponse une fois qu'une transaction en file d'attente a été traitée. Le corps de la réponse est une instance de TransactionResponse qui inclut les informations suivantes :
{
"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.
}
}
Si le planActivationTime est manquant, GTAF DOIT supposer que le forfait a été activé.
Enregistrer un CPID
Lorsqu'un client compatible avec les notifications reçoit un nouveau CPID à partir du point de terminaison CPID, il enregistre le CPID auprès de GTAF si les conditions d'utilisation du client l'y autorisent. Si le client enregistre le CPID auprès de GTAF, GTAF enregistre le CPID auprès de la DPA à l'aide de l'appel d'API suivant :
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
où userKey correspond au CPID et le seul CLIENT_ID accepté est mobiledataplan. Le corps de la requête est une instance de RegisterCpidRequest et contient l'heure après laquelle le CPID ne peut plus être utilisé pour envoyer des notifications. Il se présente comme suit :
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Cette API ne concerne que les opérateurs qui souhaitent prendre en charge le module "Forfait de données mobiles" dans les services Google Play. Afin d'envoyer des notifications de manière fiable à l'utilisateur, le DPA PEUT stocker le dernier CPID enregistré pour chaque utilisateur. Pour savoir comment utiliser le CPID enregistré pour envoyer des notifications, consultez Choisir un CPID.
Le DPA doit générer une réponse 200-OK s'il associe correctement le CPID à l'utilisateur et le stocke de manière persistante. Veuillez consulter la section Cas d'erreur pour connaître la réponse attendue en cas d'erreur.
Consentement
GTAF PEUT émettre la demande suivante pour transmettre la préférence de consentement de l'utilisateur à l'opérateur.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
où userKey est un CPID ou un MSISDN. Le corps de la requête est une instance de SetConsentStatusRequest. Si la requête aboutit, le corps de la réponse doit être vide.
Chaque appel de GTAF au DPA respecte les conditions d'utilisation du client Google qui effectue l'appel. Selon les applications que le DPA souhaite prendre en charge, il appartient à l'opérateur de décider si le DPA implémente cette API. Si la DPA choisit d'implémenter l'API de consentement, elle DOIT stocker le dernier état de consentement pour chaque utilisateur. Pour savoir comment utiliser les informations sur l'état du consentement, consultez Choisir un CPID.
En cas de succès, le DPA DOIT renvoyer le code HTTP 200 OK avec un corps de réponse vide. Veuillez consulter Cas d'erreur pour connaître la réponse attendue en cas d'erreur.