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

1. Giriş

Genel Bakış

Google Cüzdan API'si, bağlılık kartları, teklifler, hediye kartları, etkinlik biletleri, toplu taşıma biletleri ve biniş kartları gibi çeşitli kart türleri aracılığıyla kullanıcılarla etkileşim kurmanıza olanak tanır. Her kart türü veya kart sınıfı, kullanıcı deneyimini iyileş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. Genel kart türü için bazı örnek kullanım alanlarını aşağıda bulabilirsiniz:

• Otopark kartları
• Kütüphane üyelik kartları
• Yüklü kart kuponları
• Spor salonu üyelik kartları
• Rezervasyonlar

Aşağıdakilerle sunulabilen tüm kullanım alanları için genel kartları kullanabilirsiniz:

• En fazla üç satır 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 uygulamasına Google Cüzdan'a ekle düğmesi ekleme hakkında daha fazla bilgi için lütfen Google Cüzdan geliştirici belgelerine bakın.

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

Sınıfları ve nesneleri iletme

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

Tür	Açıklama
Kart sınıfı	Tek bir kart nesnesi için şablon. Bu sınıfın tüm kart nesneleri için ortak olan bilgileri içerir.
Kart nesnesi	Kullanıcı kimliğine özgü bir kart 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 kuruluş hesabı oluşturma
2. Kart verme için hizmet hesabı oluşturma
3. Yeni bir genel kart sınıfı oluşturma
4. Yeni bir kart nesnesi oluşturma
5. Kart kaydetmek için Google Cüzdan'a ekle düğmesi oluşturma
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 veya sonraki sürümler

Hedefler

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

• Google Cüzdan SDK'sını Android uygulamanıza ekleme
• 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şturma

Destek

Codelab'in herhangi bir noktasında takılırsanız google-pay/wallet-android-codelab GitHub deposunda referans için eksiksiz bir çözüm bulabilirsiniz.

2. Kurulum

Bu adımda, demo modunda bir Düzenleyen hesabı oluşturacaksınız. Bu sayede, kullanıcı cüzdanlarına eklenebilecek kart sınıfları ve nesneleri oluşturabilirsiniz. Ardından, bir Google Cloud projesi ve hizmet hesabı oluşturacaksınız. Bunlar, arka uç sunucusuyla aynı şekilde programatik olarak kart sınıfları ve nesneleri oluşturmak için kullanılır. Son olarak, Google Cloud hizmet hesabını Google Cüzdan veren hesabınızdaki kartları yönetmek için yetkilendirirsiniz.

Mobil uygulamalar gibi herkese açık istemcilerde kart sınıfları ve nesneleri oluşturmak mümkündür. Ancak arka uç sunucusu gibi özel bir istemcide kart oluşturmak veya kimliği doğrulanmış ve güvenli isteklerle istemci uygulamalarınızdan kartları getirmek daha güvenlidir.

Google Cüzdan API'si veren kuruluş hesabına kaydolma

Google Cüzdan için kart oluşturup dağıtmak üzere bir Düzenleyen hesabı gerekir. Google Pay ve Cüzdan Konsolu'nu kullanarak kaydolabilirsiniz. Başlangıçta, demo modunda kart oluşturma erişiminiz olur. Bu nedenle, oluşturduğunuz kartları yalnızca belirli test kullanıcıları ekleyebilir. Test kullanıcıları, Google Pay ve Cüzdan Konsolu'nda yönetilebilir.

Demo modu hakkında daha fazla bilgi için Genel kart ön koşulları başlıklı makaleyi inceleyin.

1. Google Pay ve Cüzdan Konsolu'nu açın.
2. Düzenleyen hesabı oluşturmak için ekrandaki talimatları uygulayın.
3. Google Cüzdan API'si'ni seçin.
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şturun'u seçin.
7. Bu codelab'de kullanacağınız e-posta adreslerini ekleyin.

Google Cüzdan API'sini etkinleştirin

1. Google Cloud Console'da oturum açın.
2. Henüz bir Google Cloud projeniz yoksa hemen bir tane 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 hizmet hesabı ve hizmet hesabı anahtarı gerekir. 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ğundan gizli tutulmalıdır.

Bu codelab için mevcut bir hizmet hesabını kullanırken dikkatli olun. Bu hesap, gerekli olmayan diğer kaynaklara erişim iznine sahip olabilir.

Hizmet hesabı oluşturma

