Google Cüzdan kartı geliştirme akışı

Google Cüzdan API'si hediye kartları, biniş kartları, etkinlik biletleri gibi belirli kullanım alanları için optimize edilmiş, önceden tanımlanmış bir dizi kart türü sağlar. Belirli bir kart türünün geçerli olmadığı kullanım alanları için kullanılan bir Genel kart türü de vardır.

Bu makale, Google Cüzdan API'sini kullanarak kart oluşturmak ve göndermek için gereken temel adımlar hakkında sizi bilgilendirmek amacıyla hazırlanmıştır. Aşağıda açıklanan adımlardan bazılarını gerçekleştirmenin birden çok yolu vardır ancak genel olarak tüm geçiş türleri, aynı temel geliştirme akışı izlenerek oluşturulur.

Kart oluşturmayla ilgili ayrıntılı ve adım adım açıklamalı kılavuz için Google Cüzdan REST API veya Android SDK kullanımıyla ilgili kılavuzları inceleyin.

Ne işe yarar?

Kartlar Sınıfı, şablona benzer şekilde, birden fazla geçişte ortak olan bir özellik kümesi tanımlar. Örneğin, bir etkinliğin biletlerini yayınlıyorsanız Kartlar Sınıfı tüm biletlerde aynı olan alanları (etkinlik adı, tarih ve saat gibi) tanımlar.

Verdiğiniz her kart, bir Kartlar Sınıfını referans almalıdır. Ayrıca oluşturduğunuz her Kartlar Sınıfına benzersiz bir kimlik atamanız gerekir. Bu kimlik, kartları oluştururken referans olarak kullanılır.

Nasıl yapılır?

Kartlar Sınıfı JSON biçiminde tanımlanır ve Google Cüzdan REST API'si, Android SDK'sı veya Google Cüzdan Business Console ile oluşturulabilir.

Örnek Kartlar Sınıfını göster

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "logo": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "LOGO_IMAGE_DESCRIPTION"
      }
    }
  },
  "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",
  "hexBackgroundColor": "#264750",
  "heroImage": {
    "sourceUri": {
      "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
    },
    "contentDescription": {
      "defaultValue": {
        "language": "en-US",
        "value": "HERO_IMAGE_DESCRIPTION"
      }
    }
  }
}
    

Ne işe yarar?

Kartlar Nesnesi, belirli bir kullanıcıya verilecek benzersiz bir kartın özelliklerini tanımlar. Örneğin, bir etkinlik biletine ilişkin Geçiş Nesnesi, koltuk numarası veya biletin QR kodu gibi belirli bir bilete özgü alanları tanımlar.

Bir Kartlar Nesnesi oluşturulduğunda, Google Cüzdan API'si yeni bir kartı depolar ve kartı Veren hesabınızla ilişkilendirir. Depolanan kart, Kartlar nesnesinin benzersiz özellikleri ile ilişkili Kartlar Sınıfının şablon özelliklerinin bir kombinasyonudur.

Ayrıca her Passes nesnesine benzersiz bir kimlik atamanız gerekir. Bu kimlik, kart verildiğinde bu nesneye referans vermek için kullanılır.

Nasıl yapılır?

Kartlar Nesnesi, JSON biçiminde tanımlanır ve Google Cüzdan REST API'si veya Android SDK'sı ile oluşturulabilir.

