Motivação
A API de compartilhamento de planos de dados móveis do Google permite que um operador envie informações sobre um plano de dados do usuário (identificado por chave de usuário) para o GTAF. Nesta página, descrevemos o mecanismo pelo qual essas atualizações podem ser enviadas à GTAF e aos aplicativos do Google. Atualmente, a API permite que a DPA envie o status do plano de dados ao GTAF para ser consumido por um cliente do Google.
Autenticação
Todas as solicitações da API Data Plan Sharing para o GTAF precisam ser autenticadas com o servidor OAuth2 do Google Cloud. As solicitações precisam ser autenticadas como uma conta de serviço que foi adicionada à lista de permissões no Portal ISP para o ASN que a DPA representa. Consulte Google Cloud OAuth 2.0 para contas de serviço para ver a documentação sobre como usar o OAuth com contas de serviço do Google Cloud.
Atualizações no plano de dados
Atualmente, a API de compartilhamento de planos de dados móveis do Google permite que um operador compartilhe atualizações sobre o plano de dados de um usuário:
- Status do plano de dados:captura o status atual do plano de dados de um usuário. Por exemplo, se um usuário estiver sem dados, um operador poderá enviar uma atualização de status do plano de dados ao GTAF, que poderá ser usado pelo GTAF para enviar uma notificação de status do plano ao usuário.
Descrição da API
Figura 3. Interação do GTAF-DPA quando o DPA compartilha o status do plano de dados com o GTAF.
Os apps podem receber informações de status do plano de dados compartilhados com o GTAF de duas maneiras:
- A UE chama o GTAF para ver informações de status do plano de dados:
- A DPA do operador usa a API Data Plan Sharing para enviar o status do plano de dados do usuário para o GTAF. O GTAF armazena o status do plano e a chave de usuário associada até o prazo de validade especificado pelo operador.
- O aplicativo do Google em execução na UE solicita as informações de status do plano de dados usando uma API interna do Google. O aplicativo inclui a chave de usuário na solicitação.
- Se o aplicativo puder usar o status do plano de dados em cache, o GTAF usará a chave do usuário para procurar o status do plano de dados do usuário. O GTAF retorna esse status para o aplicativo.
- O GTAF envia as informações de status do plano de dados para a UE:
- Quando relevante, o status do plano de dados recebido do operador é enviado diretamente para o UE. Especificamente, o status do plano enviado é usado para atualizar o cache do dispositivo do módulo do plano de dados para dispositivos móveis no Google Play Services.
Status de compartilhamento do plano de dados
A DPA usa um POST HTTPS para criar e atualizar uma entrada de status de plano existente para que um usuário seja usado por um cliente. No momento, o GTAF é compatível com mobiledataplan e youtube como identificadores válidos de clientes. Veja um exemplo de solicitação para um operador com asn 12345 e as informações do plano de compartilhamento key key abcdef do usuário com o GTAF para o cliente youtube:
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus
O corpo da solicitação é uma instância 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"
}
Se a solicitação for bem-sucedida, o GTAF retornará o código de resposta HTTP 200 e a entrada planStatus enviada com uma notificação, se alguma tiver sido enviada ao usuário. Se o GTAF identificar um problema com a solicitação, ele retornará um código de status HTTP no intervalo 400-499. Se o GTAF não conseguir concluir uma solicitação devido a uma falha do GTAF, um código HTTP no intervalo de 500 a 599 retornará um código HTTP. As solicitações que recebem uma resposta no intervalo de 500 a 599 são consideradas reproduzíveis, e as solicitações que recebem uma resposta no intervalo de 400 a 499 geralmente não podem ser tentadas novamente. O artigo Casos de erro explica as respostas de erro do GTAF em detalhes.
Push de status do plano para cliente padrão
O GTAF oferece suporte à seguinte chamada, em que o status do plano é enviado pelo operador sem especificar o cliente para o qual ele pode ser usado. Nesse caso, supomos que o status do plano é destinado ao cliente mobiledataplan e que o operador pretende enviar uma notificação para o usuário. O corpo da solicitação é uma instância de PlanStatus.
POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef
Internacionalização
Para apoiar a internacionalização, a DPA precisa saber o idioma preferido do usuário, mesmo sem uma solicitação direta do GTAF. Para resolver esse problema, a solicitação para o endpoint CPID PODE incluir um cabeçalho Accept-Language, dependendo do acesso dos clientes às preferências de idioma do usuário. Se o cabeçalho for incluído, strings legíveis em atualizações que a DPA envia usando a API MDP precisam usar as configurações fornecidas na solicitação CPID.
A DPA pode atualizar as preferências de idioma do usuário ao receber uma solicitação do GTAF com um cabeçalho Accept-Language e usar as preferências atualizadas do usuário para determinar o código do idioma em solicitações futuras para o GTAF.
A DPA PRECISA especificar o idioma usado para strings visíveis do usuário usando languageCode. O GTAF usa isso para criar o título e o corpo das notificações mostradas ao usuário.