Google Cüzdan API'sini kullanarak Android'de kart oluşturma

1. Giriş

Genel Bakış

Google Cüzdan API'si, kullanıcılarla çeşitli kart türleri üzerinden etkileşim kurmanıza olanak tanır: bağlılık kartları, teklifler, hediye kartları, etkinlik biletleri, toplu taşıma biletleri, biniş kartları ve daha fazlası. Her kart türü veya geçme sınıfı, kullanıcı deneyimini geliştirmek için kullanım alanına özel alanlar ve özellikler içerir.

Ancak bunlar her kullanım alanına uygun olmayabilir. Daha özelleştirilmiş bir deneyim oluşturmak için genel kart türünü kullanabilirsiniz. Aşağıda, genel kart türünün kullanım alanlarına örnekler verilmiştir:

• Otopark kartları
• Kütüphane üyelik kartları
• Kayıtlı değer kuponları
• Spor salonu üyelik kartları
• Rezervasyonlar

Genel kartları, aşağıdakilerin sunulduğu tüm kullanım alanları için kullanabilirsiniz:

• En fazla üç satırlık bilgi
• (İsteğe bağlı) Barkod grafiği
• (İsteğe bağlı) Ayrıntılar bölümü

Google Cüzdan API'si veya Android uygulamalarına Google Cüzdan'a ekle düğmesi ekleme hakkında daha fazla bilgi edinmek için lütfen Google Cüzdan geliştirici dokümanlarına bakın.

Tüm kart sınıfları ve nesneler Kabul Edilebilir Kullanım Politikası'na uygun olmalıdır.

Kart sınıfları ve nesneleri

Google Cüzdan API'si aşağıdakilerin oluşturulması için yöntemler sunar:

Tür	Açıklama
Kursu geçme	Tek bir kart nesnesi için şablon. Bu sınıfa ait tüm geçiş nesneleriyle ilgili ortak bilgileri içerir.
Nesneyi geçirin	Bir User-ID için benzersiz olan geçiş sınıfı örneği.

Bu codelab hakkında

Bu codelab'de aşağıdaki görevleri tamamlayacaksınız.

1. Demo modunda yeni bir veren hesap oluşturma
2. Kartları vermek için bir hizmet hesabı oluşturun
3. Yeni genel kart sınıfı oluşturma
4. Yeni kart nesnesi oluşturun
5. Kartı kaydetmek için Google Cüzdan'a ekle düğmesi oluşturun
6. Düğmeyi Android uygulamanızda gösterme
7. Kart kaydetme sonucunu işleme

Ön koşullar

• Android Studio
• Git
• Google Cloud Console'a erişimi olan bir Google Hesabı
• Node.js 10 sürümü veya üzeri

Hedefler

Bu codelab'i tamamladıktan sonra şunları yapabileceksiniz:

• Google Cüzdan SDK'sını Android uygulamanıza ekleyin
• Google Cüzdan API'sinin Android destekli bir cihazda kullanılıp kullanılamadığını kontrol etme
• Google Cüzdan'a ekle düğmesi oluşturun

Destek

Codelab'de herhangi bir noktada takılırsanız google-pay/wallet-android-codelab GitHub deposunda referans olarak kullanabileceğiniz eksiksiz bir çözüm bulabilirsiniz.

2. Kurulum

Bu adımda, demo modunda bir Veren hesap oluşturacaksınız. Böylece, kullanıcı cüzdanlarına eklenebilecek kart sınıfları ve nesneler oluşturabilirsiniz. Şimdi bir Google Cloud projesi ve hizmet hesabı oluşturacaksınız. Bunlar, arka uç sunucusuyla aynı şekilde programatik olarak geçiş sınıfları ve nesneleri oluşturmak için kullanılacaktır. Son olarak, Google Cloud hizmet hesabına, Google Cüzdan'ı veren kuruluş hesabınızdaki kartları yönetme yetkisi verirsiniz.

