Motivação
Como mencionado na visão geral, dependendo dos casos de uso que o operador quer oferecer suporte, o DPA precisa implementar uma combinação da API Google Mobile Data Plan Sharing e da API Data Plan Agent. Este documento descreve a API Data Plan Agent, que o Google usa para identificar os planos de dados móveis do usuário, recuperar informações sobre eles e comprar planos de dados.
Autenticação
Antes que o GTAF possa fazer chamadas, o DPA precisa autenticar o GTAF. Como parte do processo de integração do operador, vamos verificar a validade do certificado SSL da DPA. Atualmente, EXIGIMOS o uso do OAuth2 para autenticação mútua. Consulte Autenticação do agente do plano de dados para saber como o GTAF se autentica com o DPA.
Internacionalização
As solicitações da GTAF à DPA incluem um cabeçalho "Accept-Language" que indica o idioma em que as strings legíveis (por exemplo, descrições de planos) devem estar. Além disso, as respostas da DPA (PlanStatus, PlanOffers) incluem um campo obrigatório languageCode cujo valor é o código de idioma BCP-47 (por exemplo, "en-US") da resposta.
Se a DPA não for compatível com o idioma solicitado pelo usuário, ela poderá usar um idioma padrão e o campo "languageCode" para indicar a escolha.
Descrição da API
O GTAF usa a chave do usuário, que identifica um assinante do operador, ao consultar a DPA do operador. Quando o GTAF consulta a DPA em nome de aplicativos que têm acesso ao MSISDN, o GTAF PODE usar o MSISDN. Em um nível alto, a API Data Plan Agent proposta inclui os seguintes componentes:
- Mecanismo para consultar o status do plano de dados do usuário.
- Mecanismo para consultar a DPA sobre ofertas de plano de dados para o usuário.
- Mecanismo para fazer mudanças no plano de dados do usuário (por exemplo, comprar um novo plano).
- Mecanismo para compartilhar os CPIDs que podem ser usados para enviar notificações aos usuários.
- Mecanismo para compartilhar as escolhas do usuário sobre se inscrever ou não no nosso serviço.
O restante deste documento detalha cada um desses componentes da API. A menos que seja explicitamente indicado, todas as comunicações precisam acontecer por HTTPS (com um certificado SSL de DPA válido). Dependendo dos recursos reais compatíveis, um operador PODE implementar todos ou um subconjunto desses componentes de API.
Interação entre GTAF e DPA
Figura 4. Fluxo de chamadas para solicitar e receber informações do plano de dados do usuário.
A Figura 4 ilustra o fluxo de chamadas associado a um cliente que consulta o status do plano de dados do usuário e outras informações relacionadas. Esse fluxo de chamadas é compartilhado para chamadas de API acionadas pelo cliente no UE.
- O cliente solicita o status do plano de dados e/ou outras informações chamando uma API privada do Google. O cliente inclui a chave de usuário na solicitação para o GTAF.
- O GTAF usa a chave do usuário e um identificador do cliente para consultar a DPA do operador. Os identificadores de cliente aceitos são mobiledataplan e youtube. Quando o DPA recebe uma chamada com um desses identificadores de cliente, ele PRECISA responder com informações do plano que podem ser usadas pelo cliente.
- O GTAF retorna as informações solicitadas ao cliente, e as informações do plano são armazenadas em cache pelo GTAF até o horário de expiração especificado pela DPA.
As etapas 1 e 3 na Figura 4 são APIs privadas do Google e, portanto, não são descritas com mais detalhes. A etapa 2 é uma API pública descrita abaixo. O DPA PRECISA respeitar o cabeçalho HTTP Cache-Control: no-cache ao veicular essas chamadas de API do GTAF.
Como consultar o status do plano de dados
O GTAF emite a seguinte solicitação HTTP para receber o status do plano:
GET DPA_URL/{userKey}/planStatus?key_type={CPID,MSISDN}&client_id=CLIENT_ID
O cliente em nome de quem a GTAF está entrando em contato com a DPA é identificado usando CLIENT_ID. Dependendo do contrato entre o cliente e o operador do Google, a DPA pode personalizar a resposta à GTAF. Em caso de sucesso, a DPA DEVE retornar HTTP 200 OK com um corpo de resposta que representa um PlanStatus. Consulte Casos de erro para ver a resposta esperada em caso de erros.
{
"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"
}]
}],
"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"
"planInfoPerClient": {
"youtube": {
"rateLimitedStreaming": {
"maxMediaRateKbps": 256
}
}
}
}
Para planos pós-pagos, expirationTime PRECISA ser a data de recorrência do plano (ou seja, quando o saldo de dados é atualizado/recarregado).
Cada módulo de plano pode conter várias categorias de tráfego de módulo de plano (PMTCs)) para modelar o caso em que um módulo de plano é compartilhado entre vários apps (por exemplo, 500 MB para jogos e músicas. Os seguintes PMTCs são predefinidos: GENERIC, VIDEO,
VIDEO_BROWSING, VIDEO_OFFLINE, MUSIC, GAMING, SOCIAL and MESSAGING.. Espera-se que os operadores entrem em contato com equipes individuais do Google para concordar com o conjunto de categorias de tráfego e suas semânticas relevantes para diferentes aplicativos do Google.
Consultar ofertas de planos
O GTAF emite a seguinte solicitação HTTP para receber ofertas de planos da operadora:
GET DPA_URL/{userKey}/planOffer?key_type={CPID,MSISDN}&client_id=CLIENT_ID&context={purchaseContext}
O cliente em nome de quem a GTAF está entrando em contato com a DPA é identificado usando CLIENT_ID. Dependendo do contrato entre o cliente e o operador do Google, a DPA pode personalizar a resposta à GTAF. O parâmetro de contexto opcional fornece o contexto do aplicativo em que a solicitação é feita. Normalmente, essa é uma string que o aplicativo transmite ao operador pelo GTAF.
Em caso de sucesso, a DPA PRECISA retornar HTTP 200 OK com um corpo de resposta que representa um PlanOffer. Consulte Casos de erro para ver a resposta esperada em caso de erros.
{
"offers": [
{
"planName": "ACME Red", // req.
"planId": "turbulent1", // req.
"planDescription": "Unlimited Videos for 30 days.", // req.
"promoMessage": "Binge watch videos.",
"languageCode": "en_US", // req.
"overusagePolicy": "BLOCKED",
"cost": { // req.
"currencyCode": "INR",
"units": "300",
"nanos": 0
},
"duration": "2592000s",
"offerContext": "YouTube",
"trafficCategories": ["VIDEO"],
"quotaBytes": "9223372036850",
"filterTags": ["repurchase", "all"]
}
],
"filters" : [
{
"tag": "repurchase",
"displayText": "REPURCHASE PLANS"
},
{
"tag": "all",
"displayText": "ALL PLANS"
}
]
"expireTime": "2019-03-04T00:06:07Z" // req.
}
A ordem dos planos de dados na matriz offers PODE determinar a ordem em que os planos de dados são apresentados aos usuários. Além disso, se o aplicativo puder apresentar apenas x planos devido a limitações de interface ou outras, e a resposta contiver y > x planos, apenas os primeiros x planos SERÃO apresentados. O GTAF compartilha apenas até 50 planos se o aplicativo que consulta ofertas for o módulo de plano de dados móveis, que faz parte dos Serviços do Google Play. Isso garante uma boa experiência do usuário para
usuários do Google Play Services.
As ofertas de upselling têm filterTags como um parâmetro opcional, que é uma matriz de
tags anexadas a cada plano. Todas essas filterTags precisam corresponder à tag, que é
um objeto dentro de "Filter". Filter é um objeto de primeiro nível que contém
tuple<tag, displaytext="">. Filter é uma lista consolidada de filtros que serão
renderizados na interface. O usuário pode filtrar clicando em DisplayText. A tag
correspondente ao displayText é usada para filtrar as ofertas.</tag,>
O operador PRECISA ter um mecanismo para atender a um pedido de compra de qualquer oferta feita ao usuário. O mecanismo pelo qual o usuário vai pagar por qualquer compra pode ser comunicado com o GTAF usando a opção formOfPayment na resposta.
Compra de dados
A API de plano de compra define como o GTAF pode comprar planos pela DPA. A GTAF inicia a transação para comprar um plano de dados para a DPA. A solicitação DEVE incluir um identificador de transação exclusivo (transactionId) para rastrear solicitações e evitar a execução de transações duplicadas. O DPA PRECISA responder com uma resposta de sucesso/falha.
Solicitação de transação
Quando recebe uma solicitação de um cliente, o GTAF emite uma solicitação POST para a DPA. O URL da solicitação é:
POST DPA_URL/{userKey}/purchasePlan?key_type={CPID,MSISDN}&client_id=CLIENT_ID
em que userKey é um CPID ou MSISDN. O corpo da solicitação é uma instância de TransactionRequest, que inclui os seguintes campos:
{
"planId": string, // Id of plan to be purchased. Copied from
// offers.planId field returned from a
// Upsell Offer request,
// if available. (req.).
"transactionId": string, // Unique request identifier (req.)
"offerContext": string, // Copied from from the
// offers.offerContext, if available.
// (opt.)
"callbackUrl": string // URL that the DPA can call back with response once
// it has handled the request.
}
Resposta da transação
O DPA GERA uma resposta 200-OK apenas para uma transação executada ou enfileirada com sucesso. Consulte Casos de erro para ver a resposta esperada em caso de erros. No caso de uma transação em fila, o DPA só vai preencher o status da transação e deixar outros campos na resposta em branco. O DPA PRECISA retornar uma resposta à GTAF depois que uma transação enfileirada for processada. O corpo da resposta é uma instância de TransactionResponse, que inclui os seguintes detalhes:
{
"transactionStatus": "SUCCESS",
"purchase": {
"planId": string, // copied from request. (req.)
"transactionId": string, // copied from request. (req.)
"transactionMessage": string, // status message. (opt.)
"confirmationCode": string, // DPA-generated confirmation code
// for successful transaction. (opt.)
"planActivationTime" : string, // Time when plan will be activated,
// in timestamp format. (opt.)
},
// walletInfo is populated with the balance left in the user's account.
"walletBalance": {
"currencyCode": string, // 3-letter currency code defined in ISO 4217.
"units": string, // Whole units of the currency amount.
"nanos": number // Number of nano units of the amount.
}
}
Se o planActivationTime estiver ausente, o GTAF vai presumir que o plano foi ativado.
Registrar CPID
Quando um cliente que aceita notificações recebe um novo CPID do endpoint CPID, ele registra o CPID com o GTAF se os termos do cliente permitirem que o GTAF faça isso. Se o cliente registrar o CPID com sucesso no GTAF, o GTAF vai registrar o CPID com o DPA usando a seguinte chamada de API:
POST DPA_URL/{userKey}/registerCpid?key_type={CPID,MSISDN}&client_id=CLIENT_ID
em que userKey é o CPID e o único CLIENT_ID aceito é
mobiledataplan. O corpo da solicitação é uma instância de
RegisterCpidRequest e contém o
horário após o qual o CPID não pode ser usado para enviar notificações e tem esta aparência:
{"staleTime": "2017-01-29T01:00:03.14159Z"}
Essa API é relevante apenas para operadores que querem oferecer suporte ao módulo Plano de dados móveis no Google Play Services. Para enviar notificações de forma confiável ao usuário, o DPA PODE armazenar o CPID registrado mais recente para cada usuário. Consulte Escolher um CPID para saber como usar o CPID registrado no envio de notificações.
A DPA vai gerar uma resposta 200-OK se associar o CPID ao usuário e armazená-lo de forma permanente. Consulte Casos de erro para ver a resposta esperada em caso de erros.
Consentimento
O GTAF PODE emitir a seguinte solicitação para transmitir a preferência de consentimento do usuário à operadora.
POST DPA_URL/{userKey}/consent?key_type={CPID,MSISDN}&client_id=CLIENT_ID
em que userKey é um CPID ou MSISDN. O corpo da solicitação é uma
instância de
SetConsentStatusRequest. Se a solicitação for bem-sucedida, o corpo da resposta estará vazio.
Todas as chamadas do GTAF para a DPA seguem os Termos de Serviço do cliente do Google que faz a chamada. Dependendo dos aplicativos que a DPA quer oferecer suporte, cabe ao operador decidir se a DPA implementa essa API. Se o DPA optar por implementar a API Consent, ele DEVERÁ armazenar o status de consentimento mais recente de cada usuário. Consulte Escolher CPID para orientações sobre como usar as informações de status de consentimento.
Em caso de sucesso, o DPA PRECISA retornar HTTP 200 OK com um corpo de resposta vazio. Consulte Casos de erro para ver a resposta esperada em caso de erros.