Örnek Geçiş Nesnesini göster

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "5"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "G"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "40"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "3A"
      }
    }
  },
  "barcode": {
    "type": "QR_CODE",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
    

Ne işe yarar?

Bir kullanıcıya kullanım hakkı vermek için Passes Class ve Passes Objects bir JSON Web Token (JWT) olarak kodlanmalıdır. JWT biçimi, iki taraf arasındaki hak taleplerini temsil etmeye yönelik yaygın ve açık bir standarttır. Google Cüzdan API'si ile kart verilmesi durumunda JWT'ler, kullanıcının, Kartı Veren hesabınızla ilişkilendirilmiş belirli bir karta erişme hakkına sahip olduğunu iddia etmek için kullanılır.

Google Cüzdan API'sine bir JWT gönderildiğinde, kodlanmış veriler belirli bir kartın tanımlanması ve kullanıcıya verilmesi için kullanılır. Kart daha önce verilmişse bu veriler, Google Cüzdan API'nin ilgili kartın aynı olduğunu tanımlamasına da olanak tanır. Böylece söz konusu kart, kullanıcının Google Cüzdan hesabına birden fazla kez eklenmez.

Nasıl yapılır?

JWT'ler, JWT spesifikasyonuna göre JSON biçiminde tanımlanır. Google Cüzdan API'si ile kart vermek üzere JWT tanımlamak için, vermek istediğiniz kartla ilgili bilgileri JWT'nin payload mülkünde sağlarsınız.

Örnek JWT'yi göster

{
  "iss": "issuer@example.com",
  "aud": "google",
  "typ": "savetowallet",
  "iat": 1696877738,
  "origins": [
    "www.example.com"
  ],
  "payload": {
    "eventTicketObjects": [
      {
        "id": "ISSUER_ID.LOYALTY_OBJECT_SUFFIX"
      }
    ]
  }
}
    

Ne işe yarar?

Kart düzenlemek için Google Cüzdan API'sine gönderilen tüm JWT'ler, daha önce Google Cüzdan İşletme Konsolu'nda sağladığınız kimlik bilgileriyle imzalanmalıdır. İmzalama işlemi, kimlik bilgilerinizi kullanarak JWT'yi şifreleyerek kartlarınızın güvende kalmasını sağlar. Ayrıca Google Cüzdan API'sinin, kendisine kodlanan kart ayrıntılarının geçerli olduğunu ve Kartı Veren hesabınızla ilişkilendirilmiş olduğunu doğrulamasını sağlar.

Nasıl yapılır?

Google Cüzdan istemci kitaplıkları ve Android SDK'sı, JWT'lerinizi imzalamak için kullanışlı yöntemler sunar. Ayrıca, aralarından seçim yapabileceğiniz kod imzalamanın karmaşıklığını kaldıran çok sayıda açık kaynak kitaplığı da vardır.

Kart yayınlamak için Google Cüzdan REST API'sini kullananlar için JWT, Google Cloud Hizmet Hesabı anahtarıyla imzalanır. Google Cüzdan Android SDK'sını kullananlarda SDK, JWT'yi uygulama imzalama sertifikanızın SHA-1 parmak iziyle otomatik olarak imzalar.

Kimlik bilgilerinizi korumak için JWT'ler yalnızca sunucunuzda oturum açmalı veya uygulamanızda Google Cüzdan Android SDK'sı kullanılmalıdır.

Örnek kod imzalamayı göster

Java

  // Create the JWT as a HashMap object
  HashMap claims = new HashMap();
  claims.put("iss", ((ServiceAccountCredentials) credentials).getClientEmail());
  claims.put("aud", "google");
  claims.put("origins", Arrays.asList("www.example.com"));
  claims.put("typ", "savetowallet");

  // Create the Google Wallet payload and add to the JWT
  HashMap payload = new HashMap();
  payload.put("eventTicketObjects", Arrays.asList(newObject));
  claims.put("payload", payload);

  // Google Cloud service account credentials are used to sign the JWT
  Algorithm algorithm =
      Algorithm.RSA256(
          null, (RSAPrivateKey) ((ServiceAccountCredentials) credentials).getPrivateKey());
  String token = JWT.create().withPayload(claims).sign(algorithm);
        

Node.JS

  // Create the JWT claims
  let claims = {
    iss: this.credentials.client_email,
    aud: 'google',
    origins: ['www.example.com'],
    typ: 'savetowallet',
    payload: {
      eventTicketObjects: [newObject]
    },
  };

  // The service account credentials are used to sign the JWT
  let token = jwt.sign(claims, this.credentials.private_key, { algorithm: 'RS256' });
        

Python

  # Create the JWT claims
  claims = {
      'iss': self.credentials.service_account_email,
      'aud': 'google',
      'origins': ['www.example.com'],
      'typ': 'savetowallet',
      'payload': {
          # The listed classes and objects will be created
          'eventTicketObjects': [new_object]
      }
  }

  # The service account credentials are used to sign the JWT
  signer = crypt.RSASigner.from_service_account_file(self.key_file_path)
  token = jwt.encode(signer, claims).decode('utf-8')
        

Ne işe yarar?

İmzalanmış bir JWT oluşturduktan sonra kartınızı Google Cüzdan kullanıcılarına vermeye hazırsınız demektir! Bunun için kullanıcıya bir "Google Cüzdan'a ekle" düğmesi veya bağlantısı sunulur. Bir kullanıcı düğmeyi veya köprüyü tıkladığında, imzalı JWT Google Cüzdan API'sine gönderilir ve daha sonra, kayıtlı kimlik bilgilerinizi kullanarak mesajın şifresini çözer. JWT imzası doğrulandıktan sonra kart, Google Cüzdan'a kaydedilmesi için kullanıcıya verilir.

Nasıl yapılır?

Bir Android uygulaması için "Google Cüzdan'a ekle" düğmesi oluşturmak üzere düğmeyi oluşturma yöntemlerini sağlayan Google Cüzdan Android SDK'sını kullanın. Web, e-posta ve kısa mesaj dahil diğer tüm platformlar için https://pay.google.com/gp/v/save/<signed_jwt> biçiminde bir köprü oluşturun. Mümkün olduğunda, bu bağlantıyı kullanıcıya "Google Cüzdan'a ekle" düğmesi olarak sunmak en iyisidir.

"Google Cüzdan'a ekle" düğmesini kullanma hakkında daha fazla bilgi için Google Cüzdan API'si Marka yönergelerine bakın.

Örnek kodu göster

  https://pay.google.com/gp/v/save/<signed_jwt>
        

Android SDK

  private lateinit var walletClient: PayClient
  private val addToGoogleWalletRequestCode = 1000
  private lateinit var addToGoogleWalletButton: View

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    walletClient = Pay.getClient(this)
    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }
  }
        

