Motivación
Como se mencionó en la descripción general, según los casos prácticos que el operador desee admitir, la APD debe implementar una combinación de la API de uso compartido del plan de datos móviles de Google y la API del agente del plan de datos. En este documento, se describe la API del Agente de plan de datos que Google usará para identificar los planes de datos móviles del usuario, recuperar información sobre estos planes y adquirir planes de datos.
Autenticación
Antes de que GTAF pueda llamar, la APD debe autenticar a GTAF. Como parte del proceso de integración de operadores, verificaremos la validez del certificado SSL de DPA. Actualmente, REQUIERES el uso de OAuth2 para la autenticación mutua. Consulta Autenticación del agente del plan de datos para obtener detalles sobre cómo se autentica GTAF con el DPA.
Internacionalización
Las solicitudes de GTAF a la APD incluyen un encabezado Accept-Language que indica el idioma en el que deberían estar las strings legibles (p.ej., las descripciones de los planes). Además, las respuestas de DPA (PlanStatus, PlanOffers) incluyen un campo de languageCode obligatorio cuyo valor es el código de idioma BCP-47 (p.ej., &en “EE.UU.” de la respuesta.
Si la APD 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 al suscriptor, cuando se consulta la APD del operador. Cuando GTAF consulta la APD en nombre de las aplicaciones que tienen acceso al MSISDN, GTAF PUEDE usar el MSISDN. En un nivel superior, la API del agente de planes de datos propuesta consta de los siguientes componentes:
- 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).
- Mecanismo para compartir los CPID que se pueden usar para enviar notificaciones a los usuarios.
- Mecanismo para compartir opciones de usuario sobre si se registrarán en nuestro servicio.
El resto de este documento explica cada uno de estos componentes de API. A menos que se indique explícitamente, todas las comunicaciones DEBEN realizarse por HTTPS (con un certificado SSL de DPA válido). Según las características reales que se admitan, un operador PUEDE implementar todos o algunos de estos componentes de API.
Interacción GTAF-DPA
Figura 4: Flujo de llamadas para solicitar y recibir información del plan de datos del usuario
En la figura 4, se ilustra el flujo de llamadas asociado con un cliente que consulta el estado del plan de datos del usuario y otra información del plan de datos. Este flujo de llamadas se comparte para las llamadas a la API que activa el cliente en la UE.
- El cliente solicita el estado del plan de datos o demás información mediante una llamada a una API de Google privada. El cliente incluye la clave del usuario en la solicitud para GTAF.
- GTAF usa la clave del usuario y un identificador de cliente para consultar el APD del operador. Los identificadores de cliente admitidos son mobiledataplan y youtube. Cuando la APD recibe una llamada con uno de estos identificadores de cliente, DEBE responder con información del plan que el cliente pueda usar.
- GTAF muestra la información solicitada al cliente, y la GTAF almacena en caché la información del plan hasta la fecha de vencimiento que especifica el APD.
Los pasos 1 y 3 de la figura 4 son API privadas de Google y, por lo tanto, no se describen con más detalle. El paso 2 es una API pública que se describe a continuación. La APD DEBE respetar el encabezado HTTP Cache-Control: no-cache cuando entrega 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 la APD se identifica mediante CLIENT_ID. Según el acuerdo entre el cliente y el operador de Google, la APD puede personalizar la respuesta a GTAF. En caso de tener éxito, el APD debe mostrar HTTP 200 de forma correcta con un cuerpo de respuesta que represente un PlanStatus. Consulta Casos de error para obtener una 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
}
}
}
}
Para los planes pospagos, expirationTime DEBE ser la fecha de recurrencia del plan (es decir, cuando se actualiza o se vuelve a cargar 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 equipos de Google individuales a fin de acordar el conjunto de categorías de tráfico y su semántica que son relevantes para las diferentes aplicaciones de Google.
Consulta ofertas del plan
GTAF emite la siguiente solicitud HTTP para obtener ofertas del plan 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 la APD se identifica mediante CLIENT_ID. Según el acuerdo entre el cliente y el operador de Google, la APD puede personalizar la respuesta a GTAF. El parámetro de contexto opcional proporciona el contexto de la aplicación en la que se realiza la solicitud. Por lo general, es una string que la aplicación le pasa al operador a través de GTAF.
En caso de tener éxito, el APD debe mostrar HTTP 200 de forma correcta con un cuerpo de respuesta que represente una PlanOffer. Consulta Casos de errores para obtener una 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 arreglo offers PUEDE determinar el orden en el que los planes de datos se presentan a los usuarios. Además, si la aplicación puede presentar solo x planes debido a la IU o a otras limitaciones, y la respuesta contiene y > x planes, solo se presentarán los primeros x planes. El GTAF comparte solo hasta 50 planes si la aplicación que busca ofertas es un módulo del plan de datos móviles que forma parte de los Servicios de Google Play. Esto es para garantizar una buena experiencia del usuario para los Servicios de Google Play.
Las ofertas de venta incremental tienen filterTags como parámetro opcional, que es un arreglo 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 tupla &tag; displaytext=">. Filter es una lista consolidada de filtros que se renderizarán en la IU. El usuario podría filtrar haciendo clic en el texto de visualización. La etiqueta correspondiente a displayText se usa para filtrar las ofertas.
Ten en cuenta que el operador DEBE tener un mecanismo para cumplir con una solicitud de compra de cualquier oferta que se extienda al usuario. El mecanismo a través del cual se le cobrará al usuario por cualquier compra se puede comunicar con GTAF mediante la opción formOfPayment en la respuesta.
Compra de datos
La API del plan de compra define cómo la GTAF puede comprar planes a través de la APD. GTAF inicia la transacción para comprar un plan de datos a la APD. La solicitud SHALL incluye 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 falla.
Solicitud de transacción
Una vez que recibe una solicitud de un cliente, el GTAF envía una solicitud POST a la APD. La URL de la solicitud es la siguiente:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
En el ejemplo anterior, 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
La APD generará una respuesta 200-OK solo para una transacción ejecutada con éxito o una transacción en cola. Consulta Casos de error para obtener una respuesta esperada en caso de errores. En el caso de una transacción en cola, el APD solo completará el estado de la transacción y dejará otros campos en la respuesta vacíos. La APD DEBE llamar a GTAF con una respuesta una vez que se haya manejado 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 planActivationTime, GTAF ASUMIRÁ que el plan se activó.
Registrar CPID
Cuando un cliente que admite notificaciones obtiene un CPID nuevo desde el extremo del CPID, registra el CPID con GTAF si los términos del cliente permiten que GTAF lo haga. Si el cliente registra correctamente el CPID con GTAF, GTAF registrará el CPID con el DPA mediante 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 hora a partir de la cual el CPID no se puede usar 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 buscan admitir el módulo de plan de datos móviles en los Servicios de Google Play. A fin de enviar notificaciones de manera confiable al usuario, el APD puede almacenar el CPID registrado más reciente de cada usuario. Consulta cómo elegir el CPID si deseas obtener orientación sobre cómo usar el CPID registrado para enviar notificaciones.
La APD generará una respuesta 200-OK si la APD asocia correctamente el CPID con el usuario y lo almacena de forma persistente. Consulta Casos de errores para obtener una respuesta esperada en caso de errores.
Consentimiento
GTAF PUEDE emitir la siguiente solicitud para pasar la preferencia de consentimiento del usuario al proveedor.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
En el ejemplo anterior, userKey es CPID o MSISDN. El cuerpo de la solicitud es una instancia de SetConsentStatusRequest. Si se realiza correctamente, el cuerpo de la respuesta debe estar vacío.
Todas las llamadas de GTAF a la APD siguen las Condiciones del Servicio del cliente de Google que realiza la llamada. Según las aplicaciones que el DPA busque admitir, depende del operador decidir si el DPA implementa esta API. Si la APD elige implementar la API de consentimiento, debe almacenar el estado de consentimiento más reciente de cada usuario. Consulta Elige el CPID para obtener instrucciones sobre cómo usar la información del estado de consentimiento.
En caso de tener éxito, el APD debe mostrar HTTP 200 de forma correcta con un cuerpo de respuesta vacío. Consulta Casos de error para obtener una respuesta esperada en caso de errores.