Genel bakış

Google Cüzdan Kartları API'si, iş ortaklarına toplu taşıma biletinin etkinleştirilmesi için bir uç nokta belirtme olanağı sunar. Etkinleştirme gerektiğinde kullanıcı için bir "Etkinleştir" düğmesi gösterilir. Bu düğme dokunulduğunda, aşağıda açıklanan parametrelerle belirtilen uç nokta çağrılır. Uç nokta, geri dönmeden önce kartın geçerli kullanım bilgilerine (barkod veya görsel inceleme) sahip olduğundan emin olmalıdır. Bu noktada, kullanıcının Cüzdan'ındaki kart, teklifi kullanma bilgilerini gösterecek şekilde güncellenir. Etkinleştirmeden önce, mevcut teklifi kullanma bilgilerinin görüntülenmeyeceğini unutmayın.

Etkinleştirme API'sı

Etkinleştirme uç noktası, API'de transit sınıfında activationOptions kullanılarak belirtilir. İş ortağı, makul gecikmeyle çalışan bir etkinleştirme uç noktası sağlamaktan sorumludur.

  activationOptions: {
    activationUrl: string
  }
Alan Açıklama
activationUrl

string

Etkinleştirme istekleri için çağrılacak iş ortağı uç noktasının URL'si. URL, HTTPS'de barındırılmalı ve robots.txt, URL yolunun UserAgent:Google-Valuables tarafından erişilebilir olmasına izin vermelidir.

Etkinleştirme durumu, activationStatus alanı kullanılarak nesnede depolanır. NOT_ACTIVATED ve ACTIVATED geçerli durumlar arasındadır. Etkinleştirme uç noktası, nesneyi ACTIVATED durumuyla güncellemeli ve nesnenin barkod veya görsel inceleme parametreleri gibi geçerli kullanım bilgilerine sahip olduğundan emin olmalıdır. deviceContext alanı, cihaz sabitleme için kullanılabilir.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
Alan Açıklama
activationStatus

enum (ActivationStatus)

Bu geçiş nesnesinin etkinleştirme durumu. Bu durum, biletin gösterimini değiştirir ve kullanıcıların işlem yapmasına olanak tanır. Örneğin, NOT_ACTIVATED olarak ayarlanırsa bilet ayrıntılarında Etkinleştir düğmesi gösterilir.

Kabul edilebilir değerler şunlardır:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

Nesnenin ilişkilendirileceği cihaz bağlamı. Ayarlanırsa teklifi kullanma bilgileri yalnızca belirtilen cihaza geri verilir.
hasLinkedDevice

boolean

Bu nesnenin şu anda tek bir cihaza bağlı olup olmadığı.
DeviceContext
Alan Açıklama
deviceToken

string

Ayarlanırsa teklifi kullanma bilgileri yalnızca nesnenin etkinleştirilmesinin ardından belirtilen cihaza döndürülür. Bu tanımlayıcı, bir kullanıcının cihazını izlemek için sabit bir tanımlayıcı olarak kullanılamaz. Aynı cihazın farklı geçiş kartlarında, hatta aynı cihazda yapılan farklı etkinleştirmelerde bile değişiklik gösterebilir. Bu ayar yapılırken arayanlar, etkinleştirilmekte olan nesnede de hasLinkedDevice ayarını yapmalıdır.

deviceToken öğesinin, etkinleştirme parametreleri deviceContext alanından alındığını unutmayın.

Cihaz sabitleme

Cihaz sabitleme, kullanıcının bileti bir cihazda etkinleştirmesine ve bilet kullanma bilgilerinin yalnızca bu cihazda gösterilmesini sağlayan bir özelliktir. Bu, biletin yalnızca tek bir cihazda görüntülenmesine izin veren ONE_USER_ONE_DEVICE multipleDevicesAndHoldersAllowedStatus öğesinden ayrıdır. Cihaz sabitleme ile ONE_USER_ALL_DEVICES durumunun kullanılması önerilir.

Kullanıcı, etkinleştirme işleminden önce tüm cihazlarında bileti görebilir ve etkinleştirebilir. Sabitlenen cihaz etkinleştirilip bir cihaza sabitlendikten sonra teklifi kullanma bilgileri görüntülenir. Diğer cihazlarda ise kullanıcının bileti başka bir cihaza taşımasına izin veren bir etkinleştirme düğmesi gösterilir. Bileti taşımak istenen bir işlev değilse ancak herhangi bir cihazda etkinleştirmek istiyorsanız cihaz sabitleme özelliğini kullanmak yerine, etkinleştirme sırasında bilet ONE_USER_ONE_DEVICE olarak güncellenebilir.

Cihaz sabitlemeyi uygulamak için nesnenin, etkinleştirme parametreleri ile alınan deviceToken alanıyla güncellenmesi ve aynı API çağrısında hasLinkedDevice değerini true olarak ayarlamak gerekir. İstenirse gelecekteki bir API çağrısında hasLinkedDevice değeri false olarak ayarlanarak biletin bir cihazla bağlantısı kaldırılabilir.

cihaz sabitleme sıra şeması

Etkinleştirme parametreleri

Etkinleştirme uç noktasına gönderilen istek aşağıdaki parametreleri içerir.

JSON Örneği: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

Tanımlayıcı Açıklama
classId

Tam nitelikli sınıf kimliği. Aşağıdaki biçimi kullanır:

<issuer_id.class_id>
objectIds

Aşağıdaki biçimi kullanan tam nitelikli nesne kimlikleri dizisi:

<issuer_id.object_id>
expTimeMillis EPOCH'dan bu yana geçerlilik süresi (milisaniye cinsinden). Geçerlilik süresi sona erdikten sonra mesajın geçersiz olarak kabul edilmesi gerekir.
eventType Her zaman "activate".
nonce Yinelenen teslimatları takip etme yok.
deviceContext

Google tarafından oluşturulan ve kullanıcının işlem yaptığı cihazı temsil eden benzersiz bir kimlik. Bu kimlik, bir nesneyi cihaza bağlayan güncellemeler yaparken kullanılmalıdır.

Bu kimlik, belirli bir cihazdan gelecekteki istekler için sabit olmayabilir.