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.
- 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.
- O cliente emite uma solicitação HTTP GET para o endpoint de CPID. O operador PODE aceitar o envio da solicitação por HTTPS.
- 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.
- 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:
- 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.
- 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 precisará 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, mesmo que um assinante tenha solicitado outros CPIDs depois. O Google recomenda usar um valor de TTL de 30 dias, mas não menos de 14 dias para ter a melhor experiência do usuário. O GTAF vai codificar o CPID por RFC2396 em chamadas subsequentes para a DPA.
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.
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.
Armazenamento de CPID
Um CPID gerado usando o mecanismo descrito acima não precisa ser armazenado em um banco de dados. As informações relevantes para processar chamadas à DPA podem ser derivadas do CPID.
- Quando o DPA recebe uma chamada da GTAF para um status ou ofertas de plano, o MSISDN pode ser derivado descriptografando o CPID e extraindo o MSISDN.
- Para derivar o tempo de expiração do CPID, descriptografe o CPID e extraia o carimbo de data/hora de expiração.
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 de CPID
pode usar valores maiores no campo ttlSeconds para reduzir a frequência com que
gera CPIDs.
Casos de erro
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. Uma boa mensagem de erro inclui informações que podem ajudar a depurar a causa do erro. Por exemplo, no caso de um CPID expirado, incluir a geração e o tempo de expiração do CPID nos ajudaria a confirmar se o endpoint do CPID está funcionando conforme o esperado.
{
"errorMessage": "<error message>",
"cause": "USER_ROAMING"
}
O endpoint CPID precisa retornar o seguinte, dependendo do cenário:
- Se uma solicitação de CPID for recebida para um usuário que não pertence à rede do operador (por exemplo, um usuário de outro operador 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 precisará retornar o código de status HTTP 403 com USER_ROAMING, USER_OPT_OUT ou INELIGIBLE_FOR_SERVICE como causa.
- Se uma solicitação de CPID for recebida com um número de telefone inválido, o endpoint de CPID precisa retornar HTTP 400 com a causa do erro INVALID_NUMBER.
- Se a solicitação ao endpoint de CPID estiver malformada de alguma outra forma, o endpoint de CPID PRECISA retornar HTTP 400 com ERROR_CAUSE_UNSPECIFIED como causa.
- Para outras causas de erro, qualquer código de erro HTTP compatível é aceitável. Em particular, HTTP 500 é uma causa de erro adequada para qualquer falha interna no endpoint CPID.