Établir le CPID

GTAF utilise une clé utilisateur pour identifier un abonné lorsqu'il communique avec le DPA. Les applications qui ont accès au MSISDN de l'utilisateur peuvent l'utiliser comme user_key. En revanche, les applications qui n'ont pas accès au MSISDN doivent établir un identifiant de forfait mobile (CPID) sans découvrir le MSISDN de l'utilisateur. Nous décrivons ci-dessous le mécanisme qui établit un CPID.

Processus d'appel CPID

Figure 2 : Flux d'appel pour établir le CPID.

  1. Dans l'UE, une application Google utilise une API interne à Google pour récupérer l'URL du point de terminaison CPID à partir de GTAF. L'opérateur est identifié à l'aide de l'adresse IP publique du client et du code MCC+MNC de la carte SIM active. Dans le cas des MVNO, Google utilisera le SPN et le GID1 pour déterminer le MVNO.
  2. Le client émet une requête HTTP GET au point de terminaison CPID. L'opérateur PEUT accepter l'envoi de la requête via HTTPS.
  3. L'opérateur PEUT utiliser sa fonction d'inspection approfondie des paquets pour identifier la requête et injecter le numéro de téléphone de l'utilisateur dans la requête en tant qu'en-tête HTTP.
  4. Le point de terminaison CPID reçoit la requête, construit le CPID et le renvoie à l'UE avec une durée de vie (TTL) indiquant la durée pendant laquelle l'UE peut utiliser ce CPID.

L'opérateur PEUT également utiliser des adresses IP au lieu de noms de domaine dans l'URL du point de terminaison CPID, si cela est préférable. Les adresses IP PEUVENT se trouver dans un espace d'adressage privé, mais elles doivent être accessibles par les clients Google au sein du réseau de l'opérateur.

L'opérateur DOIT fournir les informations suivantes à Google lors du processus d'intégration :

  1. URL CPID que les applications contacteront pour obtenir des CPID. Une URL CPID_URL est obligatoire, mais l'opérateur peut en fournir plusieurs pour augmenter la disponibilité.
  2. Liste des préfixes IP appartenant à l'opérateur, ainsi que le code pays mobile (MCC) et le ou les codes réseau mobile (MNC) que l'opérateur souhaite mapper aux CPID_URL fournis. Si l'opérateur utilise le SPN ou le GID1 pour distinguer les MVNO de son réseau, il DOIT également fournir ces informations. Google utilisera ces informations pour faire correspondre les clients aux points de terminaison CPID correspondants, comme indiqué à l'étape 1 de la figure 2.

Le format de la requête est le suivant : GET CPID_URL Pour des raisons d'héritage, le point de terminaison CPID doit pouvoir accepter une requête comme celle-ci :

GET CPID_URL?app={app_id}

Le point de terminaison CPID peut ignorer le paramètre d'URL {app_id} lors de la génération du CPID. Toutefois, il DOIT être en mesure de traiter une requête contenant le paramètre.

La requête envoyée au point de terminaison CPID PEUT inclure l'en-tête Accept-Language. Si l'en-tête est inclus, les chaînes lisibles par l'homme dans les mises à jour que le DPA envoie à l'aide de l'API Mobile Data Plan Sharing DOIVENT utiliser les paramètres fournis dans la requête CPID.

Chaque fois que le client émet une requête GET CPID_URL, il DOIT recevoir un nouveau CPID. Si la création du CPID réussit, le point de terminaison CPID DOIT renvoyer une réponse "200 OK". Le corps de la réponse DOIT contenir une instance de CPIDResponse.

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

Le CPID renvoyé DOIT être valide pendant ttlSeconds secondes, même si un abonné a demandé d'autres CPID par la suite. Pour une expérience utilisateur optimale, Google recommande d'utiliser une valeur TTL de 30 jours, mais pas moins de 14 jours. Le GTAF encodera le CPID par RFC2396 lors des appels ultérieurs au DPA.

Génération de CPID

La méthode RECOMMANDÉE pour que le point de terminaison CPID crée un CPID est la suivante :

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