Mobil uygulamalar gibi herkese açık istemcilerde geçiş sınıfları ve nesneler oluşturulabilir. Ancak kartları arka uç sunucusu gibi özel bir istemcide oluşturmak veya kimliği doğrulanmış ve güvenli istekler aracılığıyla istemci uygulamalarınızdan getirmek daha güvenlidir.

Google Cüzdan API'sini veren kuruluş hesabına kaydolun

Google Cüzdan'a yönelik kartlar oluşturmak ve dağıtmak için Kartı Veren hesap gereklidir. Google Pay ve Cüzdan Konsolu. İlk aşamada, demo modunda kart oluşturabilirsiniz. Dolayısıyla oluşturduğunuz kartları yalnızca belirli test kullanıcıları ekleyebilir. Test kullanıcıları Google Pay ve Cüzdan Konsolu.

Demo modu hakkında daha fazla bilgi edinmek için Genel geçiş ön koşullarını inceleyin.

1. Google Pay ve Cüzdan Konsolu
2. Kartı veren kuruluş hesabı oluşturmak için ekrandaki talimatları uygulayın.
3. Google Cüzdan API'si seçeneğini belirleyin.
4. Hizmet şartlarını ve gizlilik politikasını anladığınızı onaylayın
5. Düzenleyen Kimliği değerini bir metin düzenleyiciye veya başka bir konuma kopyalayın
6. Yönet sekmesinde Test hesapları oluştur'u seçin
7. Bu codelab'de kullanacağınız e-posta adreslerini ekleyin

Google Cüzdan API'sini etkinleştir

1. Google Cloud Console'da oturum açın.
2. Google Cloud projeniz yoksa hemen bir proje oluşturun (daha fazla bilgi için Proje oluşturma ve yönetme başlıklı makaleyi inceleyin)
3. Projeniz için Google Cüzdan API'sini (Kartlar için Google Pay API'si olarak da bilinir) etkinleştirin.

Hizmet hesabı ve anahtar oluşturma

Google Cüzdan API'sini çağırmak için bir hizmet hesabı ve hizmet hesabı anahtarı gereklidir. Hizmet hesabı, Google Cüzdan API'sini çağıran kimliktir. Hizmet hesabı anahtarı, uygulamanızı hizmet hesabı olarak tanımlayan bir özel anahtar içerir. Bu anahtar hassas olduğu için gizli tutun.

Bu codelab için mevcut bir hizmet hesabı, gerekli olmayan diğer kaynaklara yönelik izinlere sahip olabileceğinden bu hizmet hesabını kullanırken dikkatli olun.

Hizmet hesabı oluşturma

1. Google Cloud konsolunda Hizmet Hesapları'nı açın.
2. Hizmet hesabınız için bir ad, kimlik ve açıklama girin
3. OLUŞTUR VE DEVAM ET'i seçin
4. BİTTİ'yi seçin

Hizmet hesabı anahtarı oluşturma

1. Hizmet hesabınızı seçin
2. KEYS menüsünü seçin.
3. ANAHTAR EKLE'yi, ardından Yeni anahtar oluştur'u seçin.
4. JSON anahtar türünü seçin
5. OLUŞTUR'u seçin.

Anahtar dosyasını yerel iş istasyonunuza kaydetmeniz istenir. Konumunu unutmayın.

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlayın

GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni, Google SDK'ları tarafından bir hizmet hesabı olarak kimlik doğrulaması yapmak ve bir Google Cloud projesinin farklı API'lerine erişmek için kullanılır.

1. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlamak için Google Cloud hizmet hesabı anahtarları dokümanındaki talimatları uygulayın.
2. Ortam değişkeninin yeni bir terminal (MacOS/Linux) veya komut satırı (Windows) oturumunda ayarlandığını doğrulayın (zaten açıksa yeni bir oturum başlatmanız gerekebilir)

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Hizmet hesabını yetkilendirme

Son olarak, hizmet hesabını Google Cüzdan kartlarını yönetmesi için yetkilendirmeniz gerekir.

