Cómo establecer el CPID

GTAF usa una clave de usuario para identificar a un suscriptor cuando se comunica con el APD. Las aplicaciones que tienen acceso al MSISDN del usuario pueden usarlo como user_key. Por otro lado, las aplicaciones que no tienen acceso al MSISDN, deben establecer un identificador del plan del proveedor (CPID) sin descubrir el MSISDN del usuario. A continuación, describimos el mecanismo que establece un CPID.

Flujo de llamada CPID

Figura 2: Flujo de llamada para establecer el CPID

  1. Una aplicación de Google en la UE usa una API interna de Google para recuperar la URL del extremo CPID de GTAF. El operador se identifica mediante la dirección IP pública del cliente y el MCC+MNC de la tarjeta SIM activa. En el caso de los MVNO, Google usará SPN y GID1 para determinar el MVNO.
  2. El cliente emite una solicitud HTTP GET al extremo CPID. El operador PUEDE admitir el envío de la solicitud a través de HTTPS.
  3. El operador PUEDE usar su función de inspección profunda de paquetes para identificar la solicitud y, luego, insertar el número de teléfono del usuario en la solicitud como un encabezado HTTP.
  4. El extremo CPID recibe la solicitud, construye el CPID y lo muestra al UE con un tiempo de actividad (TTL), que indica por cuánto tiempo el UE puede usar este CPID.

El operador también puede usar direcciones IP en lugar de nombres de dominio en la URL del extremo del CPID si eso es preferible. Las direcciones IP PUEDEN estar en el espacio de direcciones privadas, pero deben ser accesibles para los clientes de Google dentro de la red del operador.

El operador DEBE proporcionar la siguiente información a Google como parte del proceso de integración:

  1. El CPID_URL con el que las aplicaciones se comunicarán para adquirir los CPID. Una CPID_URL es obligatoria, pero el operador puede proporcionar varias URL para aumentar la disponibilidad.
  2. La lista de prefijos de IP que posee el operador y el código de país móvil (MCC) y los códigos de red móvil (MNC) que el operador desea asignar a las CPID_URL proporcionadas Si el operador usa SPN o GID1 para distinguir los MVNO de su red, también debe proporcionar esta información. Google usará esta información para hacer coincidir a los clientes con los extremos CPID correspondientes, como se muestra en el Paso 1 de la Figura 2.

El formato de la solicitud es el siguiente: GET CPID_URL Por motivos heredados, el extremo CPID debería poder admitir una solicitud como la siguiente:

GET CPID_URL?app={app_id}

El extremo CPID puede ignorar el parámetro de URL {app_id} cuando genera el CPID. Sin embargo, DEBE poder manejar una solicitud que contiene el parámetro.

La solicitud al extremo CPID PUEDE incluir el encabezado Accept-Language. Si se incluye el encabezado, las strings legibles en las actualizaciones que envía la APD mediante la API de uso compartido del plan de datos móviles DEBEN usar la configuración proporcionada en la solicitud de CPID.

Cada vez que el cliente emite una solicitud GET CPID_URL, DEBE recibir un nuevo CPID. Si la creación del CPID se realiza correctamente, el extremo CPID DEBE mostrar una respuesta 200 OK. El cuerpo de la respuesta DEBE contener una instancia de CPIDResponse.

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

El CPID que se muestra DEBE ser válido durante ttlSeconds, incluso si un suscriptor solicitó otros CPID después. Google recomienda usar un valor de TTL de 30 días, pero no menos de 14 días, para brindar la mejor experiencia del usuario. GTAF codificará el CPID según RFC2396 en llamadas posteriores a la APD.

Generación del CPID

La forma RECOMENDADA para que el extremo CPID cree un CPID es la siguiente:

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

El extremo CPID concatena el MSISDN, el idioma que envía el cliente en el encabezado Accept-Language y una marca de tiempo de alta resolución, y lo encripta a través de AES con la clave secret. La marca de tiempo DEBE corresponder a la fecha de vencimiento del CPID. El resultado encriptado está codificado en Base64. Además, cuando el CPID se usa en una URL, DEBE codificarse como URL para controlar los caracteres especiales (/+=) que se usan en Base64. En particular, cuando GTAF llama a la DPA o cuando llama a la API de Mobile Data Plan Sharing, el CPID DEBE codificarse como URL.

Según la situación de un operador en particular, puede que no sea trivial implementar el extremo CPID. Un desafío en particular que se ha encontrado con frecuencia es obtener acceso a MSISDN en el extremo CPID. Nos complace compartir las lecciones aprendidas sobre los operadores de integración. Comunícate con nosotros si tienes algún problema.

Almacenamiento CPID

Un CPID generado mediante el mecanismo descrito antes no tiene que almacenarse en una base de datos. La información relevante para manejar llamadas al DPA se puede obtener del CPID.

  1. Cuando la APD recibe una llamada de la GTAF para ofertas o estados de plan, el MSISDN se puede derivar desencriptando el CPID y extrayendo el MSISDN.
  2. La hora de vencimiento del CPID se puede derivar desencriptando el CPID y extrayendo la marca de tiempo de vencimiento.

Requisitos de disponibilidad y capacidad

Si los clientes no pueden recuperar un CPID, no pueden acceder a la información de la API de Mobile Data Plan. Por este motivo, el operador DEBE tomar las medidas necesarias para garantizar la disponibilidad del extremo CPID. Estas medidas incluyen tener varias instancias del extremo CPID y las funciones de DPI, y tener redundancia física, de sitio y de red para ambas funciones, y garantizar que los recursos del sistema y la capacidad sean adecuados. Además, el extremo CPID y la función de DPI que inyecta el encabezado deben tener la capacidad adecuada para manejar la carga de todos los clientes de Google que solicitan CPID. El extremo CPID puede usar valores más grandes en el campo ttlSeconds para reducir la frecuencia que genera los CPID.

Casos de error

Si se produce un error, el extremo CPID DEBE mostrar un error HTTP con un cuerpo de respuesta que DEBE contener una instancia de ErrorResponse. Un buen mensaje de error podría incluir información que pueda ayudar a depurar la causa del error. Por ejemplo, en el caso de un CPID vencido, incluir la generación y el tiempo de vencimiento del CPID nos ayudaría a confirmar que el extremo CPID funciona según lo diseñado.

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

El extremo CPID DEBE mostrar lo siguiente según el caso:

  1. Si se recibe una solicitud de CPID para un usuario que no pertenece a la red del operador (p.ej., un usuario que pertenece a otro operador, pero roaming en la red entregada por este extremo de CPID) o que no optó por compartir información del plan de datos con Google, el extremo de CPID DEBE mostrar el código de estado HTTP 403 con USER_ROAMING, USER_OPT_OUT o INELIGIBLE_FOR_SERVICE como causa.
  2. Si se recibe una solicitud de CPID con un número de teléfono no válido, el extremo de CPID DEBE mostrar HTTP 400 con la causa de error INVALID_NUMBER.
  3. Si la solicitud al extremo de CPID tiene errores de formato, el extremo de CPID DEBE mostrar HTTP 400 con la causa ERROR_CAUSE_UNSPECIFIED.
  4. Para otras causas de error, se acepta cualquier código de error de HTTP compatible. En particular, HTTP 500 es una causa de error adecuada para cualquier falla interna en el extremo CPID.