Cómo establecer el CPID

La GTAF usa la clave del usuario para identificar a un suscriptor cuando se comunica con el DPA. 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 de plan de operador (CPID) sin descubrir el MSISDN del usuario. A continuación, describimos el mecanismo que establece un CPID.

Flujo de llamadas de CPID

Figura 2: Flujo de llamadas 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 de CPID de GTAF. El operador se identifica con 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á el SPN y el GID1 para determinar el MVNO.
2. El cliente emite una solicitud HTTP GET al extremo del CPID. El operador PUEDE admitir el envío de la solicitud a través de HTTPS.
3. El operador PUEDE emplear 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 de CPID recibe la solicitud, construye el CPID y lo devuelve al UE con un tiempo de actividad (TTL) que indica durante 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 lo prefiere. Las direcciones IP PUEDEN estar en un espacio de direcciones privadas, pero los clientes de Google deben poder acceder a ellas dentro de la red del operador.

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

1. Es la CPID_URL a la que se conectarán las aplicaciones para adquirir CPIDs. Se requiere una CPID_URL, pero el operador puede proporcionar varias URLs para aumentar la disponibilidad.
2. Es la lista de prefijos de IP que posee el operador y los códigos de país móvil (MCC) y los códigos de red móvil (MNC) que el operador desea que se asignen a las CPID_URLs proporcionadas. Si el operador usa el SPN o el GID1 para distinguir a los MVNO en su red, también DEBE proporcionar esta información. Google usará esta información para correlacionar los clientes con los extremos de 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 del CPID debe poder admitir una solicitud como la siguiente:

GET CPID_URL?app={app_id}

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

La solicitud al extremo de CPID PUEDE incluir el encabezado Accept-Language. Si se incluye el encabezado, las cadenas legibles para humanos en las actualizaciones que el DPA envía con la API de Mobile Data Plan Sharing 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 CPID nuevo. Si la creación del CPID se realiza correctamente, el endpoint del CPID DEBE devolver una respuesta 200 OK. El cuerpo de la respuesta DEBE contener una instancia de CPIDResponse.

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

El CPID que se devuelve DEBE ser válido durante ttlSeconds segundos, 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 al usuario. GTAF codificará el CPID por RFC2396 en las llamadas posteriores al DPA.

Generación de CPID

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

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

El extremo de 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 se codifica 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 al DPA o cuando el DPA llama a la API de Mobile Data Plan Sharing, el CPID DEBE estar codificado como URL.

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

Almacenamiento de CPID

No es necesario almacenar en una base de datos un CPID generado con el mecanismo descrito anteriormente. La información pertinente para atender las llamadas a la DPA se puede obtener del CPID.

1. Cuando el DPA recibe una llamada del GTAF para consultar el estado de un plan o las ofertas, el MSISDN se puede derivar desencriptando el CPID y extrayendo el MSISDN.
2. Para obtener la fecha y hora de vencimiento del CPID, se puede descifrar el CPID y, luego, extraer la marca de tiempo de vencimiento.

Requisitos de disponibilidad y capacidad

Si los clientes no pueden recuperar un CPID, no podrán acceder a ninguna 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 del CPID. Estas medidas incluyen tener varias instancias de las funciones de CPID y DPI, y tener redundancia física, de sitio y de red para ambas funciones, además de garantizar que los recursos y la capacidad del sistema sean adecuados. Además, el extremo de CPID y la función de DPI que inserta el encabezado deben tener la capacidad adecuada para controlar la carga de todos los clientes de Google que solicitan CPID. El extremo del CPID puede usar valores más grandes en el campo ttlSeconds para reducir la frecuencia con la que genera CPIDs.

Casos de error

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

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

Según la situación, el extremo de CPID DEBE devolver lo siguiente:

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 que está en itinerancia en la red que proporciona este extremo de CPID) o que no habilitó el uso compartido de la información del plan de datos con Google, el extremo de CPID DEBE devolver 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 devolver el error HTTP 400 con la causa INVALID_NUMBER.
3. Si la solicitud al extremo de CPID está mal formada de alguna otra manera, el extremo de CPID DEBE devolver HTTP 400 con ERROR_CAUSE_UNSPECIFIED como causa.
4. Para otras causas de error, se acepta cualquier código de error HTTP compatible. En particular, el error HTTP 500 es una causa de error adecuada para cualquier falla interna en el extremo de CPID.