1. Google Pay ve Cüzdan Konsolu
2. Kullanıcılar'ı seçin.
3. Kullanıcı davet et'i seçin.
4. Hizmet hesabının e-posta adresini girin (ör. [e-mail])
5. Erişim düzeyi açılır menüsünden Geliştirici veya Yönetici'yi seçin.
6. Davet Et'i seçin.

3. Genel kart sınıfı oluşturma

Bu adımda, kartınız için temel sınıf oluşturacaksınız. Bir kullanıcı için oluşturulan her yeni kart, ilgili kart sınıfında tanımlanan özellikleri devralır.

Bu codelab'de oluşturacağınız kart sınıfı, Genel kartların esnekliğini kullanarak hem kimlik rozeti hem de meydan okuma puanı izleyicisi olarak çalışan bir nesne oluşturur. Bu sınıftan bir kart nesnesi oluşturulduğunda, aşağıdaki grafik gibi görünür.

Bu grafikte, bir kartta ayarlanabilecek tesislerin küçük bir alt kümesi gösterilmektedir. Farklı kart özelliklerinin kullanıcı deneyimini nasıl etkilediğini görmek için Genel kart şablonunu inceleyin.

Kart sınıfları, doğrudan Google Pay ve Cüzdan Konsolu'nu kullanarak veya Google Cüzdan API'sini kullanarak. Bu codelab'de, API'yi kullanarak genel kart sınıfı oluşturacaksınız. Bu, özel bir arka uç sunucusunun geçiş sınıfları oluşturmak için kullanacağı süreci izler.

1. google-pay/wallet-android-codelab GitHub deposunu yerel iş istasyonunuza klonlayın.

   git clone https://github.com/google-pay/wallet-android-codelab.git
   

2. Terminal veya komut satırı isteminizde klonlanan depoyu açın
3. backend dizinine gidin (bu komut dosyaları arka uç sunucu işlemlerini taklit eder)

   cd backend
   

4. Node.js bağımlılıklarını yükleyin

   npm install .
   

5. backend dizininde generic_class.js dosyasını açın
6. issuerId değerini Google Pay'deki Sertifikayı Veren Kimliğinizle değiştirin ve Cüzdan Konsolu

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

7. Terminal veya komut satırı isteminizde generic_class.jskomut dosyasını

   node generic_class.js
   

   çalıştırın.

Kodunuz çalıştırıldığında yeni bir geçiş sınıfı oluşturur ve sınıf kimliğini verir. Sınıf kimliği, kartı verenin kimliği ve ardından geliştirici tarafından tanımlanan bir son ekten oluşur. Bu durumda, sonek codelab_class olarak ayarlanır (sınıf kimliği 1234123412341234123.codelab_class değerine benzerdir). Çıkış günlükleri, Google Cüzdan API'sinin yanıtını da içerir.

4. Projeyi Android Studio'da açma

Klonladığınız GitHub deposu, boş etkinliğe sahip bir Android projesi içeriyor. Bu adımda, ürün sayfasına Google Cüzdan'a ekle düğmesi eklemek için bu etkinlikte düzenleme yapacaksınız.

1. Android Studio'yu açma
2. Dosya'yı ve ardından Aç'ı seçin
3. Depoda android dizinini seçin
4. Aç'ı seçin.

Google Cüzdan SDK'sını uygulamanıza ekleyin

1. Modül düzeyinde Gradle derleme dosyasını açın (android/app/build.gradle)
2. Google Cüzdan SDK'sını dependencies bölümüne ekleyin

   // TODO: Add the "com.google.android.gms:play-services-pay" dependency to
   //       use the Google Wallet API
   implementation "com.google.android.gms:play-services-pay:16.0.3"
   

3. Dosyayı kaydet
4. Dosya'yı, ardından Projeyi Gradle Dosyalarıyla Senkronize Et'i seçin.

5. Şunu oluşturun: Google Cüzdan'a ekle düğmesi

