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

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

Bu codelab hakkında

subjectSon güncelleme Oca 19, 2023
account_circleYazan: Nick Alteen

1. Giriş

Genel Bakış

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

Ancak bu yöntemler her kullanım alanına uygun olmayabilir. Daha özelleştirilmiş bir deneyim oluşturmak için genel geçiş türünü kullanabilirsiniz. Genel geçiş türü için bazı örnek kullanım alanları şunlardır:

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

Genel kartları aşağıdakilerle sunulabilecek tüm kullanım alanları için kullanabilirsiniz:

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

Google Cüzdan'a ekleme hazırlama akışını gösteren Android cihaz

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

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ıfa ait tüm geçiş nesnelerine ortak bilgileri içerir.

Kart nesnesi

Kullanıcı kimliğine özgü bir 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 kart veren hesabı oluşturma
  2. Kart çıkarmak için hizmet hesabı oluşturma
  3. Yeni bir genel kart sınıfı oluşturma
  4. Yeni bir geçiş 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

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 aşamasında takılırsanız google-pay/wallet-android-codelab GitHub deposunda referans olarak kullanabileceğiniz eksiksiz bir çözüm yer alır.

2. Kurulum

Bu adımda, demo modunda bir Issuer 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şturun. Bunlar, arka uç sunucusuyla aynı şekilde programlı olarak geçiş sınıfları ve nesneleri oluşturmak için kullanılır. Son olarak, Google Cloud hizmet hesabını Google Cüzdan sağlayıcı hesabınızdaki kartları yönetmek üzere yetkilendirin.

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

Google Cüzdan için kart oluşturmak ve dağıtmak amacıyla bir kart veren hesabı gerekir. Google Pay ve Cüzdan Konsolu'nu kullanarak kaydolabilirsiniz. İlk olarak, demo modunda kart oluşturma erişiminiz olacaktır. Bu durumda, 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 geçiş ön koşulları başlıklı makaleyi inceleyin.

  1. Google Pay ve Cüzdan Konsolu'nu açın.
  2. Kart veren 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ştur'u seçin.
  7. Bu kod laboratuvarında kullanacağınız e-posta adreslerini ekleyin

