Bu sayfa, Cloud Translation API ile çevrilmiştir.

Google Cüzdan'daki Motics biletleriyle ilgili teknik ayrıntılar

Bu sayfada, bir Toplu Taşıma Operatörü'nün (PTO) ve Google ile entegrasyon sağlamaları gerekir. Google Cüzdan'da satın alabilirsiniz. Çözüm, Google Cüzdan API'sini kullanıyor ve etkinleştirme uç noktası uygulamasından bahsedelim.

Sistem Mimarisi

Bu bölümde sistem mimarisi ve Motics kaydetme akışı gösterilmektedir.

. Şekil 1. Motics Bilet Kaydetme Akışı

Şekil 1'de bir Motics bileti oluşturma, etkinleştirme ve sabitleme akışı gösterilmektedir Google Cüzdan'da çeşitli tüzel kişiler:

Google sunucuları
PTO (Sistem Entegratörü) sunucusu
Motics SCE sunucusu
Web mağazası

Aşağıda, akış daha ayrıntılı olarak açıklanmaktadır:

İlk kurulum aşamasında, PTO sunucusu transitClass oluşturur. transitClass:Insert komutunu kullanarak ownerId ve activationUrl öğelerini iletme Google Cüzdan API uç noktası. Bu tek seferlik bir etkinliktir.
Ardından, bir kullanıcı web mağazasından bir bilet satın aldığında PTO sunucusu transitObject:Insert ve bazı temel bilet işlemleri bilgilerini içeren başlangıç alanları için geçerlidir.
Ardından PTO sunucusu ve web mağazası birlikte çalışarak Google Cüzdan'a ekle düğmesine basın ve nihai olarak biletin JWT'sini şuraya gönderin: kayıt bağlantısını kullanarak.
Artık bilet sabitleme aşaması başlayabilir. Bu işlemde Google sunucusu, Etkinleştirme Uç Noktası activationUrl arkasındadır.
4. adıma yanıt olarak PTO sunucusu imzayı oluşturur (sigSTB) SAM ile imzalanmış SCE_ID numarasını içeren.
activationUrl çağrısına yanıt vermeden önce PTO sunucusu gerekli tüm Motics bilgilerini içeren transitObject:Patch öğesini arayın, Buna, Motics applicationData dahildir.
PTO ancak transitObject:Patch çağrısı başarılı olduktan sonra sunucu, activationUrl için başarılı (HTTP-200) yanıtı döndürmelidir çağrısına bir tıklama URL'si eklemeniz gerekir.

Taşıma ve Uygulama Akışın Bağlantısını Kaldır

İyi bir kullanıcı deneyimi sağlamak için kullanıcı, Motics'lerini kartı veren kuruluş tarafından tanımlanan belirli sınırlar dahilinde bir cihazdan diğerine bilet gönderebilir. Bunu yapmak için kartı veren kuruluşun Taşıma ve Bağlantısını Kaldırma Akışı'nı uygulaması gerekir.

Etkinleştirme Uç Noktası

Kartı veren kuruluşun/PTO'nun (veya sistem entegratörü) bir destek kaydı oluşturması gerekir. Google'ın bilet kaydedildiğinde çağıracağı etkinleştirme uç noktası. URL transitClass:Insert çağrısında sağlanmalıdır. Etkinleştirme uç noktası, imzayı (sigSTB) oluşturur ve Aşağıda tanımlanan parametrelere sahip transitObject:Patch yöntemi bölümüne bakın.

İstek

Etkinleştirme uç noktasına gönderilen istek aşağıdaki biçimdedir:

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,
}

Yanıt

Gövdesi boş olan bir HTTP-200 başarılı yanıtı, şu durumlarda döndürülmelidir:

SCE_ID içeren sigSTB oluşturuldu ve SAM ile imzalandı
transitObject:Patch yöntemi başarıyla çağrıldı

Status: 200 - OK
Body: {}

Gecikme Hedefleri

Etkinleştirme uç noktası, aşağıdaki gecikme hedeflerine uymalıdır:

Tüm isteklerden en az 50% tanesine 200ms içinde yanıt verilmelidir.
Tüm isteklerden en az 95% tanesine 2s içinde yanıt verilmelidir.
10s katı bir üst sınır var