Kullanıcı verdiğiniz kartı kaydettikten sonra, kaydettiği diğer kartlarla birlikte Google Cüzdan uygulamasında görebilir.

JWT'de Kart Nesneleri ve Kartlar Sınıfları Oluşturma

Kartlar Sınıfları ve Kartlar Nesneleri, Google Cüzdan REST API'si veya Android SDK'sı kullanılarak önceden oluşturulabilir. Oluşturulan bu kartlar, kimlikleri referans alarak kart yayınlamak için kullanılır.

Alternatif olarak, JSON'u doğrudan kullanıcıya vermek için kullanılan JWT'ye yerleştirerek 'Geçiş Sınıfları ve Nesneleri' "tam zamanında" da oluşturabilirsiniz. Bu yöntemde, Kartlar Sınıfları ve Kartlar Nesneleri, imzalı JWT bir "Google Cüzdan'a Ekle" düğmesi veya bağlantısı kullanılarak gönderildiğinde Google Cüzdan API'si tarafından oluşturulur.

Örneğin, aşağıda payload.eventTicketClasses ve payload.eventTicketObjects özellikleri kullanılarak tanımlanmış yeni Kartlar Sınıfı ve Başarılı Nesneleri olan bir JWT gösterilmektedir. Bu özelliklerin dizi olduğuna ve dolayısıyla bir veya daha fazla Geçiş Sınıfını ya da Başarılı Nesnelerini kabul edebildiğine dikkat edin. JWT'de, mevcut bir Passes Class'a kimliğine referans veren yeni bir Passes Nesnesi de belirtebilirsiniz.

Örnek JWT'yi göster

  {
    "iss": "issuer@example.com",
    "aud": "google",
    "typ": "savetowallet",
    "iat": 1696877738,
    "origins": [
      "www.example.com"
    ],
    "payload": {
      "eventTicketClasses": [{
        "id": "ISSUER_ID.EVENT_CLASS_ID",
        "issuerName": "[TEST ONLY] Heraldic Event",
        "localizedIssuerName": {
          "defaultValue": {
            "language": "en-US",
            "value": "[TEST ONLY] Heraldic Event"
          }
        },
        "logo": {
          "sourceUri": {
            "uri": "https://images.unsplash.com/photo-1475721027785-f74eccf877e2?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=660&h=660"
          },
          "contentDescription": {
            "defaultValue": {
              "language": "en-US",
              "value": "LOGO_IMAGE_DESCRIPTION"
            }
          }
        },
        "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",
        "hexBackgroundColor": "#264750",
        "heroImage": {
          "sourceUri": {
            "uri": "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1032&h=336"
          },
          "contentDescription": {
            "defaultValue": {
              "language": "en-US",
              "value": "HERO_IMAGE_DESCRIPTION"
            }
          }
        }
      }],
      "eventTicketObjects": [{
        "id": "ISSUER_ID.OBJECT_ID",
        "classId": "ISSUER_ID.EVENT_CLASS_ID",
        "state": "ACTIVE",
        "seatInfo": {
          "seat": {
            "defaultValue": {
              "language": "en-us",
              "value": "5"
            }
          },
          "row": {
            "defaultValue": {
              "language": "en-us",
              "value": "G"
            }
          },
          "section": {
            "defaultValue": {
              "language": "en-us",
              "value": "40"
            }
          },
          "gate": {
            "defaultValue": {
              "language": "en-us",
              "value": "3A"
            }
          }
        },
        "barcode": {
          "type": "QR_CODE",
          "value": "BARCODE_VALUE",
          "alternateText": ""
        }
      }]
    }
  }