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 geçiş türünün kullanılamadığı durumlara yönelik kullanım amaçlı bir genel geçiş türü de mevcuttur.

Bu makale, Google Cüzdan API'sini kullanarak kart oluşturmak ve göndermek için gereken temel adımlar konusunda bilgi vermek amacıyla hazırlanmıştır. Aşağıda ayrıntılı olarak 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ı bir adım adım açıklamalı kılavuz için web, e-posta ve SMS veya Android uygulamaları kılavuzlarını inceleyin.

Ne işe yarar?

Kartlar Sınıfı, şablona benzer şekilde, birden çok kartta ortak olan bir özellik kümesi tanımlar. Örneğin, bir etkinlik için bilet 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 için bir Kartlar Sınıfı belirtilmelidir. Ayrıca oluşturduğunuz her Kartlar Sınıfına benzersiz bir kimlik atamanız gerekir. Bu kimlik, kart oluştururken bu kimlik 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 İşletme Konsolu 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 biletinin Kartlar Nesnesi, belirli bir bilete özgü alanları (ör. koltuk numarası veya ilgili biletin QR kodu) tanımlar.

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

Ayrıca her Kartlar Nesnesine benzersiz bir kimlik atamanız gerekir. Bu kimlik, kart verilirken 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 veya Android SDK ile oluşturulabilir.

Örnek Kartlar 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 geçiş vermek için Passes Sınıfı ve Kartlar Nesnesi, JSON Web Token (JWT) olarak kodlanmalıdır. JWT biçimi, iki taraf arasındaki hak taleplerini temsil etmek için 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ğuna dair bir talep göndermek için kullanılır.

Google Cüzdan API'sine bir JWT gönderildiğinde, kodlanmış veriler belirli bir kartı tanımlamak ve kullanıcıya vermek için kullanılır. Kart daha önce verilmişse bu veriler ayrıca Google Cüzdan API'sinin, ilgili kartın yinelenen bir kart olduğunu tanımlamasına ve böylece kullanıcının Google Cüzdan'ına birden fazla kez eklenmemesine olanak tanır.

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 vermek 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şleminde, kartlarınızın güvende kalması için JWT'yi şifrelemek ve Google Cüzdan API'sinin içinde 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ğlamak için kimlik bilgileriniz kullanılır.

Nasıl yapılır?

Google Cüzdan istemci kitaplıkları ve Android SDK'sı, JWT'lerinizi imzalamanız için kolaylıklar sağlar. Ayrıca, kod imzalama karmaşıklığını giderip aralarından seçim yapabileceğiniz çok sayıda açık kaynak kitaplığı da vardır.

Kart düzenlemek için Google Cüzdan REST API'yi kullananlar için JWT, Google Cloud Hizmet Hesabı anahtarıyla imzalanır. Google Cüzdan Android SDK'sını kullananlar için SDK, uygulama imzalama sertifikanızın SHA-1 parmak iziyle JWT'yi otomatik olarak imzalama işlemini gerçekleştirir.

Kimlik bilgilerinizi korumak için JWT'ler yalnızca sunucunuzda oturum açılmalı 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ı bir Google Cüzdan kullanıcısına vermeye hazırsınız demektir! Bu işlem, kullanıcıya "Google Cüzdan'a ekle" düğmesi veya bağlantısı gösterilerek yapılır. Kullanıcı düğmeyi veya köprüyü tıkladığında, imzalı JWT Google Cüzdan API'sine gönderilir ve ardından kayıtlı kimlik bilgilerinizi kullanarak mesajın şifresini çözer. JWT imzası doğrulandıktan sonra kart, Google Cüzdan hesabına 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üğmenin oluşturulmasına ilişkin yöntemler sunan Google Cüzdan Android SDK'sını kullanın. Web, e-posta ve kısa mesaj dahil olmak üzere 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ünse, en iyisi bu bağlantının kullanıcıya "Google Cüzdan'a ekle" düğmesi olarak sunulmasıdır.

"Google Cüzdan'a ekle" düğmesini kullanma hakkında daha fazla bilgi için Google Cüzdan API'si Marka kurallarına 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 veya Android SDK kullanılarak önceden oluşturulabilir. Oluşturulan kartlar, kimliklerini belirterek geçiş kartı yayınlamak için kullanılır.

Alternatif olarak, JSON'larını doğrudan bir kullanıcıya vermek için kullanılan JWT'ye yerleştirerek 'Tam zamanında' Kartlar Sınıfları ve Nesneler oluşturabilirsiniz. Bu yöntemde, Kartlar Sınıfları ve Kartlar Nesneleri, imzalanmış 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 Kartlar Nesnesi olan bir JWT gösterilmektedir. Bu özelliklerin dizi olduğuna ve bir veya daha fazla Kartlar Sınıfı ya da Kartlar Nesnesi kabul edebildiğine dikkat edin. JWT'de, kimliğine göre mevcut bir Kartlar Sınıfına 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": ""
        }
      }]
    }
  }