Estabelecer CPID

O GTAF usa a chave do usuário para identificar um assinante ao se comunicar com a DPA. Aplicativos que têm acesso ao MSISDN do usuário podem usá-lo como user_key. Por outro lado, os aplicativos que não têm acesso ao MSISDN precisam estabelecer um identificador do plano de operadora (CPID, na sigla em inglês) sem descobrir o MSISDN do usuário. Descrevemos a seguir 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 na UE usa uma API interna do Google para recuperar o URL do endpoint do CPID do GTAF. O operador é identificado usando o endereço IP público do cliente e o MCC+MNC do chip ativo. No caso de MVNOs, o Google usará o SPN e o GID1 para determinar o MVNO.
  2. O cliente emite uma solicitação HTTP GET para o endpoint CPID. O operador pode oferecer suporte ao envio da solicitação por HTTPS.
  3. O operador pode usar a função de inspeção de pacotes profundos para identificar a solicitação e injetar o número de telefone do usuário na solicitação como um cabeçalho HTTP.
  4. O endpoint do CPID recebe a solicitação, cria o CPID e retorna o CPID à UE com um time to live (TTL) indicando por quanto tempo a UE pode usar esse CPID.

Se preferir, o operador PODE usar endereços IP em vez de nomes de domínios no URL do endpoint do CPID. Os endereços IP PODEM estar em um espaço de endereço particular, mas precisam ser acessados pelos clientes do Google dentro da rede do operador.

O operador SHALL fornecerá as seguintes informações ao Google como parte do processo de integração:

  1. O CPID_URL com que os aplicativos entrarão em contato para adquirir CPIDs. Um CPID_URL é obrigatório, mas o operador pode fornecer vários URLs para aumentar a disponibilidade.
  2. A lista de prefixos de IP que o operador tem e o código de país para dispositivos móveis (MCC) e códigos de rede móvel (MNC, na sigla em inglês) que o operador quer mapear para os CPID_URLs informados. Se o operador usar SPN ou GID1 para distinguir MVNOs na rede, o operador também terá que fornecer essas informações. O Google usará essas informações para fazer a correspondência dos clientes com os endpoints do CPID correspondentes, conforme mostrado na Etapa 1 da Figura 2.

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

GET CPID_URL?app={app_id}

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

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

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 PRECISA retornar uma resposta de 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 para ttlSeconds segundos, mesmo que um assinante solicite outros CPIDs posteriormente. O Google recomenda o uso de um valor de TTL de 30 dias, mas não menos do que 14 dias para uma melhor experiência do usuário. O GTAF codificará o CPID de acordo com o RFC2396 nas chamadas subsequentes para a DPA.

Geração de CPID

A forma RECOMENDADA para que o endpoint do CPID crie um CPID é:

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

O endpoint CPID concatena o MSISDN, a linguagem enviada pelo cliente no cabeçalho Accept-Language, um carimbo de data/hora de alta resolução e o criptografa pelo AES usando secret. O carimbo de data/hora DEVE corresponder ao horário em que o CPID expira. A saída criptografada é codificada em Base64. Além disso, quando o CPID é usado em um URL, ele PRECISA estar codificado para processar caracteres especiais (/+=) usados em Base64. Em especial, quando a GTAF chama a DPA ou quando a DPA chama a API Mobile Data Plan Sharing, o CPID PRECISA ser codificado para URL.

Dependendo da situação de determinado operador, pode ser difícil implementar o endpoint do CPID. Um desafio específico que foi encontrado com frequência é receber o MSISDN no endpoint do CPID. Temos o prazer de compartilhar as lições aprendidas com os operadores de integração. Entre em contato conosco se tiver problemas.

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 para a DPA podem ser derivadas do CPID.

  1. Quando a DPA recebe uma chamada do GTAF para informar um status de plano ou ofertas, o MSISDN pode ser derivado com a descriptografia do CPID e da extração do MSISDN.
  2. O tempo de expiração do CPID pode ser derivado descriptografando o CPID e extraindo o carimbo de data/hora de expiração.

Requisitos de disponibilidade e capacidade

Se os clientes não conseguirem recuperar um CPID, eles não poderão acessar nenhuma informação da API do plano de dados para dispositivos móveis. Por esse motivo, o operador SHALL tomará as medidas necessárias para garantir a disponibilidade do endpoint do CPID. Essas medidas incluem ter várias instâncias do endpoint CPID e funções DPI e 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 do CPID e a função 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 do CPID pode usar valores maiores no campo do ttlSeconds para reduzir a frequência com que ele gera CPIDs.

Casos de erro

Se ocorrer um erro, o endpoint do CPID PRECISA retornar um erro HTTP com um corpo de resposta que PRECISA conter uma instância de ErrorResponse. Uma boa mensagem de erro incluiria informações que podem ajudar a depurar a causa do erro. Por exemplo, no caso de um CPID expirado, incluindo a geração e o prazo de validade do CPID, podemos nos ajudar a confirmar se o endpoint do CPID está funcionando conforme projetado.

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

O endpoint do CPID PRECISA retornar o seguinte, dependendo do cenário:

  1. Se uma solicitação de CPID for recebida para um usuário que não pertence à rede do operador (por exemplo, um usuário que pertence a outro operador, mas está em roaming na rede veiculada por este endpoint do CPID) ou que não optou por compartilhar informações do plano de dados com o Google, o endpoint do CPID PRECISA retornar o código de status HTTP 403 com USER_ROAMING, USER_OPT_OUT ou INELIGIBLE_FOR_SERVICE como o INELIGIBLE_FOR_SERVICE
  2. 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 de erro INVALID_NUMBER.
  3. Se a solicitação para o endpoint do CPID for corrompida de qualquer outra forma, o endpoint do CPID PRECISA retornar HTTP 400 com ERROR_CAUSE_UNSPECIFIED como a causa.
  4. Para outras causas de erro, qualquer código de erro HTTP compatível é aceitável. Especificamente, o HTTP 500 é uma causa de erro adequada para qualquer falha interna no endpoint do CPID.