Cette page a été traduite par l'API Cloud Translation.

Détails techniques des billets Motics dans Google Wallet

Cette page fournit les détails techniques d'un opérateur de transports en commun (PTO) et son intégrateur système doit s'intégrer à Google pour fournir des tickets Motics. dans Google Wallet. La solution utilise l'API Google Wallet et s'appuie également sur l'opérateur de transports en commun pour implémenter un point de terminaison d'activation.

Architecture du système

Cette section présente l'architecture du système et le flux d'enregistrement Motics.

Figure 1 : Parcours d'économie d'un billet pour la course à pied

La figure 1 illustre le processus de création, d'activation et d'épinglage d'un ticket Motics dans Google Wallet, dans plusieurs entités:

les serveurs de Google.
Serveur de l'intégrateur système
Serveur Motics SCE
Boutique en ligne

Vous trouverez ci-dessous une description plus détaillée de la procédure à suivre:

Dans la phase de configuration initiale, le serveur de l'opérateur de transports en commun crée le transitClass, en transmettant ownerId et activationUrl à l'aide de transitClass:Insert. Point de terminaison de l'API Google Wallet. Il s'agit d'une activité ponctuelle.
Ensuite, lorsqu'un utilisateur achète un billet à la boutique en ligne, le serveur de l'opérateur de transports en commun appelle transitObject:Insert contenant des informations de base sur les billets et quelques des champs initiaux indiquant qu'il s'agit d'un ticket Motics.
Ensuite, le serveur de l'opérateur de transports en commun et la boutique en ligne travaillent ensemble pour afficher le Ajouter à Google Wallet et renvoyer le JWT du billet au Google, à l'aide du lien "Enregistrer".
La phase d'épinglage des demandes peut maintenant commencer. Lorsque le serveur Google appelle la méthode Point de terminaison d'activation derrière activationUrl.
En réponse à l'étape 4, le serveur de l'opérateur de transports en commun génère la signature (sigSTB). contenant le SCE_ID signé avec le SAM.
Avant de répondre à l'appel activationUrl, le serveur de l'opérateur de transports en commun doit d'abord appelez transitObject:Patch, contenant toutes les informations Motics nécessaires, y compris les applicationData Motics.
Ce n'est qu'une fois que l'appel transitObject:Patch a abouti que l'opérateur de transports en commun le serveur doit renvoyer une réponse de réussite (HTTP-200) à activationUrl .

Implémentez le transfert et Dissocier le flux

Pour offrir une bonne expérience utilisateur, l'utilisateur doit pouvoir déplacer ses éléments Motics d'un appareil à un autre, dans les limites définies par l'émetteur. Pour ce faire, l'émetteur doit implémenter le flux de déplacement et de dissociation.

Point de terminaison d'activation

L'émetteur/l'opérateur de transports en commun (ou son intégrateur système) doit implémenter une demande point de terminaison d'activation que Google appellera lorsque le billet sera enregistré. L'URL à ce point de terminaison doit être indiqué dans l'appel de transitClass:Insert. Le point de terminaison d'activation générera la signature (sigSTB) et appellera transitObject:Patch avec les paramètres définis dans les éléments suivants : .

Requête

La requête envoyée au point de terminaison d'activation a le format suivant:

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

Réponse

Une réponse positive HTTP-200 avec un corps vide doit être renvoyée dans les cas suivants:

Le sigSTB contenant SCE_ID a été généré et signé avec le SAM
La méthode transitObject:Patch a bien été appelée

Status: 200 - OK
Body: {}

Cibles de latence

Le point de terminaison d'activation doit respecter les objectifs de latence suivants:

Au moins 50% de l'ensemble des demandes doivent recevoir une réponse sous 200ms
Au moins 95% de l'ensemble des demandes doivent recevoir une réponse sous 2s
La limite supérieure stricte est fixée à 10s.

Modifications apportées à l'API Google Wallet

Vous trouverez ci-dessous les modifications apportées aux points de terminaison de l'API Google Wallet afin de sont compatibles avec Motics, comme indiqué dans l'architecture du système.

Méthode: transitClass:insert

Il s'agit du point de terminaison de l'API Google Wallet permettant de créer un transitClass sur le backend. L'intégrateur système doit appeler cette API avec le code suivant : et tous les autres champs qui s'appliquent, le cas échéant. Consultez transitClass et transitClass.Insert pour obtenir la liste complète des API (autres que "Motics") et plus de détails.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

Représentation JSON

L'intégration Motics nécessite au minimum la représentation JSON suivante : transitClass dans le corps de la requête transitClass:insert. Autre obligatoire Vous devez également définir les champs de métadonnées transitClass.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

Lorsque certEnvironment = PRODUCTION, le serveur Google récupère le certificat à partir du serveur Motics de production. Lorsque certEnvironment = STAGING récupérera le certificat à partir du serveur Motics Sandbox.

Méthode: transitObject:insert

Il s'agit du point de terminaison de l'API Google Wallet permettant d'insérer le transitObject pour le nouveau titre de transport qu'un utilisateur souhaite acheter et ajouter à Google Wallet. Le système l'intégrateur doit transmettre un transitObject contenant principalement les informations de ticket à l'adresse à ce stade. Reportez-vous à la propriété transitObject. API transitObject.Insert pour obtenir la liste complète des paramètres (hors Mobile) et plus de détails.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

Représentation JSON

L'intégration Motics nécessite au minimum la représentation JSON suivante : transitObject dans le corps de la requête transitObject:insert. Autre objet les champs de métadonnées peuvent être définis, et tous les autres champs obligatoires doivent également être inclus.

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

Remarques :

L'API nécessite que le champ applicationData soit inclus. À ce stade dans le flux d'activation Motics, la valeur applicationData n'est pas encore connue, il doit donc être défini sur une chaîne vide.
- Le applicationData sera défini plus tard dans transitObject:Patch .
Les objets DateTime validTimeInterval doivent comporter un décalage horaire. spécifié, par exemple: 2024-04-12T19:20:50.52-04:00.

Méthode: transitObject:patch

Il s'agit du point de terminaison de l'API Google Wallet pour corriger le transitObject avec les données à utilisé par Google pour générer des codes-barres Motics et récupérer le service VDV eTicket certificats. Reportez-vous à la propriété transitObject. API transitObject.Patch pour obtenir la liste complète des paramètres (hors Mobile) et plus de détails.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

Représentation JSON

L'intégration Motics nécessite la représentation suivante de l'objet transitObject dans le corps de la requête transitObject:patch. Notez qu'il s'agit point où le champ applicationData est renseigné.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

Spécifications des données d'application

Voici la spécification Motics pour le contenu du applicationData (tag:0x5F07). Le applicationData doit être généré par l'intégrateur système au format tag-length-value (TLV) Ces données sont plus tard encapsulés dans une structure de données plus grande pour être enfin encodés dans le code QR du code source.

Tag	Longueur	Valeur
`0x9E`	81 80	Signature `OctetString`, 128 premiers octets de données de droit d'accès signées Terme Google: `sigSTB`
`0x9A`	Variable	Données résiduelles `OctetString`, données résiduelles des droits d'accès Terme Google: `sigSTB cont.`
`0x7F21`	81 C8	Certificat de l'émetteur `OctetString`, données du certificat Terme Google: `Cert(puk_SAM)`
`0x42`	08	Référence de l'autorité de certification (CAR) `OctetString`, valeur CAR Terme Google: `CAR`