Le point de terminaison CPID concatène le MSISDN, la langue envoyée par le client dans l'en-tête Accept-Language et un code temporel haute résolution, puis le chiffre à l'aide d'AES avec la clé secret. L'horodatage DOIT correspondre à l'heure d'expiration du CPID. Le résultat chiffré est encodé en base64. De plus, lorsque le CPID est utilisé dans une URL, il DOIT être encodé au format URL pour gérer les caractères spéciaux (/+=) utilisés dans Base64. En particulier lorsque GTAF appelle la DPA ou lorsque la DPA appelle l'API de partage de forfait de données mobiles, le CPID DOIT être encodé au format URL.

Selon la situation d'un opérateur donné, l'implémentation du point de terminaison CPID peut être complexe. L'un des problèmes les plus fréquemment rencontrés est l'accès au MSISDN au niveau du point de terminaison CPID. Nous sommes heureux de partager les enseignements tirés de l'intégration des opérateurs. N'hésitez pas à nous contacter si vous rencontrez des difficultés.

Stockage des CPID

Il n'est pas nécessaire de stocker dans une base de données un CPID généré à l'aide du mécanisme décrit ci-dessus. Les informations pertinentes pour traiter les appels au DPA peuvent être obtenues à partir du CPID.

  1. Lorsque le DPA reçoit un appel de GTAF concernant l'état d'un forfait ou des offres, le MSISDN peut être obtenu en déchiffrant le CPID et en extrayant le MSISDN.
  2. Le délai d'expiration du CPID peut être déterminé en déchiffrant le CPID, puis en extrayant le code temporel d'expiration.

Disponibilité et exigences de capacité

Si les clients ne peuvent pas récupérer de CPID, ils ne peuvent accéder à aucune information de l'API Mobile Data Plan. C'est pourquoi l'opérateur DOIT prendre les mesures nécessaires pour assurer la disponibilité du point de terminaison CPID. Ces mesures incluent la présence de plusieurs instances du point de terminaison CPID et des fonctions DPI, ainsi que la redondance physique, du site et du réseau pour les deux fonctions. Elles garantissent également que les ressources et la capacité du système sont adéquates. De plus, le point de terminaison CPID ainsi que la fonction DPI qui injecte l'en-tête doivent avoir une capacité suffisante pour gérer la charge de tous les clients Google qui demandent des CPID. Le point de terminaison CPID peut utiliser des valeurs plus élevées dans le champ ttlSeconds pour réduire la fréquence à laquelle il génère des CPID.

Cas d'erreur

En cas d'erreur, le point de terminaison CPID DOIT renvoyer une erreur HTTP avec un corps de réponse qui DOIT contenir une instance de ErrorResponse. Un bon message d'erreur doit inclure des informations qui peuvent aider à déboguer la cause de l'erreur. Par exemple, en cas de CPID expiré, l'inclusion de la génération du CPID et de son délai d'expiration nous aiderait à confirmer que le point de terminaison CPID fonctionne comme prévu.

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

Le point de terminaison CPID DOIT renvoyer les éléments suivants en fonction du scénario :

  1. Si une demande de CPID est reçue pour un utilisateur qui n'appartient pas au réseau de l'opérateur (par exemple, un utilisateur appartenant à un autre opérateur, mais en itinérance sur le réseau desservi par ce point de terminaison CPID) ou qui n'a pas choisi de partager les informations sur son forfait de données avec Google, le point de terminaison CPID DOIT renvoyer le code d'état HTTP 403 avec USER_ROAMING, USER_OPT_OUT ou INELIGIBLE_FOR_SERVICE comme cause.
  2. Si une requête CPID est reçue avec un numéro de téléphone non valide, le point de terminaison CPID DOIT renvoyer HTTP 400 avec la cause d'erreur INVALID_NUMBER.
  3. Si la requête envoyée au point de terminaison CPID est mal formée d'une autre manière, le point de terminaison CPID DOIT renvoyer le code HTTP 400 avec ERROR_CAUSE_UNSPECIFIED comme cause.
  4. Pour les autres causes d'erreur, tout code d'erreur HTTP compatible est acceptable. En particulier, HTTP 500 est une cause d'erreur appropriée pour tout échec interne au point de terminaison CPID.