Como começar a usar o compartilhamento de plano de dados móveis

Terminologia

• GTAF: função de aplicativo de trânsito do Google. Um serviço do Google que implementa a API Data Plan Sharing e interage com DPAs em nome de aplicativos do Google. Os aplicativos do Google podem consultar o GTAF para informações sobre o plano de dados do usuário. Como alternativa, se os aplicativos do Google se registrarem no GTAF, ele poderá enviar atualizações sobre o plano de dados do usuário.
• MSISDN: número de diretório internacional de assinante de estação móvel, um número que identifica exclusivamente uma assinatura em uma rede móvel. Mais conhecido como número de telefone.
• Endpoint CPID: um serviço implementado por operadoras de rede móvel que gera um identificador de plano da operadora (CPID, na sigla em inglês) que pode ser usado para pesquisar as informações do plano de dados do usuário. O CPID permite que um aplicativo consulte detalhes do plano de dados de um usuário sem acessar o MSISDN dele. Descrevemos o procedimento para gerar CPIDs abaixo.
• Chave do usuário: a chave do usuário é uma string que pode ser usada para identificar o plano de dados de um usuário. Pode ser o CPID ou o MSISDN para aplicativos que têm acesso ao MSISDN.
• DPA: Data Plan Agent, um serviço implementado por operadoras de rede móvel que compartilha informações do plano de dados do usuário com o GTAF. O DPA pode compartilhar informações com o GTAF usando uma combinação de envio de dados com a API Google Mobile Data Plan Sharing e implementação da API Data Plan Agent. O DPA também pode atuar como o endpoint de CPID.
• UE: equipamento do usuário, dispositivo usado pelo usuário.

Linguagem dos requisitos

As palavras-chave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" nestes guias devem ser interpretadas conforme descrito na RFC 2119.

Compartilhamento de plano de dados móveis

De modo geral, o compartilhamento de plano de dados móveis tem três partes:

1. Mecanismo para estabelecer e atualizar um identificador de plano da operadora (CPID, na sigla em inglês), que pode ser usado como uma chave de usuário. Os aplicativos que têm acesso ao MSISDN podem usá-lo como uma chave de usuário.
2. Uma API de compartilhamento de plano de dados móveis do Google que permite ao DPA enviar informações sobre o plano de dados de um usuário ao Google. Por exemplo, se a DPA quiser notificar o usuário sobre uma oferta, ela pode notificar o GTAF, que por sua vez notifica o usuário.
3. Uma API de agente de plano de dados implementada pela DPA que permite que o GTAF consulte a DPA para informações sobre o plano de dados do usuário. Por exemplo, se um aplicativo quiser mostrar o saldo atual do plano de dados ao usuário, ele poderá consultar o GTAF, que por sua vez consulta o DPA.

O restante desta página apresenta a terminologia do plano de dados e detalha como estabelecer um CPID. A seguir, confira a API Google Mobile Data Plan Sharing e a especificação da API Data Plan Agent.

Terminologia do plano de dados

O esquema de um planStatus definido na API PRECISA ser capaz de representar planos de dados oferecidos pelas operadoras aos usuários. A API permite definir planos de dados que cobram dos usuários uma taxa diferente para todo o tráfego de um determinado conjunto de URLs (por exemplo, todo o tráfego para *.acmefake.com é cobrado a uma taxa diferente). A API também é compatível com planos de dados que oferecem taxas diferentes para determinados tipos de ações em um app. Chamamos esses planos de dados de subaplicativos. Um exemplo de plano de dados de subaplicativo seria oferecer navegação de vídeo sem custo financeiro (ou seja, taxa zero), enquanto assistir vídeos no aplicativo deduz dados do saldo de dados do assinante. O app de vídeo PRECISA conseguir aprender essas informações ao consultar dados do plano.

Aqui, apresentamos alguns termos relacionados a planos de dados. A Figura 1 mostra exemplos de planos de dados representativos dos conceitos que queremos capturar.

Plano de dados:o pacote de serviços móveis de nível superior que um assinante compra. Pode ser algo simples como "10 GB de dados móveis por 30 dias" ou uma coleção de componentes, também conhecidos como módulos. Um plano de dados tem:

• Nome do plano de dados, como "ACME Red".
• Identificador do plano de dados, usado para se referir ao plano, por exemplo, durante compras.
• Tempo de expiração, quando o plano de dados expira.
• Categoria do plano, se ele é pré-pago ou pós-pago.

Módulo de plano:um componente de um plano de dados. Especificamente, um módulo de plano tem:

