Établir le CPID

Le GTAF utilise une clé utilisateur pour identifier un abonné lorsqu'il communique avec l'APD. Les applications qui ont accès au fichier MSISDN peuvent l'utiliser comme clé utilisateur. D'autre part, les applications qui n'ont pas accès au fichier MSISDN doivent établir un identifiant de forfait de l'opérateur (CPID) sans découvrir le fichier MSISDN de l'utilisateur. Dans ce qui suit, nous décrivons le mécanisme qui établit un CPID.

Flux d'appel CPID

Figure 2: Flux d'appels pour établir le CPID

  1. Une application Google dans l'UE utilise une API interne à Google pour récupérer l'URL du point de terminaison CPID à partir du GTAF. L'opérateur est identifié à l'aide de l'adresse IP publique du client et du CM+MNC de la carte SIM active. Dans le cas des MVNO, Google utilise le SPN et le GID1 pour déterminer le MVNO.
  2. Le client envoie 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 de 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 valeur TTL (Time To Live) indiquant la durée pendant laquelle l'UE peut l'utiliser.

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 l'espace d'adresses privé, mais elles doivent être accessibles aux clients Google au sein du réseau des opérateurs.

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

  1. CPID_URL que les applications contactent pour obtenir les CPID. Une URL CPID_URL est obligatoire, mais l'opérateur peut fournir plusieurs URL pour augmenter la disponibilité.
  2. Liste des préfixes IP appartenant à l'opérateur, et des codes pays et code des réseaux mobiles (CM) que l'opérateur souhaite mapper aux URL CPID_URL fournies. Si l'opérateur utilise SPN ou GID1 pour distinguer les MVNO de son réseau, il DOIT également fournir ces informations. Google utilisera ces informations pour mettre les clients en correspondance avec les 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 les anciennes raisons, le point de terminaison CPID doit être compatible avec les requêtes suivantes:

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 pouvoir 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 dans les mises à jour envoyées par le DPA à l'aide de l'API Mobile Data Plan Sharing doivent impérativement utiliser les paramètres fournis dans la requête CPID.

Chaque fois que le client émet une requête CPID_URL GET, il DOIT recevoir un nouveau CPID. Si la création du CPID aboutit, 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, 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. GTAF encodera le CPID conformément à la RFC2396 lors des prochains appels à l'APD.

Génération du CPID

Pour que le point de terminaison CPID crée un CPID, il est RECOMMANDÉ:

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, ainsi qu'un horodatage de haute résolution et le chiffre via AES à l'aide d'une clé secret. L'horodatage DOIT correspondre à l'expiration du CPID. La sortie chiffrée est encodée en base64. De plus, lorsque le CPID est utilisé dans une URL, il DOIT être encodé en URL pour gérer les caractères spéciaux (/+=) utilisés en base64. En particulier, lorsque la GTAF appelle le DPA ou lorsque le DPA appelle l'API Mobile Data Plan Sharing, le CPID DOIT être encodé au format URL.

En fonction de la situation des opérateurs, l'implémentation du point de terminaison CPID peut s'avérer complexe. L'accès au fichier MSISDN au niveau du point de terminaison CPID est un défi courant. Nous sommes ravis de partager les enseignements tirés des opérateurs d'intégration. N'hésitez pas à nous contacter si vous rencontrez des problèmes.

Stockage CPID

Un CPID généré à l'aide du mécanisme décrit ci-dessus n'a pas besoin d'être stocké dans une base de données. Les informations pertinentes pour gérer les appels au DPA peuvent être obtenues à partir du CPID.

  1. Lorsque le DPA reçoit un appel de la GTAF concernant un forfait ou une offre, 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 obtenu en déchiffrant le CPID, puis en extrayant l'horodatage d'expiration.

Disponibilité et capacité requises

Si les clients ne peuvent pas récupérer de CPID, ils ne peuvent accéder à aucune information de l'API Mobile Data Plan. Pour cette raison, l'opérateur DOIT prendre les mesures nécessaires pour garantir la disponibilité du point de terminaison CPID. Ces mesures incluent la possibilité d'avoir plusieurs instances du point de terminaison CPID et des fonctions PPP, ainsi qu'une redondance physique, de site et de réseau pour les deux fonctions, et de garantir que les ressources système et la capacité sont adéquates. De plus, le point de terminaison CPID ainsi que la fonction PPP qui injecte l'en-tête doivent disposer d'une capacité suffisante pour gérer la charge de tous les clients Google demandant 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

Si une erreur se produit, le point de terminaison CPID DOIT renvoyer une erreur HTTP avec un corps de réponse DOIT contenir une instance de ErrorResponse. Un message d'erreur correct peut inclure des informations susceptibles de l'aider à déboguer la cause de l'erreur. Par exemple, si un CPID est arrivé à expiration, y compris la génération et le délai d'expiration du CPID, nous pouvons vérifier que le point de terminaison CPID fonctionne comme prévu.

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

Le point de terminaison CPID DOIT renvoyer le résultat suivant en fonction du scénario:

  1. Si une requête 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 et itinérant sur le réseau desservi par ce point de terminaison CPID) ou qui n'a pas choisi de partager les informations du forfait avec Google, le point de terminaison CPID DOIT renvoyer le code d'état HTTP 403 avec USER_ROAMING, USER_OPT_OUT ou INELIGIBLE_FOR.
  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 le code HTTP 400 avec une cause d'erreur INVALID_NUMBER.
  3. Si la requête envoyée au point de terminaison CPID est incorrecte, le point de terminaison CPID DOIT renvoyer le code HTTP 400 avec comme erreur ERROR_CAUSE_UNSPECIFIED.
  4. Pour les autres causes d'erreur, tout code d'erreur HTTP compatible est accepté. En particulier, HTTP 500 est une cause d'erreur adaptée en cas de défaillance interne du point de terminaison CPID.