Google Cüzdan API'si değişiklikleri

Google Cüzdan API uç noktalarında yapılan değişiklikler aşağıda özetlenmiştir: sistem mimarisinde belirtildiği gibi Motics'i desteklemelidir.

Yöntem: geçişSınıfı:insert

Bu, Google'ın sitesinde transitClass oluşturmak için kullanılan Google Cüzdan API uç noktasıdır. arka uçta olması gerekir. Sistem entegratörü, bu API'yi aşağıdaki yöntemlerle çağırmalıdır. istek parametreleriyle birlikte geçerli olan diğer tüm alanlarla birlikte sağlayın. Referans transitClass ve transitClass.Insert API belgelerinin tam listesi için (Motics olmayan) parametrelerini ve daha fazla ayrıntıyı inceleyebilirsiniz.

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

JSON gösterimi

Motics entegrasyonu en azından aşağıdaki JSON temsilini gerektirir: transitClass:insert istek gövdesindeki transitClass. Diğer zorunlu transitClass meta veri alanının da ayarlanması gerekir.

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

certEnvironment = PRODUCTION olduğunda Google sunucusu sertifikayı getirir. Studio'dan alır. certEnvironment = Google sunucusu, sertifikayı korumalı alan Motics sunucusundan getirir.

Yöntem: transitObject:insert

Bu, yeni için transitObject öğesinin ekleneceği Google Cüzdan API uç noktasıdır satın almak ve Google Cüzdan'a eklemek istediği bileti verebilirsiniz. Sistem entegratör, temel olarak bilet bilgileri içeren bir transitObject geçirmelidir. bu noktada. transitObject ve transitObject.Insert API'si belgelerini inceleyin.

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

JSON gösterimi

Motics entegrasyonu en azından aşağıdaki JSON temsilini gerektirir: transitObject:insert istek gövdesindeki transitObject. Diğer nesne meta veri alanları da ayarlanabilir ve diğer tüm zorunlu alanlar da dahil.

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

Notlar:

API, applicationData alanının dahil edilmesini gerektirir. Bu noktada Motics etkinleştirme akışında, applicationData değeri henüz bilinmiyor, boş bir dizeye ayarlanması gerekir.
- applicationData, transitObject:Patch içinde daha sonra ayarlanacak çağrısına bir tıklama URL'si eklemeniz gerekir.
validTimeInterval DateTime nesnelerinin saat dilimi farkı olmalıdır belirtildi, örneğin: 2024-04-12T19:20:50.52-04:00.

Yöntem: transitObject:patch

Bu, transitObject uygulamasına yama uygulanacak verilerle kullanılacak Google Cüzdan API uç noktasıdır Google tarafından Motics barkod oluşturmak ve VDV eTicket Hizmeti'ni getirmek için kullanılır ekleyebilirsiniz. transitObject ve transitObject.Patch API'si belgelerini inceleyin.

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

JSON gösterimi

Motics entegrasyonu, transitObject:patch istek gövdesinde transitObject. Bu konumda olduğunu unutmayın applicationData alanının doldurulduğundan emin olun.

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

Uygulama Verileri spesifikasyonları

Aşağıda, applicationData (etiket:0x5F07). applicationData, şunun tarafından oluşturulmalıdır: sistem entegratörü etiket-uzunluğu-değer (TLV) biçimindedir. Bu veriler daha sonra son olarak QR kodunun bir parçası olarak kodlanacak daha büyük bir veri yapısı içine alınmalıdır girin.

Etiket	Uzunluk	Değer
`0x9E`	81 80	İmza `OctetString`, imzalı yararlanma hakkı verilerinin ilk 128 baytı Google terimi: `sigSTB`
`0x9A`	Değişir	Kalan veriler `OctetString`, kalan yararlanma hakkı verileri Google terimi: `sigSTB cont.`
`0x7F21`	81 C8	Belgeyi veren kuruluş belgesi `OctetString`, sertifika verileri Google terimi: `Cert(puk_SAM)`
`0x42`	08	Sertifika Yetkilisi Referansı (CAR) `OctetString`, CAR değeri Google terimi: `CAR`