Bu adımda, bir Google Cüzdan'a ekle düğmesi oluşturacak ve bunu mevcut bir etkinliğe ekleyeceksiniz. Düğme öğeleri projeye zaten dahil edilmiştir. Düğmeyi eklemek için ayrı bir düzen dosyası oluşturursunuz. Eklendikten sonra, düğme aşağıdaki gibi görünür.

Düğmeyi kendi uygulamanıza ekliyorsanız düğme için ihtiyaçlarınıza uygun dillerde SVG dosyalarını indirmek üzere Marka yönergeleri sayfasını ziyaret edin. Yalnızca desteklenen yapılandırmalardaki grafikleri eklediğinizden emin olun. Vektör öğelerini Android Studio'da Dosya > Yeni > Vektör Öğesi. Sihirbazda Yerel dosya'yı seçin, bir ad (ör. add_to_google_wallet_button) girin ve iş istasyonunuzdaki dosyayı bulun.

1. Yeni düzen dosyası oluşturun: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Aşağıdaki içeriği yeni düzen dosyasına ekleyin

   <?xml version="1.0" encoding="utf-8"?>
   <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:layout_width="match_parent"
       android:layout_height="48sp"
       android:background="@drawable/add_to_google_wallet_button_background_shape"
       android:clickable="true"
       android:contentDescription="@string/add_to_google_wallet_button_content_description"
       android:focusable="true">
     <ImageView
         android:layout_width="227dp"
         android:layout_height="26dp"
         android:layout_gravity="center"
         android:duplicateParentState="true"
         android:src="@drawable/add_to_google_wallet_button_foreground" />
   </FrameLayout>
   

3. Ödeme etkinliği düzen dosyasına (app/src/main/res/layout/activity_checkout.xml) add_to_google_wallet_button.xml düzenini ekleyin

   <!--
       TODO: Create the button under `add_to_google_wallet_button.xml`
             and include it in your UI
   -->
   <include
       android:id="@+id/addToGoogleWalletButton"
       layout="@layout/add_to_google_wallet_button"
       android:layout_width="match_parent"
       android:layout_height="48dp"
       android:layout_marginTop="10dp" />
   

6. Google Cüzdan API'sinin kullanılıp kullanılamadığını kontrol etme

Bir kullanıcının uygulamanızı Google Cüzdan API'sini desteklemeyen bir cihazda açması, kartı eklemeye çalıştığında olumsuz bir deneyime yol açabilir. Kullanıcının cihazı Google Cüzdan API'sini desteklemiyorsa Google Cüzdan'a ekle düğmesinin gizlenmesi karışıklığı önler. API'nin kullanılamamasının çeşitli nedenleri olabilir. Örneğin, Android veya Google Play Hizmetleri sürümlerinin eski olması veya Google Cüzdan'ın kullanıcının ülkesinde kullanılamaması.

Bu adımda, uygulamanıza Google Cüzdan API'sinin cihazda kullanılıp kullanılamadığını kontrol eden bir mantık ekleyeceksiniz. Bu durumda düğme etkinlikte oluşturulur. Aksi takdirde düğme gizlenir.

Başka tasarım kalıpları kullanıyorsanız alana özgü iş mantığını doğru bir şekilde yerleştirmeyi düşünün. Örneğin, Model-View-ViewModel (MVVM) modelini kullanıyorsanız Etkinliğinize veya Parçanıza kullanıcı arayüzüyle ilgili iş mantığını yerleştirin (ör. kullanıcı arayüzü öğeleri ve etkinlik sonuçları) ve ViewModel'inizdeki operasyonel mantığı (ör. istemci örneklendirmesi ve ağ çağrısı tetikleyicileri).

1. CheckoutActivity.kt dosyasını app/src/main/java/com/google/android/gms/samples/wallet/activity/ uygulamasında aç
2. PayClient örneği

   // TODO: Create a client to interact with the Google Wallet API
   private lateinit var walletClient: PayClient
   

   için bir sınıf mülkü oluşturun
3. onCreate yönteminde

   // TODO: Instantiate the client
   walletClient = Pay.getClient(this)
   

   PayClient özelliğini örneklendirin
