Motivação
A API Google Mobile Data Plan Sharing permite que uma operadora envie informações sobre o plano de dados de um usuário (identificado por uma chave de usuário) para o GTAF. Nesta página, descrevemos o mecanismo pelo qual essas atualizações podem ser enviadas para o GTAF e, portanto, para os aplicativos do Google. No momento, a API permite que o DPA envie o status do plano de dados para o GTAF, que será usado por um cliente do Google.
Autenticação
Todas as solicitações da API Data Plan Sharing para o GTAF precisam ser autenticadas usando 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 do ISP para o ASN que o DPA representa. Consulte OAuth 2.0 do Google Cloud para contas de serviço (em inglês) para ver a documentação sobre como usar o OAuth com contas de serviço do Google Cloud.
Atualizações do plano de dados
No momento, a API Google Mobile Data Plan Sharing permite que uma operadora 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 ficando sem dados, um operador poderá enviar uma atualização de status do plano de dados para o GTAF, que poderá ser usado para enviar uma notificação de status do plano ao usuário.
Descrição da API
Figura 3. Interação entre GTAF e DPA quando o DPA compartilha o status do plano de dados com o GTAF.
Os aplicativos podem receber informações sobre o status do plano de dados compartilhadas com o GTAF de uma das duas maneiras:
- O UE chama o GTAF para 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 de um usuário ao GTAF. O GTAF armazena o status do plano e a chave de usuário associada até o prazo de validade especificado pela operadora.
- O aplicativo do Google em execução no 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 pesquisar o status do plano de dados do usuário. Em seguida, o GTAF retorna esse status ao aplicativo.
- O GTAF envia informações de status do plano de dados para o UE:
- Quando relevante, o status do plano de dados recebido da operadora é enviado diretamente para o UE. Em particular, o status do plano enviado é usado para atualizar o cache no dispositivo do módulo de plano de dados móveis nos Serviços do Google Play.
Compartilhamento do status do plano de dados
A DPA usa um POST HTTPS para criar e atualizar uma entrada de status de plano para um usuário ser usado por um cliente. No momento, o GTAF é compatível com mobiledataplan e youtube como identificadores de cliente válidos. Confira um exemplo de solicitação para um operador com asn 12345 e chave de usuário abcdef compartilhando informações do plano 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 vai retornar o código de resposta HTTP 200 e a entrada planStatus enviada por push com uma entrada de notificações, caso alguma notificação tenha sido enviada ao usuário. Se o GTAF identificar um problema com a solicitação, ele vai retornar um código de status HTTP no intervalo de 400 a 499. Se o GTAF não conseguir concluir uma solicitação devido a uma falha, ele vai retornar um código HTTP no intervalo de 500 a 599. As solicitações que recebem uma resposta no intervalo de 500 a 599 são consideradas passíveis de novas tentativas, e as que recebem uma resposta no intervalo de 400 a 499 geralmente não são. Casos de erro explica em detalhes as respostas de erro do GTAF.
Envio do status do plano para o cliente padrão
O GTAF oferece suporte à seguinte chamada em que o status do plano é enviado por push pelo operador sem especificar o cliente para o qual ele pode ser usado. Neste caso, presumimos que o status do plano é destinado ao cliente mobiledataplan e que a operadora pretende enviar uma notificação ao 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 oferecer suporte à internacionalização, o DPA precisa saber o idioma preferido do usuário, mesmo sem uma solicitação direta do GTAF. Para resolver esse problema, a solicitação ao 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, as strings legíveis por humanos em atualizações enviadas pelo DPA usando a API MDP precisarão usar as configurações fornecidas na solicitação de CPID.
A DPA PODE atualizar as preferências de idioma do usuário quando receber uma solicitação da GTAF com um cabeçalho "Accept-Language" e usar as preferências atualizadas para determinar o código de idioma em solicitações futuras à GTAF.
O DPA PRECISA especificar o idioma usado para strings visíveis ao usuário usando languageCode. O GTAF usa isso para criar o título e o corpo das notificações mostradas ao usuário.