Google Cüzdan API'sini etkinleştirme

  1. Google Cloud Console'da oturum açın.
  2. Henüz 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 (Passes API için Google Pay 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ı 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 tutun.

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 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. Bu konumu hatırladığınızdan emin olun.

GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlama

GOOGLE_APPLICATION_CREDENTIALS ortam değişkeni, Google SDK'ları tarafından hizmet hesabı olarak kimlik doğrulamak ve 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ı belgelerindeki talimatları uygulayın.
  2. Ortam değişkeninin yeni bir terminal (MacOS/Linux) veya komut satırı (Windows) oturumunda ayarlandığını doğrulayın (Açık bir oturumunuz varsa 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önetmek üzere 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 (ör. test-svc@myproject.iam.gserviceaccount.com)
  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 kapsamlı kart sınıfı oluşturma

Bu adımda, kartınızın temel sınıfını oluşturacaksınız. Bir kullanıcı için her yeni geçiş oluşturulduğunda, geçiş sınıfında tanımlanan özellikler devralınır.

Bu codelab sırasında oluşturacağınız geçiş kartı sınıfı, hem kimlik rozeti hem de yarışma puanı izleyici olarak çalışan bir nesne oluşturmak için genel geçiş kartlarının esnekliğini kullanır. Bu sınıftan bir geçiş nesnesi oluşturulduğunda aşağıdaki grafik gibi görünür.

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 Generic pass sınıfını oluşturacaksınız. Bu işlem, özel bir arka uç sunucusunun geçiş sınıfları oluşturmak için kullanacağı işleme benzer.

  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. Klonlanmış deposu 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 Issuer ID ile 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ırıldığında yeni bir geçiş sınıfı oluşturur ve sınıf kimliğini döndürür. Sınıf kimliği, geliştirici tarafından tanımlanan bir son ek içeren, veren kuruluş kimliğinden oluşur. Bu durumda son ek codelab_class olarak ayarlanır (sınıf kimliği 1234123412341234123.codelab_class'a benzer). Çıkış günlükleri, Google Cüzdan API'sinden gelen yanıtı da içerir.

4. Projeyi Android Studio'da açma

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

  1. Android Studio'yu açma
  2. Dosya'yı ve ardından 'ı seçin.
  3. Depodaki android dizinini seçin
  4. 'ı 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 ekleme
    // 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ı ve ardından Projeyi Gradle Dosyalarıyla Senkronize Et'i seçin.

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

Bu adımda, bir Google Cüzdan'a ekle düğmesi oluşturup mevcut bir etkinliğe ekleyeceksiniz. Düğmenin öğeleri projeye zaten eklenmiş. Düğmeyi eklemek için ayrı bir düzen dosyası oluşturursunuz. Eklenen düğme aşağıdaki gibi görünür.

Google Cüzdan'a ekle düğmesi

  1. Yeni bir sayfa düzeni 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üzeni 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&#39;sinin kullanılıp kullanılamadığını kontrol etme

Kullanıcılar uygulamanızı Google Cüzdan API'yi desteklemeyen bir cihazda açarsa geçiş eklemeye çalışırken olumsuz bir deneyim yaşayabilirler. Kullanıcının cihazı Google Cüzdan API'sini desteklemiyorsa Google Cüzdan'a ekle düğmesi gizlenerek olası karışıklıklar önlenebilir. API'nin kullanılamamasının çeşitli nedenleri vardır. Ö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ılıp kullanılamadığını kontrol eden bir mantık ekleyeceksiniz. Bu durumda düğme etkinlikte oluşturulur. Aksi takdirde düğme gizlenir.

  1. CheckoutActivity.kt dosyasını app/src/main/java/com/google/android/gms/samples/wallet/activity/'da açma
  2. PayClient örneği için sınıf mülkü oluşturma
    // TODO: Create a client to interact with the Google Wallet API
    private lateinit var walletClient: PayClient
  3. onCreate yönteminde PayClient mülkünü örneklendirin
    // TODO: Instantiate the client
    walletClient = Pay.getClient(this)
  4. Google Cüzdan SDK'sının ve API'sinin cihazda kullanılıp kullanılamadığı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&#39;a ekle düğmesi artık uygulama etkinliğinde gösteriliyor

7. Genel geçiş nesnesi oluşturma

Google Cüzdan API'sinin kullanılabilir olduğunu doğruladığınıza göre, kart oluşturabilir ve kullanıcınızdan kartı cüzdanına eklemesini isteyebilirsiniz. Kullanıcılar için geçiş nesnesi oluşturmanın iki yolu vardır.

Arka uç sunucuda 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 yöntem, kullanıcının cüzdanına eklemeye çalışmadan önce öğenin varlığını doğruladığından, kullanıcıların benimsemesinin yüksek olduğu durumlar için en uygun yöntemdir.

Kullanıcı cüzdanına eklediğinde geçiş kartı nesnesini oluşturun

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

  1. backend/generic_pass.js dosyasını açma
  2. issuerId değerini Google Pay ve Cüzdan Konsolu'ndaki Issuer ID ile 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ırıldığında yeni bir geçiş nesnesi tanımlar ve bu nesneyi JWT'ye yerleştirir. Ardından JWT, daha önce oluşturduğunuz hizmet hesabı anahtarıyla imzalanır. Bu işlem, kimlik bilgilerinin istemci uygulamasında saklanmaması için Google Cüzdan API'sine gönderilen isteğin kimliğini doğrular.

aside Üretim ortamında, JWT'leri oluşturmaktan ve istemcilere döndürmekten arka uç sisteminiz sorumludur. Bu codelab'de generic_pass.js komut dosyası bu davranışı taklit eder ve istemci uygulamasında kullanabileceğiniz bir jeton "döner".

8. Kartı Google Cüzdan&#39;a ekleme

Google Cüzdan API'sinin kullanılabilir olduğunu doğrulayıp imzalı bir JWT oluşturduktan sonra kullanıcıdan kartı cüzdanına eklemesini isteyebilirsiniz. Bu adımda, Google Cüzdan'a Ekle düğmesine, kartın kullanıcının cüzdanına kaydedilmesi için Google Cüzdan API'sini kullanan bir dinleyici eklersiniz.

  1. app/src/main/CheckoutActivity.kt dosyasını açma
  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 saklamak 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.

    addToGoogleWalletButton.setOnClickListener {
      walletClient.savePassesJwt(token, this, addToGoogleWalletRequestCode)
    }

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çma
  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ıyla tamamlandı
  • Kullanıcı tarafından iptal
  • Beklenmedik hatalar

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

10. Tebrikler

Örnek genel geçiş nesnesi.

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

Daha fazla bilgi

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

Kart oluşturma ve üretim erişimi isteme

Üretimde kendi kartlarınızı vermeye 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 için Android SDK Önkoşulları'na bakın.