4. Cihazda Google Cüzdan SDK'sı ve API'sinin olup olmadığını kontrol eden bir yöntem oluşturup sonucu işleyin

   // TODO: Create a method to check for the Google Wallet SDK and API
   private fun fetchCanUseGoogleWalletApi() {
     walletClient
       .getPayApiAvailabilityStatus(PayClient.RequestType.SAVE_PASSES)
       .addOnSuccessListener { status ->
         if (status == PayApiAvailabilityStatus.AVAILABLE)
           layout.passContainer.visibility = View.VISIBLE
       }
       .addOnFailureListener {
         // Hide the button and optionally show an error message
       }
   }
   

5. Google Cüzdan API'sinin kullanılabilir olup olmadığını kontrol etmek için onCreate yönteminde fetchCanUseGoogleWalletApi yöntemini çağırın

   // TODO: Check if the Google Wallet API is available
   fetchCanUseGoogleWalletApi()
   

Uygulamayı çalıştırdığınızda artık kullanıcı arayüzünde Google Cüzdan'a ekle düğmesini görürsünüz.

Google Cüzdan'a ekle düğmesi görünmüyorsa getPayApiAvailabilityStatus yöntemiyle döndürülen hatayı ve daha fazla bilgi edinmek için günlükleri kontrol edin. Söz konusu kullanıcı, gelecekte API'yi kullanmaya uygun hale gelebilir.

7. Genel kart nesnesi oluşturma

Kartı veren kuruluş hesabınız demo modundaysa yalnızca test kullanıcılarınız için geçiş kartı verebilirsiniz. Uygulamayı farklı bir e-posta adresi kullanarak çalıştırıyorsanız kartı cüzdanınıza ekleyemezsiniz.

Google Cüzdan API'sinin kullanılabildiğini doğruladığınıza göre artık bir kart oluşturabilir ve kullanıcınızdan bu kartı cüzdanına eklemesini isteyebilirsiniz. Kullanıcılar için kart nesneleri oluşturmak için iki akış vardır.

Arka uç sunucusunda geçiş nesnesini oluşturma

Bu yaklaşımda, geçiş nesnesi bir arka uç sunucusunda oluşturulur ve istemci uygulamasına imzalı bir JWT olarak döndürülür. Bu seçenek, kullanıcının cüzdanına eklemeye çalışmadan önce nesnenin mevcut olmasını sağladığından, kullanıcı benimseme oranının yüksek olduğu durumlar için daha uygundur.

Kullanıcı cüzdanına eklediğinde kart nesnesini oluşturma

Bu yaklaşımda, geçiş nesnesi tanımlanır ve arka uç sunucusunda imzalı bir JWT olarak kodlanır. Ardından, JWT'ye referans veren istemci uygulamasında Google Cüzdan'a ekle düğmesi oluşturulur. Kullanıcı düğmeyi seçtiğinde, kart nesnesini oluşturmak için JWT kullanılır. Bu yöntem, geçiş nesnelerin oluşturulmasını ve kullanılmamasını önlediği için kullanıcı benimsemesinin değişken veya bilinmediği durumlar için daha uygundur. Bu yaklaşım codelab'de kullanılacaktır.

1. backend/generic_pass.js dosyasını aç
2. issuerId değerini Google Pay'deki Sertifikayı Veren Kimliğinizle değiştirin ve Cüzdan Konsolu

   // TODO: Define Issuer ID
   let issuerId = 'ISSUER_ID';
   

3. Terminal veya komut satırı isteminizde generic_pass.js dosyasını çalıştırın

   node generic_pass.js
   

4. Çıkış jetonunu panoya veya bir metin düzenleyiciye kopyalayın

Kodunuz çalıştığında yeni bir geçiş nesnesi tanımlar ve bunu bir JWT'ye yerleştirir. JWT, daha önce oluşturduğunuz hizmet hesabı anahtarı tarafından imzalanır. Bu işlem, Google Cüzdan API'sine yapılan isteğin kimliğini doğrular. Böylece, kimlik bilgilerinin istemci uygulamasında depolanmasına gerek kalmaz.

