Motivación
La API de Google Mobile Data Plan Sharing permite que un operador envíe información sobre el plan de datos de un usuario (identificado por la clave de usuario) a la GTAF. En esta página, describimos el mecanismo a través del cual estas actualizaciones se pueden enviar a la GTAF y, por lo tanto, a las aplicaciones de Google. Actualmente, la API permite que el DPA envíe el estado del plan de datos al GTAF para que lo consuma un cliente de Google.
Autenticación
Todas las solicitudes a la API de Data Plan Sharing de GTAF deben autenticarse con el servidor de OAuth2 de Google Cloud. Las solicitudes deben autenticarse como una cuenta de servicio que se haya incluido en la lista blanca del ISP Portal para el ASN que representa la DPA. Consulta OAuth 2.0 de Google Cloud para cuentas de servicio para obtener documentación sobre cómo usar OAuth con cuentas de servicio de Google Cloud.
Actualizaciones del plan de datos
Actualmente, la API de Google Mobile Data Plan Sharing permite que un operador comparta actualizaciones sobre el 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 a un usuario se le están acabando los datos, un operador puede enviar una actualización del estado del plan de datos al GTAF, que luego podría usar el GTAF para enviar una notificación del estado del plan al usuario.
Descripción de la API
Figura 3: Interacción entre GTAF y DPA cuando el DPA comparte el estado del plan de datos con GTAF.
Las aplicaciones pueden recibir información sobre el estado del plan de datos que se comparte con GTAF de una de las siguientes dos maneras:
- El UE llama a GTAF para obtener información sobre el estado del plan de datos:
- La DPA del operador usa la API de Data Plan Sharing para enviar el estado del plan de datos de un usuario al GTAF. GTAF almacena el estado del plan y su clave de usuario asociada hasta la hora de vencimiento especificada por el operador.
- La aplicación de Google que se ejecuta en el UE solicita la información del estado del plan de datos a través de una API interna de Google. La aplicación incluye la clave de 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 devuelve este estado a la aplicación.
- La GTAF envía información sobre el estado del plan de datos al UE:
- Cuando es pertinente, el estado del plan de datos que se recibe del operador se envía directamente al UE. En particular, el estado del plan enviado se usa para actualizar la caché en el dispositivo del módulo Plan de datos móviles en los Servicios de Google Play.
Estado del plan de uso compartido de datos
El DPA usa un POST de HTTPS para crear y actualizar una entrada de estado de plan existente para que un cliente la use. Actualmente, GTAF admite mobiledataplan y youtube como identificadores de cliente válidos. A continuación, se muestra un ejemplo de solicitud para un operador con el ASN 12345 y la clave de usuario abcdef que comparte información del plan 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 se completa correctamente, GTAF devolverá 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, devolverá un código de estado HTTP en el rango de 400 a 499. Si GTAF no puede completar una solicitud debido a una falla, devolverá un código HTTP en el rango de 500 a 599. Las solicitudes que reciben una respuesta en el rango de 500 a 599 se consideran reintentables, y las solicitudes que reciben una respuesta en el rango de 400 a 499 generalmente no son reintentables. En Error Cases, se explican en detalle las respuestas de error de GTAF.
Envío de estado del plan para el 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, el DPA debe conocer el idioma preferido del usuario, incluso sin una solicitud directa del GTAF. Para resolver este problema, la solicitud al extremo de CPID PUEDE incluir un encabezado Accept-Language según el acceso de los clientes a las preferencias de idioma del usuario. Si se incluye el encabezado, las cadenas legibles para humanos en las actualizaciones que el DPA envía a través de la API de MDP deben usar la configuración proporcionada en la solicitud de CPID.
El DPA PUEDE actualizar las preferencias de idioma del usuario cuando recibe una solicitud del GTAF con un encabezado Accept-Language y usar las preferencias del usuario actualizadas para determinar el código de idioma en solicitudes futuras al GTAF.
El DPA DEBE especificar el idioma que se usa para las cadenas visibles para el usuario con languageCode. GTAF usa esta información para crear el título y el cuerpo de las notificaciones que se muestran al usuario.