• Nome do módulo, como "Noites de vídeo sem custo financeiro".
• Taxa máxima, largura de banda oferecida ao usuário por este módulo.
• Janelas de tempo flexíveis, períodos em que um desconto pode ser oferecido ao usuário.

• Categoria de tráfego do módulo de planejamento (PMTC), uma descrição do tráfego de dados a que um módulo se aplica. O PMTC pode ser tão geral quanto *todo o tráfego da Internet *ou tão específico quanto o tráfego gerado/consumido por um ou mais aplicativos, sites ou até mesmo jornadas do usuário em um único aplicativo. Exemplos desse tipo são "música ilimitada", "pacote de dados de vídeo (VDP) de 100 MB", "dados de jogos ilimitados" e "navegação de vídeo ilimitada". Para facilitar a definição de PMTCs, definimos as seguintes PMTCs: GENERIC, VIDEO, VIDEO_BROWSING, VIDEO_OFFLINE¹, MUSIC, GAMING, SOCIAL, MESSAGING e PMTC_UNSPECIFIED..

• Limite de tempo ou volume de dados: depois de ativado, o módulo do plano expira quando o limite de tempo ou volume de dados é atingido (no caso de planos baseados em tempo, por exemplo, 600 minutos de acesso à Internet nos próximos sete dias. Na Figura 1 abaixo, um assinante pode comprar um módulo de plano, como parte do "ACME Blue", que oferece 1 GB de tráfego geral do usuário a ser usado em uma semana após a ativação, antes de expirar.

Figura 1. Exemplos de planos de dados.

Como estabelecer o CPID

O GTAF usa a chave de usuário para identificar um assinante ao se comunicar com o DPA. Os aplicativos que têm acesso ao MSISDN do usuário podem usá-lo como uma user_key. Por outro lado, os aplicativos que não têm acesso ao MSISDN precisam estabelecer um identificador de plano da operadora (CPID, na sigla em inglês) sem descobrir o MSISDN do usuário. A seguir, descrevemos o mecanismo que estabelece um CPID.

Fluxo de chamadas do CPID

Figura 2: fluxo de chamadas para estabelecer o CPID.

1. Um aplicativo do Google no UE usa uma API interna do Google para recuperar o URL do endpoint CPID do GTAF. O operador é identificado usando o endereço IP público do cliente e o MCC+MNC do chip ativo. No caso das MVNOs, o Google usa o SPN e o GID1 para determinar a MVNO.
2. O cliente emite uma solicitação HTTP GET para o endpoint de CPID. O operador PODE aceitar o envio da solicitação por HTTPS.
3. O operador PODE usar a função de inspeção profunda de pacotes para identificar a solicitação e injetar o número de telefone do usuário nela como um cabeçalho HTTP.
4. O endpoint CPID recebe a solicitação, cria o CPID e o retorna ao UE com um tempo de vida (TTL) indicando por quanto tempo o UE pode usar esse CPID.

O operador também PODE usar endereços IP em vez de nomes de domínio no URL do endpoint CPID, se preferir. Os endereços IP PODEM estar no espaço de endereços privados, mas precisam ser acessíveis pelos clientes do Google na rede dos operadores.

O operador DEVE fornecer as seguintes informações ao Google como parte do processo de integração: 1. O CPID_URL que os aplicativos vão contatar para adquirir CPIDs. Um CPID_URL é obrigatório, mas o operador pode fornecer vários URLs para aumentar a disponibilidade. 1. A lista de prefixos de IP de propriedade da operadora e o código de país para dispositivos móveis (MCC) e os códigos de rede móvel (MNC) que a operadora quer mapear para os CPID_URLs fornecidos. Se o operador usar SPN ou GID1 para distinguir MVNOs na rede, ele TAMBÉM vai fornecer essas informações. O Google vai usar essas informações para corresponder clientes aos endpoints de CPID correspondentes, conforme mostrado na Etapa 1 da Figura 2.

O formato da solicitação é: GET CPID_URL Por motivos legados, o endpoint de CPID precisa ser compatível com uma solicitação como a seguinte:

GET CPID_URL?app={app_id}

O endpoint de CPID pode ignorar o parâmetro de URL {app_id} ao gerar o CPID. No entanto, ele PRECISA ser capaz de processar uma solicitação que contenha o parâmetro.

A solicitação ao endpoint CPID PODE incluir o cabeçalho Accept-Language. Se o cabeçalho for incluído, as strings legíveis por humanos nas atualizações enviadas pela DPA usando a API Mobile Data Plan Sharing precisarão usar as configurações fornecidas na solicitação de CPID.

Cada vez que o cliente emite uma solicitação GET CPID_URL, ele PRECISA receber um novo CPID. Se a criação do CPID for bem-sucedida, o endpoint do CPID vai retornar uma resposta 200 OK. O corpo da resposta PRECISA conter uma instância de CPIDResponse.

{
    "cpid": "<CPID_string>",
    "ttlSeconds": 2592000
}

O CPID retornado PRECISA ser válido por ttlSeconds segundos. O GTAF vai codificar o CPID por RFC2396 em chamadas subsequentes para a DPA.

Se ocorrer um erro, o endpoint CPID vai retornar um erro HTTP com um corpo de resposta que precisa conter uma instância de ErrorResponse. A lista de possíveis valores de causa e códigos de erro HTTP está disponível aqui.

{
    "errorMessage": "<error message>",
    "cause": "INVALID_NUMBER"
}

Em particular, se uma solicitação de CPID for recebida para um usuário que não pertence à rede do operador (por exemplo, um usuário pertencente a outro operador, mas em roaming na rede atendida por esse endpoint de CPID) ou que não ativou o compartilhamento de informações do plano de dados com o Google, o endpoint de CPID DEVE retornar o código de status HTTP 403.

Geração de CPID

A maneira RECOMENDADA para o endpoint CPID criar um CPID é:

CPID_string = Base64(AES(MSISDN + TimeStamp + language, secret))

O endpoint CPID concatena o MSISDN, o idioma enviado pelo cliente no cabeçalho Accept-Language e um carimbo de data/hora de alta resolução, criptografando tudo com AES usando a chave secret. O carimbo de data/hora PRECISA corresponder ao momento em que o CPID expira. A saída criptografada é codificada em Base64. Além disso, quando o CPID é usado em um URL, ele precisa ser codificado para processar caracteres especiais (/+=) usados em Base64. Principalmente quando o GTAF chama a DPA ou quando a DPA chama a API Mobile Data Plan Sharing, o CPID PRECISA ser codificado por URL. Uma vantagem de gerar CPID usando essa abordagem é que o endpoint de DPA e CPID não precisa ter um banco de dados de CPIDs e MSISDNs válidos.

Dependendo da situação de um operador específico, pode ser difícil implementar o endpoint CPID. Um desafio específico que tem sido encontrado com frequência é conseguir acesso ao MSISDN no endpoint CPID. Temos o prazer de compartilhar as lições aprendidas na integração de operadores. Entre em contato com nossa equipe se tiver dificuldades.

Requisitos de segurança

O operador DEVE tomar todas as precauções necessárias para proteger as informações particulares dos assinantes. Especificamente, para minimizar a exposição dos números de telefone dos assinantes, o endpoint CPID DEVE estar dentro do perímetro de segurança. Além disso, nos casos em que o operador usa DPI, ele PRECISA criptografar o MSISDN antes de injetá-lo na solicitação HTTP. Se o endpoint do CPID não for seu perímetro de segurança (por exemplo, quando o endpoint do CPID é implantado em uma nuvem pública), o operador NÃO DEVE transmitir o MSISDN pela Internet pública sem criptografia. O operador pode estabelecer uma VPN entre o DPI e o endpoint CPID (consulte a Figura 1) ou criptografar o MSISDN antes de injetá-lo no cabeçalho. A última abordagem pressupõe que o endpoint de CPID pode descriptografar o cabeçalho injetado para recuperar o MSISDN antes de gerar o CPID. Além disso, o operador DEVE proteger a chave secreta usada para gerar o CPID e fazer a rotação dela de acordo com as políticas de segurança do operador.

Requisitos de disponibilidade e capacidade

Se os clientes não puderem recuperar um CPID, não terão acesso a nenhuma informação da API Mobile Data Plan. Por isso, o operador PRECISA tomar as medidas necessárias para garantir a disponibilidade do endpoint de CPID. Essas medidas incluem ter várias instâncias do endpoint CPID e funções de DPI, além de ter redundância física, de site e de rede para ambas as funções, e garantir que os recursos e a capacidade do sistema sejam adequados. Além disso, o endpoint de CPID e a função de DPI que injeta o cabeçalho precisam ter capacidade adequada para processar a carga de todos os clientes do Google que solicitam CPIDs. O endpoint CPID pode usar valores maiores no campo "ttlSeconds" para reduzir a frequência com que gera CPIDs. O Google recomenda usar um valor de TTL de 30 dias.

Observações

---

1. O PMTC VIDEO_OFFLINE significa que esse plano é bom apenas para uso off-line (por exemplo, uma qualidade de experiência de streaming muito ruim). Ele é independente da janela do FlexTime. ↩