Motivación
Como se mencionó en la descripción general, según los casos de uso que el operador desee admitir, el DPA debe implementar una combinación de la API de Google Mobile Data Plan Sharing y la API de Data Plan Agent. En este documento, se describe la API de Data Plan Agent que Google usará para identificar los planes de datos móviles del usuario, recuperar información sobre estos planes y comprar planes de datos.
Autenticación
Antes de que GTAF pueda llamar, el DPA debe autenticar GTAF. Como parte del proceso de incorporación del operador, verificaremos la validez del certificado SSL del DPA. Actualmente, EXIGIMOS el uso de OAuth2 para la autenticación mutua. Consulta Autenticación del agente del plan de datos para obtener detalles sobre cómo GTAF se autentica con el DPA.
Internacionalización
Las solicitudes de GTAF a la DPA incluyen un encabezado Accept-Language que indica el idioma en el que deben estar las cadenas legibles por humanos (p.ej., las descripciones de los planes). Además, las respuestas de la DPA (PlanStatus, PlanOffers) incluyen un campo languageCode obligatorio cuyo valor es el código de idioma BCP-47 (p.ej., "en-US") de la respuesta.
Si la DPA no admite el idioma que solicitó el usuario, puede usar un idioma predeterminado y el campo languageCode para indicar su elección.
Descripción de la API
GTAF usa la clave del usuario, que identifica a un suscriptor del operador, cuando consulta la DPA del operador. Cuando GTAF consulta el DPA en nombre de las aplicaciones que tienen acceso al MSISDN, GTAF PUEDE usar el MSISDN. A grandes rasgos, la API del agente de planes de datos propuesta comprende los siguientes componentes:
- Es un mecanismo para consultar el estado del plan de datos del usuario.
- Mecanismo para consultar al DPA sobre las ofertas de planes de datos para el usuario.
- Mecanismo para realizar cambios en el plan de datos del usuario (p. ej., comprar un plan nuevo)
- Es un mecanismo para compartir los CPID que se pueden usar para enviar notificaciones a los usuarios.
- Mecanismo para compartir las opciones del usuario sobre si registrarse en nuestro servicio.
En el resto de este documento, se explica cada uno de estos componentes de la API. A menos que se indique explícitamente, todas las comunicaciones DEBEN realizarse a través de HTTPS (con un certificado SSL de DPA válido). Según las funciones reales que se admitan, un operador PUEDE optar por implementar todos los componentes de estas APIs o un subconjunto de ellos.
Interacción entre GTAF y DPA
Figura 4: Flujo de llamadas para solicitar y recibir información sobre el plan de datos del usuario.
En la figura 4, se ilustra el flujo de llamadas asociado con un cliente que consulta sobre el estado del plan de datos del usuario y otra información relacionada con el plan de datos. Este flujo de llamadas se comparte para las llamadas a la API que activa el cliente en el UE.
- El cliente solicita el estado del plan de datos o cualquier otra información llamando a una API privada de Google. El cliente incluye la clave de usuario en la solicitud a GTAF.
- La GTAF usa la clave del usuario y un identificador de cliente para consultar el DPA del operador. Los identificadores de cliente admitidos son mobiledataplan y youtube. Cuando el DPA recibe una llamada con uno de estos identificadores de cliente, DEBE responder con información del plan que el cliente pueda usar.
- GTAF devuelve la información solicitada al cliente, y GTAF almacena en caché la información del plan hasta la hora de vencimiento especificada por el DPA.
Los pasos 1 y 3 de la figura 4 son APIs privadas de Google y, por lo tanto, no se describen más. El paso 2 es una API pública que se describe a continuación. El DPA DEBE respetar el encabezado HTTP Cache-Control: no-cache cuando publique estas llamadas a la API desde GTAF.
Consulta el estado del plan de datos
GTAF emite la siguiente solicitud HTTP para obtener el estado del plan:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
El cliente en nombre del cual GTAF se comunica con el DPA se identifica con CLIENT_ID. Según el acuerdo entre el operador y el cliente de Google, la DPA puede personalizar la respuesta a la GTAF. En caso de éxito, el DPA DEBE devolver HTTP 200 OK con un cuerpo de respuesta que represente un PlanStatus. Consulta Casos de error para ver la respuesta esperada en caso de errores.
{
"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
}
}
}
}
En el caso de los planes pospagados, expirationTime DEBE ser la fecha de recurrencia del plan (es decir, cuando se actualiza o recarga el saldo de datos).
Cada módulo del plan puede contener varias categorías de tráfico del módulo del plan (PMTCs)para modelar el caso en el que un módulo del plan se comparte entre varias apps, p.ej., 500 MB para juegos y música Los siguientes PMTC están predefinidos: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING. Se espera que los operadores se comuniquen con los equipos individuales de Google para acordar el conjunto de categorías de tráfico y su semántica que son relevantes para las diferentes aplicaciones de Google.
Consulta de ofertas de planes
GTAF emite la siguiente solicitud HTTP para obtener ofertas de planes del operador:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
El cliente en nombre del cual GTAF se comunica con el DPA se identifica con CLIENT_ID. Según el acuerdo entre el operador y el cliente de Google, la DPA puede personalizar la respuesta a la GTAF. El parámetro de contexto opcional proporciona el contexto de la aplicación en el que se realiza la solicitud. Por lo general, es una cadena que la aplicación pasa al operador a través de GTAF.
En caso de éxito, el DPA DEBE devolver HTTP 200 OK con un cuerpo de respuesta que represente un PlanOffer. Consulta Casos de error para ver la respuesta esperada en caso de errores.
{
"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.
}
El orden de los planes de datos en el array offers PUEDE determinar el orden en el que se presentan los planes de datos a los usuarios. Además, si la aplicación solo puede presentar x planes debido a limitaciones de la IU o de otro tipo, y la respuesta contiene y > x planes, SOLO se presentarán los primeros x planes. GTAF comparte hasta 50 planes solo si la aplicación que consulta las ofertas es el módulo de planes de datos móviles, que forma parte de los Servicios de Google Play. Esto es para garantizar una buena experiencia del usuario para los usuarios de los Servicios de Google Play.
Las ofertas de venta adicional tienen filterTags como parámetro opcional, que es un array de etiquetas adjuntas a cada plan. Todas estas filterTags deben coincidir con la etiqueta, que es un objeto dentro de Filter. Filter es un objeto de primer nivel que contiene una tupla<tag, displaytext="">. Filter es una lista consolidada de filtros que se renderizarán en la IU. El usuario podía filtrar haciendo clic en DisplayText. La etiqueta correspondiente a displayText se usa para filtrar las ofertas.</tag,>
Ten en cuenta que el operador DEBE tener un mecanismo para completar una solicitud de compra de cualquier oferta que se extienda al usuario. El mecanismo a través del cual se le cobrará al usuario cualquier compra se puede comunicar con GTAF usando la opción formOfPayment en la respuesta.
Compra de datos
La API de planes de compra define cómo GTAF puede comprar planes a través del DPA. El GTAF inicia la transacción para comprar un plan de datos al DPA. La solicitud DEBE incluir un identificador de transacción único (transactionId) para hacer un seguimiento de las solicitudes y evitar la ejecución de transacciones duplicadas. La APD DEBE responder con una respuesta de éxito o error.
Solicitud de transacción
Una vez que recibe una solicitud de un cliente, GTAF emite una solicitud POST a la DPA. La URL de la solicitud es la siguiente:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
donde userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de TransactionRequest que incluye los siguientes campos:
{
"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.
}
Respuesta de la transacción
El DPA DEBE generar una respuesta 200-OK solo para una transacción ejecutada correctamente o una transacción en cola. Consulta Casos de error para ver la respuesta esperada en caso de errores. En el caso de una transacción en cola, el DPA solo debe completar el estado de la transacción y dejar vacíos los demás campos de la respuesta. El DPA DEBE llamar al GTAF con una respuesta una vez que se haya procesado una transacción en cola. El cuerpo de la respuesta es una instancia de TransactionResponse que incluye los siguientes detalles:
{
"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 falta el parámetro planActivationTime, GTAF DEBE suponer que el plan se activó.
Registra el CPID
Cuando un cliente que admite notificaciones obtiene un CPID nuevo del extremo de CPID, registra el CPID en GTAF si las condiciones del cliente lo permiten. Si el cliente registra el CPID correctamente en GTAF, GTAF registrará el CPID en el DPA con la siguiente llamada a la API:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
donde userKey es el CPID y el único CLIENT_ID admitido es mobiledataplan. El cuerpo de la solicitud es una instancia de RegisterCpidRequest y contiene la fecha y hora después de la cual no se puede usar el CPID para enviar notificaciones, y se ve de la siguiente manera:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Esta API solo es relevante para los operadores que desean admitir el módulo Plan de datos móviles en los Servicios de Google Play. Para enviar notificaciones de forma confiable al usuario, el DPA PUEDE almacenar el CPID registrado más reciente para cada usuario. Consulta Cómo elegir un CPID para obtener orientación sobre cómo usar el CPID registrado para enviar notificaciones.
La DPA generará una respuesta 200-OK si asocia correctamente el CPID con el usuario y lo almacena de forma persistente. Consulta Casos de error para ver la respuesta esperada en caso de errores.
Consentimiento
Es posible que GTAF emita la siguiente solicitud para pasar la preferencia de consentimiento del usuario al operador.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
donde userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de SetConsentStatusRequest. Si se ejecuta correctamente, el cuerpo de la respuesta debe estar vacío.
Cada llamada de GTAF a la DPA sigue las condiciones del servicio del cliente de Google que realiza la llamada. Según las aplicaciones que el DPA quiera admitir, el operador deberá decidir si el DPA implementa esta API. Si el DPA decide implementar la API de Consentimiento, DEBE almacenar el estado de consentimiento más reciente para cada usuario. Consulta Cómo elegir un CPID para obtener orientación sobre cómo usar la información del estado de consentimiento.
En caso de éxito, el DPA DEBE devolver HTTP 200 OK con un cuerpo de respuesta vacío. Consulta Casos de error para ver la respuesta esperada en caso de errores.