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 pela 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, uma operadora poderá enviar uma atualização de status do plano de dados para o GTAF, que poderá ser usado para enviar uma notificação de saldo baixo ao usuário.
Identificar usuários relevantes
O DPA precisa de uma maneira de determinar quais dados de usuários enviar ao GTAF. O GTAF espera receber atualizações para os seguintes usuários:
- CPIDs ativos: usuários com CPIDs ativos. Até que os CPIDs gerados pelo endpoint sejam válidos, a DPA DEVE enviar atualizações sobre o plano de dados de um usuário. Se o cabeçalho
Accept-Languagefoi definido no momento da criação do CPID, as strings legíveis por humanos no status do plano de dados PRECISAM estar nesse idioma. - MSISDNs registradas: para veicular aplicativos que têm acesso ao MSISDN, o GTAF vai registrar o MSISDN com o DPA, conforme descrito na seção registro de MSISDN da API Data Plan Agent. Depois que o MSISDN é registrado, o DPA DEVE enviar atualizações sobre o plano de dados do usuário até que o registro expire.
Descrição da API
Compartilhamento do status do plano de dados
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 de 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.
- 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 para o UE.
- 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.
Interação entre GTAF e DPA
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
{
"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.
Envio do status do plano para o cliente padrão
O GTAF continua oferecendo 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. Nesse caso, presumimos que o status do plano é destinado ao cliente mobiledataplan e que o operador pretende enviar uma notificação ao usuário. O corpo da solicitação é o mesmo para o caso de uso por cliente e o caso de uso do cliente padrão.
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. Se o cabeçalho for incluído, as strings legíveis em atualizações enviadas pelo DPA usando a API MDP precisarão usar as configurações fornecidas na solicitação de CPID.