1. Google Cloud Console'da Hizmet Hesapları'nı açın.
2. Hizmet hesabınız için 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 (ANAHTARLAR) menüsünü seçin.
3. ANAHTAR EKLE'yi ve 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 hizmet hesabı olarak kimlik doğrulaması yapmak ve bir Google Cloud projesi için farklı API'lere erişmek üzere kullanılır.

1. GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlamak için Google Cloud hizmet hesabı anahtarları dokümanları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çık bir oturumunuz varsa yeni bir oturum başlatmanız gerekebilir).

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Hizmet hesabını yetkilendirin

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

1. Google Pay ve Cüzdan Konsolu'nu açın.
2. Kullanıcılar'ı seçin.
3. Kullanıcı davet et'i seçin.
4. Hizmet hesabının e-posta adresini girin (ö[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 geçiş 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 yeni bir kart oluşturulduğunda, kart sınıfında tanımlanan özellikler kartta yer alır.

Bu codelab sırasında oluşturacağınız kart sınıfı, hem kimlik rozeti hem de puan takipçisi olarak işlev gören bir nesne oluşturmak için genel kartların esnekliğinden yararlanır. Bu sınıftan bir kart nesnesi oluşturulduğunda aşağıdaki grafik gibi görünür.

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

Kart sınıfları doğrudan Google Pay ve Cüzdan Konsolu'nda veya Google Cüzdan API'si kullanılarak oluşturulabilir. Bu codelab'de, API'yi kullanarak Genel kart sınıfını oluşturacaksınız. Bu, özel bir arka uç sunucusunun geçiş sınıfları oluşturmak için kullandığı süreci takip eder.

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

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

2. Klonlanan depoyu terminalinizde veya komut satırı isteminizde 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 ve Cüzdan Konsolu'ndaki veren kuruluş kimliğinizle değiştirin.

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

7. Terminalinizde veya komut satırı isteminizde generic_class.js komut dosyasını çalıştırın.

   node generic_class.js
   

Kodunuz çalıştığında yeni bir kart sınıfı oluşturur ve sınıf kimliğini çıkarır. Sınıf kimliği, kimliği veren kuruluş kimliği ve ardından geliştirici tarafından tanımlanan bir sonekten oluşur. Bu durumda, sonek codelab_class olarak ayarlanır (sınıf kimliği 1234123412341234123.codelab_class'ye benzer). Çıkış günlükleri, Google Cüzdan API'sinden gelen yanıtı da içerir.

4. Projeyi Android Studio'da açın.

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

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

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

1. Modül düzeyindeki Gradle derleme dosyasını (android/app/build.gradle) açın.
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ı kaydetme
4. Dosya'yı, ardından Projeyi Gradle Dosyalarıyla Senkronize Et'i seçin.

5. Google Cüzdan'a ekle düğmesini oluşturma

Bu adımda, Google Cüzdan'a ekle düğmesi oluşturup mevcut bir etkinliğe ekleyeceksiniz. Düğmeyle ilgili öğeler 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 ihtiyacınıza uygun dillerdeki düğme için SVG dosyalarını indirmek üzere Marka kuralları'nı ziyaret edin. Yalnızca desteklenen yapılandırmalar için grafik eklediğinizden emin olun. Android Studio'da Dosya > Yeni > Vektör Öğesi'ni seçerek vektör öğelerini içe aktarabilirsiniz. Sihirbazda Yerel dosya'yı seçin, bir ad girin (ör. add_to_google_wallet_button) ve dosyayı iş istasyonunuzda bulun.

1. Yeni bir düzen dosyası oluşturun: app/src/main/res/layout/add_to_google_wallet_button.xml
2. Yeni düzen dosyasına aşağıdaki içeriği 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ılabilir olup olmadığını kontrol etme

Bir kullanıcı, Google Cüzdan API'sini desteklemeyen bir cihazda uygulamanızı açarsa kartı eklemeye çalıştığında olumsuz bir deneyim yaşayabilir. Kullanıcının cihazı Google Cüzdan API'sini desteklemiyorsa Google Cüzdan'a ekle düğmesini gizlemek olası karışıklıkları önler. API'nin kullanılamamasının çeşitli nedenleri olabilir. Örneğin, Android veya Google Play Hizmetleri sürümlerinin güncel olmaması ya da Google Cüzdan'ın kullanıcının ülkesinde kullanılamaması.

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

Diğer tasarım kalıplarını kullanıyorsanız alana özgü işletme mantığını uygun şekilde yerleştirmeyi düşünün. Örneğin, Model-View-ViewModel (MVVM) kalıbını kullanıyorsanız kullanıcı arayüzüyle ilgili iş mantığını Etkinliğinize veya Parçanıza yerleştirin (ör. UI öğeleri ve etkinlik sonuçları) ve ViewModel'inizdeki operasyonel mantık (ör. istemci oluşturma 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çın.
2. PayClient örneği için sınıf özelliği oluşturma

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

3. PayClient özelliğini onCreate yönteminde oluşturun.

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

4. Google Cüzdan SDK'sının ve API'sinin cihazda kullanılabilir olup olmadığını kontrol eden ve sonucu işleyen bir yöntem oluşturun.

   // 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 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 daha fazla bilgi edinmek için getPayApiAvailabilityStatus yöntemi tarafından döndürülen hatayı ve günlükleri kontrol edin. Söz konusu kullanıcı gelecekte API'yi kullanmaya uygun olabilir.

7. Genel kart nesnesi oluşturma

Düzenleyen kuruluş hesabınız demo modundaysa yalnızca test kullanıcılarınız için kart düzenleyebilirsiniz. Uygulamayı farklı bir e-posta adresiyle çalıştırırsanız kartı cüzdanınıza ekleyemezsiniz.

Google Cüzdan API'nin 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şturmaya yönelik iki akış vardır.

Arka uç sunucusunda kart nesnesi 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 yöntem, kullanıcıların cüzdanlarına eklemeye çalışmadan önce nesnenin mevcut olmasını sağladığı için kullanıcı adaptasyonunun yüksek olduğu durumlarda en iyi sonucu verir.

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

Bu yaklaşımda, kart nesnesi tanımlanır ve arka uç sunucusunda imzalı bir JWT'ye 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 nesnesi oluşturmak için JWT kullanılır. Bu yöntem, kart nesnelerinin oluşturulup kullanılmamasını önlediği için kullanıcıların benimseme oranının değişken veya bilinmediği durumlarda en uygun yöntemdir. Bu yaklaşım, codelab'de kullanılacaktır.

1. backend/generic_pass.js dosyasını açın.
2. issuerId değerini Google Pay ve Cüzdan Konsolu'ndaki veren kuruluş kimliğinizle değiştirin.

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

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

   node generic_pass.js
   

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

Kodunuz çalıştığında yeni bir kart nesnesi tanımlar ve bunu bir JWT'ye yerleştirir. JWT daha sonra, daha önce oluşturduğunuz hizmet hesabı anahtarıyla imzalanır. Bu, kimlik bilgilerinin istemci uygulamasında depolanmaması için Google Cüzdan API'sine yapılan isteğin kimliğini doğrular.

aside Üretim ortamında, JWT'lerin oluşturulması ve istemcilere döndürülmesinden arka uç sisteminiz sorumlu olur. Bu codelab'de, generic_pass.js komut dosyası bu davranışı taklit eder ve istemci uygulamasında kullanmanız için bir jeton "döndürür".

8. Kartı Google Cüzdan'a ekleme

Google Cüzdan API'sinin kullanılabildiğini doğrulayıp imzalı bir JWT oluşturduktan sonra 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 ekleyeceksiniz.

1. app/src/main/CheckoutActivity.kt dosyasını açın.
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 özelliği oluşturun

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

4. Google Cüzdan'a ekle düğmesi için bir dinleyici ayarlama

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

Bir kullanıcı Google Cüzdan'a ekle düğmesini seçtiğinde walletClient.savePassesJwt yöntemi çağrılır. Bu yöntem, kullanıcıdan yeni kart nesnesini Google Cüzdan'ına eklemesini ister.

9. savePassesJwt sonucunu işleme

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çın.
2. Aşağıdaki kodu içerecek şekilde onActivityResult yöntemini 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 başarıyla eklendi
• Kullanıcı iptali
• Beklenmeyen hatalar

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

10. Tebrikler

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

Daha fazla bilgi

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

Kart oluşturma ve üretim erişimi isteğinde bulunma

Üretimde kendi kartlarınızı yayınlamaya hazır olduğunuzda üretim erişimi isteğinde bulunmak ve Android uygulamanızı yetkilendirmek için Google Pay ve Cüzdan Konsolu'na gidin.

Daha fazla bilgi edinmek için Android SDK Ön Koşulları bölümüne bakın.