Üretim ortamında arka uç sisteminiz JWT'ler oluşturmaktan ve bunları müşterilere geri vermekten sorumludur. Bu codelab'de, generic_pass.js komut dosyası bu davranışı emüle eder ve "döndürür" istemci uygulamasında kullanmanız için bir jeton.

8. Kartı Google Cüzdan'a ekleyin

Google Cüzdan API'nin kullanılabilir olduğunu doğrulayıp imzalı bir JWT oluşturduğunuza göre artık kullanıcıdan kartı cüzdanına eklemesini isteyebilirsiniz. Bu adımda, kartı kullanıcının cüzdanına kaydetmek için Google Cüzdan API'sini kullanan Google Cüzdan'a ekle düğmesine bir dinleyici eklersiniz.

1. app/src/main/CheckoutActivity.kt dosyasını aç
2. token değerini, daha önce oluşturduğunuz JWT ile değiştirin

   // TODO: Save the JWT from the backend "response"
   private val token = "TOKEN"
   

3. İstek kodunu depolamak için bir sınıf mülkü oluşturun

   // TODO: Add a request code for the save operation
   private val addToGoogleWalletRequestCode = 1000
   

4. Google Cüzdan'a ekle düğmesi

   // TODO: Set an on-click listener on the "Add to Google Wallet" button
   addToGoogleWalletButton = layout.addToGoogleWalletButton.
   
   addToGoogleWalletButton.setOnClickListener {
     walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
   }
   

   için bir işleyici ayarlayın

Kullanıcı Google Cüzdan'a ekle düğmesini seçtiğinde walletClient.savePassesJwt yöntemi çağrılır. Bu yöntemde kullanıcıdan yeni kart nesnesini Google Cüzdan hesabına eklemesi istenir.

9. Kullanıcı başına SavePassesJwt sonucu

Bu codelab'in son adımında uygulamanızı walletClient.savePassesJwt işleminin sonucunu işleyecek şekilde yapılandıracaksınız.

1. app/src/main/CheckoutActivity.kt dosyasını aç
2. onActivityResult yöntemini aşağıdaki kodu içerecek şekilde geçersiz kılın

   // TODO: Handle the result
   override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
     super.onActivityResult(requestCode, resultCode, data)
   
     if (requestCode == addToGoogleWalletRequestCode) {
       when (resultCode) {
         RESULT_OK -> {
           // Pass saved successfully. Consider informing the user.
         }
   
         RESULT_CANCELED -> {
           // Save canceled
         }
   
         PayClient.SavePassesResult.SAVE_ERROR ->
           data?.let { intentData ->
             val errorMessage = intentData.getStringExtra(PayClient.EXTRA_API_ERROR_MESSAGE)
             // Handle error. Consider informing the user.
             Log.e("SavePassesResult", errorMessage.toString())
           }
   
         else -> {
           // Handle unexpected (non-API) exception
         }
       }
     }
   }
   

Uygulamanız artık aşağıdaki senaryoları işleyebilir:

• Kart ekleme işlemi başarılı
• Kullanıcı iptali
• Beklenmeyen hatalar

Kartı ekleyebileceğinizi ve sonucu beklendiği gibi işleyebileceğinizi onaylamak için uygulamanızı çalıştırın.

10. Tebrikler

Tebrikler, Android'e Google Cüzdan API'sini başarıyla entegre ettiniz.

Daha fazla bilgi

google-pay/wallet-android-codelab GitHub deposundaki entegrasyonun tamamına göz atın.

Kart oluşturun ve üretim erişimi isteyin

Üretimde kendi kartlarınızı düzenlemeye hazır olduğunuzda Google Pay ve Cüzdan Konsolu'nu kullanarak üretim erişimi isteğinde bulunun ve Android uygulamanızı yetkilendirin.

Daha fazla bilgi edinmek için Android SDK Ön Koşulları'na bakın.