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ı, bir şablona benzer şekilde, birden fazla kartta ortak olan bir dizi özelliği tanımlar. Örneğin, bir etkinlik için bilet yayınlıyorsanız Kartlar Sınıfı, tüm biletlerde aynı olan etkinlik adı, tarih ve saat gibi alanları tanımlar.

Verdiğiniz her kart, bir Passes Class'a referans vermelidir. Ayrıca oluşturduğunuz her Kart Sınıfına benzersiz bir kimlik atamanız gerekir. Bu kimlik, kartları oluştururken bu kimliklere referans vermek için kullanılır.

Nasıl yapılır?

Kartlar, JSON biçiminde tanımlanır ve Google Cüzdan REST API, Android SDK veya Google Cüzdan Business Console'da 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 kartın özelliklerini tanımlar. Örneğin, bir etkinlik biletinin Kartlar Nesnesi, belirli bir bilete özel alanları (ör. koltuk numarası veya o biletin QR kodu) tanımlar.

Kartlar Nesnesi oluşturulduğunda, Google Cüzdan API'si yeni bir kart depolar ve bunu, kartı veren kuruluş hesabınızla ilişkilendirir. Depolanan bu kart, Passes Nesnesi'nin benzersiz özellikleri ile ilişkili Kartlar Sınıfının şablon özelliklerinin birleşimidir.

Ayrıca her Passes Nesnesi'ne benzersiz bir kimlik atamanız gerekir. Bu kimlik, kart verirken bu kimliğe referans vermek için kullanılır.

Nasıl yapılır?

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

Örnek Kartlar Nesnesi'ni 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ş yapmak için Passes Class and Passes Nesnesi JSON Web Token (JWT) olarak kodlanmalıdır. JWT biçimi, iki taraf arasındaki hak taleplerini temsil etmek için kullanılan yaygın ve açık bir standarttır. Google Cüzdan API'si ile kart verilmesi durumunda JWT'lar, kullanıcının, Kartı Veren Kuruluş hesabınızla ilişkilendirilmiş belirli bir karta erişim hakkı olduğunu iddia etmek için kullanılır.

Google Cüzdan API'sine JWT gönderildiğinde, kodlanmış veriler belirli bir kartı tanımlamak ve kullanıcıya vermek için kullanılır. Kartın daha önce düzenlenmiş olması durumunda bu veriler, Google Cüzdan API'sinin kartın kopya olduğunu tespit etmesini ve böylece kullanıcının Google Cüzdan'ına birden fazla kez eklenmemesini sağlar.

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 için bir JWT tanımlamak amacıyla, düzenlemek istediğiniz kartla ilgili bilgileri JWT'nin payload özelliğinde 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 Business Console'da sağladığınız kimlik bilgileriyle imzalanmalıdır. İmzalama işlemi, kimlik bilgilerinizi kullanarak kartlarınızın güvende kalmasını sağlar. Ayrıca, Google Cüzdan API'sinin, içinde kodlanan kart ayrıntılarının geçerli olduğunu ve kartınızı veren kuruluş hesabınızla ilişkili olduğunu doğrulamasını sağlamak için kullanılır.

Nasıl yapılır?

Google Cüzdan istemci kitaplıkları ve Android SDK'sı, JWT'lerinizi imzalamak için kolaylık sağlayan yöntemler sunar. Ayrıca kod imzalama sürecinin karmaşıklığını yönetecek çok sayıda açık kaynak kitaplık da vardır.

Kart vermek için Google Cüzdan REST API'yi kullananların JWT, bir Google Cloud Hizmet Hesabı anahtarıyla imzalanması gerekir. Google Cüzdan Android SDK'sı kullananlar için SDK, uygulama imzalama sertifikanızın SHA-1 parmak iziyle JWT'yi otomatik olarak imzalamayı işler.

Kimlik bilgilerinizi korumak için JWT'lerin yalnızca sunucunuzda imzalanması veya uygulamanızda Google Cüzdan Android SDK'sı kullanılması gerekir.

Ö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 verebilirsiniz. Bu işlem, kullanıcıya "Google Cüzdan'a ekle" seçeneği sunarak yapılır kullanabilirsiniz. Bir kullanıcı düğmeyi veya köprüyü tıkladığında, imzalanmış JWT, Google Cüzdan API'sine gönderilir ve daha sonra, kayıtlı kimlik bilgilerinizi kullanarak şifrenin şifresini çözer. JWT imzasının kimliği doğrulandıktan sonra kart, Google Cüzdan'ına kaydetmesi için kullanıcıya verilir.

Nasıl yapılır?

"Google Cüzdan'a ekle" hesabı oluşturmak için düğmesi, düğmenin oluşturulmasına ilişkin yöntemler 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" olarak sunmak en iyi seçenektir düğmesini tıklayın.

"Google Cüzdan'a ekle" seçeneğini kullanma hakkında daha fazla bilgi 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ınız verdiği kartı kaydettikten sonra, kaydettiği diğer kartlarla birlikte Google Cüzdan uygulamasında görünür.

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

Kartlar ve Kartlar Nesneleri, Google Cüzdan REST API veya Android SDK kullanılarak önceden oluşturulabilir. Bu kartlar, oluşturulduktan sonra kimliklerini referans alarak kartları düzenlemek için kullanılır.

Alternatif olarak, Kartlar Sınıfları ve Geçiş Nesneleri'ni "tam zamanında" oluşturabilirsiniz. kullanıcının JSON'ını doğrudan kullanıcıya göndermek için kullanılan JWT'ye yerleştirerek. Bu yöntemde, imzalı JWT bir "Google Cüzdan'a ekle" kullanılarak gönderildiğinde Kartlar Sınıfları ve Kartlar Nesneleri, Google Cüzdan API'si tarafından oluşturulur. kullanabilirsiniz.

Örneğin, aşağıda payload.eventTicketClasses ve payload.eventTicketObjects özellikleri kullanılarak tanımlanan yeni bir Passes Class and Passes Object'e sahip bir JWT gösterilmektedir. Bu özelliklerin dizi olduğunu, dolayısıyla bir veya daha fazla Geçiş Sınıfı ya da Geçiş Nesnesi kabul edebildiğine dikkat edin. JWT'de yalnızca mevcut bir Passes Class'a kimliğine göre 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": ""
        }
      }]
    }
  }