Motivation
Comme indiqué dans la présentation, en fonction des cas d'utilisation que l'opérateur souhaite traiter, le DPA doit mettre en œuvre 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 acheter des forfaits de données.
Authentification
Pour pouvoir appeler la GTAF, celui-ci doit l'authentifier. Dans le cadre du processus d'intégration des opérateurs, nous vérifierons la validité du certificat SSL du DPA. Nous EXIGONS actuellement l'utilisation du protocole OAuth2 pour l'authentification mutuelle. Veuillez consulter la page Authentification de l'agent de plan de données pour en savoir plus sur l'authentification du GTAF auprès du DPA.
Internationalization
Les requêtes GTAF envoyées au DPA comprennent un en-tête Accept-Language indiquant la langue dans laquelle les chaînes lisibles (par exemple, les descriptions de forfait) doivent être saisies. En outre, les réponses DPA (PlanStatus, PlanOffers) incluent un champ "languageCode" obligatoire dont la valeur correspond au code de langue BCP-47 (par exemple, fr-FR) 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 dans le champ languageCode.
Description de l'API
GTAF utilise la clé utilisateur, qui identifie un abonné auprès de l'opérateur lorsqu'il interroge l'APD de l'opérateur. Lorsque le GTAF interroge le DPA pour le compte d'applications ayant accès au MSISDN, il peut utiliser le MSISDN. De manière générale, l'API d'agent de forfait Data comprend les composants suivants:
- Mécanisme pour interroger l'état du forfait de données utilisateur
- Mécanisme d'interrogation de l'APD pour les offres de forfaits de données de l'utilisateur.
- Mécanisme pour modifier le forfait Internet de l'utilisateur (par exemple, acheter un nouveau forfait).
- Mécanisme permettant de partager les CPID pouvant être utilisés pour envoyer des notifications aux utilisateurs.
- Mécanisme pour partager les choix des utilisateurs concernant l'inscription à notre service.
Le reste de ce document détaille chacun de ces composants d'API. Sauf indication contraire, toutes les communications DOIVENT se faire via HTTPS (avec un certificat SSL DPA valide). En fonction des fonctionnalités réelles compatibles, l'opérateur peut choisir de mettre en œuvre tout ou partie de ces composants d'API.
Interaction GTAF-DPA
Figure 4. Flux d'appels pour demander et recevoir des informations sur le forfait de données utilisateur.
La figure 4 illustre le flux d'appels associé à un client interrogeant l'état du forfait Internet de l'utilisateur ainsi que d'autres informations sur le forfait. Ce flux d'appel est partagé pour les appels d'API déclenchés par le client dans 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 l'opérateur. Les identifiants client compatibles sont mobiledataplan et youtube. Lorsque le DPA reçoit un appel avec l'un de ces identifiants client, il DOIT répondre avec les informations de forfait que le client peut utiliser.
- Le GTAF renvoie les informations demandées au client, et les informations concernant le forfait sont mises en cache par le GTAF jusqu'à l'expiration du délai spécifié par le DPA.
Les étapes 1 et 3 de la figure 4 sont des API Google privées. Elles 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 lors de la diffusion de ces appels d'API à partir du GTAF.
Interroger l'état du forfait
La 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 la GTAF contacte le DPA est identifié à l'aide de CLIENT_ID. En fonction de l'accord conclu entre le client Google et l'opérateur, le DPA peut personnaliser la réponse à la GTAF. En cas de réussite, le DPA DOIT renvoyer le code HTTP 200 OK avec un corps de réponse représentant un PlanStatus. Veuillez consulter la section Cas d'erreur pour connaître les réponses attendues en cas d'erreurs.
{
"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 post-payés, expirationTime DOIT être la date de récurrence du forfait (c'est-à-dire, lorsque le solde de données est actualisé/rechargé).
Chaque module de forfait peut contenir plusieurs catégories de trafic du module Plan (PMTCs)pour modéliser le cas où un module du 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 individuelles pour s'accorder sur l'ensemble des catégories de trafic et leur sémantique pertinentes pour les différentes applications Google.
Interroger les offres du plan
La GTAF émet la requête HTTP suivante pour obtenir l'offre de forfait de l'opérateur:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
Le client au nom duquel la GTAF contacte le DPA est identifié à l'aide de CLIENT_ID. En fonction de l'accord conclu entre le client Google et l'opérateur, le DPA peut personnaliser la réponse à la GTAF. Le paramètre de contexte facultatif fournit le contexte de l'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 réussite, le DPA DOIT renvoyer le code HTTP 200 OK avec un corps de réponse représentant une PlanOffer. Veuillez consulter la section Cas d'erreur pour connaître les réponses attendues en cas d'erreurs.
{
"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 ils sont présentés aux utilisateurs. De plus, si l'application ne peut présenter que x plans en raison de l'interface utilisateur ou d'autres limites, et que la réponse contient y > x, seuls les x premiers plans doivent être présentés. Le GTAF ne partage que 50 plans au maximum si l'application interrogeant les offres est un module de forfait Internet mobile qui fait partie des services Google Play. Cela permet de garantir une bonne expérience aux utilisateurs des services Google Play.
Les offres de vente incitative comportent des paramètres de filtre en tant que paramètre facultatif. Il s'agit d'un tableau de tags associé à chaque plan. Tous ces tags doivent correspondre au tag, qui est un objet dans le filtre. Filter est un objet de premier niveau qui contient des tuples, des tags, des affichages texte.>. Filter est une liste consolidée de filtres qui sera affichée dans l'interface utilisateur. L'utilisateur peut filtrer en cliquant sur le texte affiché. Le tag correspondant à "displayText" permet de filtrer les offres.</tag,>
Notez que l'opérateur DOIT disposer d'un mécanisme pour répondre à une demande d'achat pour toute offre étendue à l'utilisateur. Le mécanisme via lequel l'utilisateur sera facturé pour tout achat peut être communiqué à la GTAF à l'aide de l'option formOfPayment dans la réponse.
Achat de données
L'API du plan d'achat définit la façon dont la GTAF peut acheter des plans via le DPA. La GTAF initialise la transaction pour acheter un forfait de données au DPA. La requête SHALL inclut un identifiant de transaction unique (transactionId) permettant de suivre les requêtes et d'éviter l'exécution de transactions en double. Le DPA DOIT répondre par une réponse de réussite/échec.
Demande de transaction
Lorsqu'il reçoit une requête d'un client, la GTAF envoie 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 CPID ou 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 à la transaction
Le DPA SHALL génère une réponse 200-OK uniquement pour une transaction exécutée avec succès ou une transaction en file d'attente. Consultez la section Cas d'erreur pour connaître les réponses attendues en cas d'erreurs. Dans le cas d'une 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 la 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 la propriété planActivationTime est manquante, la GTAF DOIT supposer que le plan a été activé.
Enregistrer le CPID
Lorsqu'un client qui prend en charge les notifications reçoit un nouveau CPID auprès du point de terminaison CPID, il l'enregistre auprès de la GTAF si les conditions du client autorisent GTAF à le faire. Si le client enregistre correctement le CPID auprès de la GTAF, celui-ci enregistre le CPID auprès du DPA via l'appel d'API suivant:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
où userKey est le CPID et le seul CLIENT_ID accepté est mobiledataplan. Le corps de la requête est une instance de RegisterCpidRequest. Il contient le délai après lequel le CPID ne peut plus être utilisé pour envoyer des notifications et se présente comme suit:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Cette API ne concerne que les opérateurs souhaitant utiliser le module de forfait de données mobiles dans les services Google Play. Pour envoyer des notifications de manière fiable à l'utilisateur, le DPA PEUT stocker le dernier CPID enregistré pour chaque utilisateur. Veuillez consulter la section Choisir le CPID pour savoir comment utiliser le CPID enregistré pour envoyer des notifications.
L'APD génère 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 les réponses attendues en cas d'erreurs.
Consentement
Le GTAF peut émettre la requête 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 CPID ou 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 la GTAF à l'APD suit les conditions d'utilisation du client Google qui effectue l'appel. En fonction des applications que le DPA souhaite prendre en charge, il appartient à l'opérateur de décider s'il met en œuvre cette API. Si l'APD choisit d'implémenter l'API Consent, il DOIT stocker le dernier état du consentement pour chaque utilisateur. Veuillez consulter la section Choisir le CPID pour savoir comment utiliser les informations sur l'état du consentement.
En cas de réussite, le DPA doit impérativement renvoyer le code HTTP 200 OK avec un corps de réponse vide. Veuillez consulter la section Cas d'erreur pour connaître les réponses attendues en cas d'erreurs.