Motivación
La API de uso compartido del plan de datos móviles de Google permite que un operador envíe información sobre el plan de datos de un usuario (identificado por la clave del usuario) a GTAF. En esta página, describimos el mecanismo mediante el cual se pueden enviar estas actualizaciones al GTAF y, por lo tanto, a las aplicaciones de Google. Actualmente, la API permite que la APD envíe el estado del plan de datos a GTAF para que lo consuma un cliente de Google.
Autenticación
Todas las solicitudes a la API de uso compartido del plan de datos para GTAF deben autenticarse con el servidor OAuth2 de Google Cloud. Las solicitudes deben autenticarse como una cuenta de servicio que se incluyó en la lista blanca en el portal de ISP para el ASN que representa el APD. Consulta Google Cloud OAuth 2.0 para cuentas de servicio a fin de obtener documentación sobre cómo usar OAuth con cuentas de servicio de Google Cloud.
Actualizaciones del plan de datos
Actualmente, la API de uso compartido del plan de datos móviles de Google permite a un operador compartir actualizaciones acerca del plan de datos de un usuario:
- Estado del plan de datos: captura el estado actual del plan de datos de un usuario. Por ejemplo, si un usuario se queda sin datos, un operador puede enviar una actualización de estado del plan de datos a GTAF, que el GTAF podría usar para enviar una notificación del estado del plan.
Descripción de la API
Figura 3: Interacción de GTAF-DPA cuando la DPA comparte el estado del plan de datos con GTAF.
Las aplicaciones pueden recibir información del estado del plan de datos compartida con GTAF de una de las siguientes maneras:
- UE llama a GTAF para obtener información sobre el estado del plan de datos:
- El DPA del operador usa la API de uso compartido del plan de datos para enviar el estado del plan de datos de un usuario a GTAF. GTAF almacena el estado del plan y su clave de usuario asociada hasta la hora de vencimiento que especifica el operador.
- La aplicación de Google que se ejecuta en la UE solicita la información de estado del plan de datos mediante una API interna de Google. La aplicación incluye la clave del usuario en su solicitud.
- Si la aplicación puede usar el estado del plan de datos almacenado en caché, GTAF usa la clave del usuario para buscar el estado del plan de datos del usuario. Luego, GTAF muestra este estado a la aplicación.
- GTAF envía la información de estado del plan de datos a la UE:
- Cuando es relevante, el estado del plan de datos que recibe del operador se envía directamente al UE. En particular, el estado del plan enviado se usa para actualizar la caché del dispositivo del módulo de plan de datos móviles de los Servicios de Google Play.
Compartir el estado del plan de datos
La APD usa una solicitud HTTPS POST a fin de crear y actualizar una entrada de estado del plan existente para que un cliente la use. Actualmente, la GTAF admite mobiledataplan y youtube como identificadores de cliente válidos. Esta es una solicitud de ejemplo para un operador con ASN 12345 y la información del plan de uso compartido abcdef de la clave de usuario con GTAF para el cliente youtube:
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus
El cuerpo de la solicitud es una instancia de 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"
}]
}],
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 569
}
}
},
"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"
}
Si la solicitud tiene éxito, GTAF mostrará el código de respuesta HTTP 200 y la entrada planStatus enviada con una entrada de notificaciones si se envió alguna notificación al usuario. Si GTAF identifica un problema con la solicitud, mostrará un código de estado HTTP en el rango 400-499. Si GTAF no puede completar una solicitud debido a una falla de GTAF, GTAF mostrará un código HTTP en el rango 500-599. Las solicitudes que reciben una respuesta en el rango 500-599 se consideran que se pueden reintentar y las que reciben una respuesta en el rango 400-499, por lo general, no se pueden reintentar. Los casos de error explican en detalle las respuestas de error de GTAF.
Enviar estado del plan al cliente predeterminado
GTAF admite la siguiente llamada en la que el operador envía el estado del plan sin especificar el cliente para el que se puede usar. En este caso, suponemos que el estado del plan está destinado al cliente mobiledataplan y que el operador pretende enviar una notificación al usuario. El cuerpo de la solicitud es una instancia de PlanStatus.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internacionalización
Para admitir la internacionalización, la APD debe conocer el idioma preferido del usuario, incluso sin una solicitud directa del GTAF. Para resolver este problema, la solicitud al extremo CPID PUEDE incluir un encabezado Accept-Language según los accesos del cliente a las preferencias de idioma del usuario. Si se incluye el encabezado, las strings legibles en las actualizaciones que envía el DPA mediante la API de MDP deben usar la configuración proporcionada en la solicitud de CPID.
La APD puede actualizar las preferencias de idioma del usuario cuando recibe una solicitud de GTAF con un encabezado Accept-Language y usar las preferencias de usuario actualizadas para determinar el código de idioma en solicitudes futuras al GTAF.
La APD DEBE especificar el idioma usado para las strings visibles del usuario mediante languageCode. GTAF usa esto para crear el título y el cuerpo de las notificaciones que se muestran al usuario.