Son kullanıcıların Google Cüzdan'a kaydedebileceği neredeyse tüm kartlar iki bileşenle tanımlanır: Kart Sınıfı ve Kart Nesnesi. Bir kullanıcıya kart verdiğinizde, Google Cüzdan API'ye ne tür bir kart oluşturacağını söyleyen bir Passes Class ve bir Passes Object örneğine ihtiyacınız olur. Ayrıca, hediye kartının değeri veya bilet sahibinin adı gibi kartta gösterilecek ayrıntılar da gerekir.
Google Cüzdan API'si, örneklerini oluşturduğunuz ve ardından kullanıcıya verilen bir kart oluşturmak için kullandığınız önceden tanımlanmış bir dizi Kart Sınıfı ve Kart Nesnesi sağlar. Örneğin, GiftCardClass ve GiftCardObject, GenericClass ve GenericObject gibi.
Her Passes Class ve Passes Object örneği, ilgili kart türü için amaçlanan kullanım alanına karşılık gelen bir dizi zorunlu ve isteğe bağlı özelliği olan bir JSON nesnesi olarak tanımlanır.
Kart Sınıfları
Kart sınıfını, kullanıcılarınıza vereceğiniz bir veya daha fazla kart oluşturmak için kullanılan ortak bir şablon olarak düşünebilirsiniz. Bir kart sınıfı, kendisine referans veren tüm kartlara dahil edilecek ortak bir özellikler grubu tanımlar.
Örneğin, aşağıdaki EventTicketClass örneği, yaklaşan bir etkinlik için verilen tüm biletlerde ortak olan alanları(mekan, etkinlik adı, düzenleyen, tarih/saat) tanımlar.
{
"id": "ISSUER_ID.EVENT_CLASS_ID",
"issuerName": "[TEST ONLY] Heraldic Event",
"localizedIssuerName": {
"defaultValue": {
"language": "en-US",
"value": "[TEST ONLY] Heraldic Event"
}
},
"eventName": {
"defaultValue": {
"language": "en-US",
"value": "Google Live"
}
},
"venue": {
"name": {
"defaultValue": {
"language": "en-US",
"value": "Shoreline Amphitheater"
}
},
"address": {
"defaultValue": {
"language": "en-US",
"value": "ADDRESS_OF_THE_VENUE"
}
}
},
"dateTime": {
"start": "2023-04-12T11:30"
},
"reviewStatus": "UNDER_REVIEW"
}
Her Passes Class örneği, sizin belirlediğiniz bir id özelliği gerektirir. Bu sınıf kimliği, yeni bir kart nesnesi örneği oluşturmak için kullandığınız her seferde referans vereceğiniz benzersiz bir tanımlayıcı görevi görür.
Kart Nesneleri
Kart sınıfı örneği, bir veya daha fazla kartta kullanılacak bir dizi ortak özelliği belirtirken kart nesnesi, belirli bir kullanıcıya verilen belirli bir kartın benzersiz ayrıntılarını belirtir.
Örneğin, Google Cüzdan API'si ile bir Etkinlik Bileti Kartı oluşturulduğunda, EventTicketObject
örneği, verilen her bilet için benzersiz olacağından bu bilete atanan koltuğun özelliklerini içerir.
{
"id": "ISSUER_ID.OBJECT_ID",
"classId": "ISSUER_ID.EVENT_CLASS_ID",
"state": "ACTIVE",
"seatInfo": {
"seat": {
"defaultValue": {
"language": "en-us",
"value": "9"
}
},
"row": {
"defaultValue": {
"language": "en-us",
"value": "L"
}
},
"section": {
"defaultValue": {
"language": "en-us",
"value": "45"
}
},
"gate": {
"defaultValue": {
"language": "en-us",
"value": "7C"
}
}
},
"barcode": {
"type": "BARCODE_TYPE_UNSPECIFIED",
"value": "BARCODE_VALUE",
"alternateText": ""
}
}
Her Passes nesnesi örneği, sizin belirlediğiniz bir id özelliği gerektirir. Bu nesne kimliği, kartı kullanıcıya verirken referans olarak kullanacağınız benzersiz bir tanımlayıcı görevi görür.
Kart sınıfları, kart nesneleriyle nasıl çalışır?
Kart Nesneleri, Kart Sınıfı örneğini, sınıf kimliğine referans vererek veya tam Kart Sınıfı tanımını ekleyerek genişletmelidir. Kart sınıfı ile kart nesnesi örneği arasındaki bu ilişki, verilen tüm kartlarda ortak olan özellikleri Kart sınıfı örneği üzerinden, tek bir karta özgü özellikleri ise Kart nesnesi örneği üzerinden ayarlayıp güncelleyebileceğiniz anlamına gelir.
Örneğin, basit bir Etkinlik Bileti kartının aşağıdaki diyagramında, paylaşılan EventTicketClass içinde tanımlanan alanlar ile EventTicketObject içinde tanımlanan belirli bir biletin alanlarının birleştirilerek son verilen kartın nasıl oluşturulduğu gösterilmektedir. Kart sınıfının kimliğinin, Kart Nesnesi'nin classId özelliğinde nasıl referans verildiğine dikkat edin.
Bir Passes Class örneğinde yapılan değişiklikler, kendisine referans veren tüm Passes Object örneklerine anında yansıtılır. Kullanıcılar, Kart Sınıfı örneğinde yaptığınız değişiklikleri bir sonraki senkronizasyonlarında Google Cüzdan uygulamalarındaki kartta görür.
Kullanıcının Google Cüzdan'ına kart ekleme
Kullanıcının Google Cüzdan'ına kart eklemek için, kullanıcının Google Cüzdan'ına kaydedilecek Kart Nesnesi örneği hakkında sizin (kartı veren) yaptığınız talepleri içeren bir JSON Web Token (JWT) oluşturursunuz. En önemlisi, kullanıcıya verdiğiniz Kart Nesnesi örneğinin Nesne Kimliği'dir. JWT, Google Cüzdan'a ekle düğmesi veya Google Cüzdan'a ekle bağlantısı aracılığıyla kullanıcıya iletilir.
Kullanıcı, verilen bir kartı Google Cüzdan'ına eklemek için düğmeyi veya bağlantıyı tıkladıktan sonra, JWT'de kodlanmış Passes Object örneğine ait bir bağlantı, kullanıcının Google Hesabı'na bağlanır. Bu, kullanıcı düğmeyi tekrar tıkladığında ilgili kart nesnesine yönelik bir bağlantı zaten mevcut olduğundan kullanıcının cüzdanına kopya eklenmeyeceği anlamına gelir.
Bir kullanıcı, Google Cüzdan uygulamasından bir kartı kaldırırsa ilgili Passes Object örneğinin kullanıcının bağlantısı otomatik olarak kaldırılır ancak örnek silinmez. Bu, kullanıcının yeni bir Passes Object örneği veya JWT oluşturulmasına gerek kalmadan kartı kaydetmek için Google Cüzdan'a ekle düğmesini ya da bağlantısını tekrar tıklayabileceği anlamına gelir.