Membuat kartu di Android menggunakan Google Wallet API

Membuat kartu di Android menggunakan Google Wallet API

Tentang codelab ini

subjectTerakhir diperbarui Jan 19, 2023
account_circleDitulis oleh Nick Alteen

1. Pengantar

Ringkasan

Google Wallet API memungkinkan Anda berinteraksi dengan pengguna melalui berbagai jenis kartu: kartu loyalitas, penawaran, kartu voucher, tiket acara, tiket transportasi umum, boarding pass, dan lainnya. Setiap jenis kartu, atau class kartu, dilengkapi dengan kolom dan fitur khusus kasus penggunaan untuk meningkatkan pengalaman pengguna.

Namun, hal ini mungkin tidak sesuai dengan setiap kasus penggunaan. Untuk membuat pengalaman yang lebih disesuaikan, Anda dapat menggunakan jenis kartu umum. Berikut adalah beberapa contoh kasus penggunaan untuk jenis kartu umum:

  • Kartu parkir
  • Kartu keanggotaan perpustakaan
  • Voucher nilai tersimpan
  • Kartu keanggotaan gym
  • Reservasi

Anda dapat menggunakan kartu umum untuk kasus penggunaan apa pun yang dapat ditampilkan dengan:

  • Maksimal tiga baris informasi
  • (Opsional) Gambar kode batang
  • (Opsional) Bagian detail

Perangkat yang didukung Android yang menunjukkan alur penyediaan Tambahkan ke Google Wallet

Untuk informasi Google Wallet API selengkapnya, atau menambahkan tombol Tambahkan ke Google Wallet ke aplikasi Android, lihat dokumentasi developer Google Wallet.

Meneruskan class dan objek

Google Wallet API mengekspos metode untuk membuat hal berikut:

Jenis

Deskripsi

Class kartu

Template untuk setiap objek kartu. Class ini berisi informasi yang umum untuk semua objek kartu yang termasuk dalam class ini.

Objek kartu

Instance class kartu yang unik untuk ID pengguna.

Tentang codelab ini

Dalam codelab ini, Anda akan menyelesaikan tugas-tugas berikut.

  1. Membuat akun penerbit baru dalam mode demo
  2. Membuat akun layanan untuk menerbitkan kartu
  3. Membuat class kartu Umum baru
  4. Membuat objek kartu baru
  5. Membuat tombol Tambahkan ke Google Wallet untuk menyimpan kartu
  6. Menampilkan tombol di aplikasi Android
  7. Menangani hasil penyimpanan kartu

Prasyarat

Tujuan

Setelah menyelesaikan codelab ini, Anda akan dapat melakukan hal berikut:

  • Menambahkan Google Wallet SDK ke aplikasi Android
  • Memeriksa apakah Google Wallet API tersedia di perangkat yang didukung Android
  • Membuat tombol Tambahkan ke Google Wallet

Dukungan

Jika Anda mengalami masalah di bagian mana pun dalam codelab, repositori GitHub google-pay/wallet-android-codelab berisi solusi lengkap untuk referensi.

2. Penyiapan

Pada langkah ini, Anda akan membuat akun Penerbit dalam mode demo. Hal ini akan memungkinkan Anda membuat class dan objek kartu yang dapat ditambahkan ke dompet pengguna. Selanjutnya, Anda akan membuat project dan akun layanan Google Cloud. Class dan objek ini akan digunakan untuk membuat class dan objek kartu secara terprogram dengan cara yang sama seperti server backend. Terakhir, Anda akan memberikan otorisasi ke akun layanan Google Cloud untuk mengelola kartu di akun penerbit Google Wallet Anda.

Mendaftar ke akun penerbit Google Wallet API

Akun Penerbit diperlukan untuk membuat dan mendistribusikan kartu untuk Google Wallet. Anda dapat mendaftar menggunakan Konsol Google Pay & Wallet. Awalnya, Anda akan memiliki akses untuk membuat kartu dalam mode demo. Artinya, hanya pengguna pengujian tertentu yang dapat menambahkan kartu yang Anda buat. Pengguna pengujian dapat dikelola di Konsol Google Pay & Wallet.

Untuk informasi selengkapnya tentang mode demo, lihat Prasyarat kartu umum.

  1. Buka Konsol Google Pay & Wallet
  2. Ikuti petunjuk di layar untuk membuat akun Penerbit
  3. Pilih Google Wallet API
  4. Konfirmasi bahwa Anda memahami persyaratan layanan dan kebijakan privasi
  5. Salin nilai ID Penerbit ke editor teks atau lokasi lain
  6. Di tab Kelola, pilih Siapkan akun pengujian
  7. Tambahkan alamat email yang akan Anda gunakan dalam codelab ini

Mengaktifkan Google Wallet API

  1. Login ke konsol Google Cloud
  2. Jika Anda belum memiliki project Google Cloud, buat sekarang (lihat Membuat dan mengelola project untuk mengetahui informasi selengkapnya)
  3. Mengaktifkan Google Wallet API (juga disebut sebagai Google Pay for Passes API) untuk project Anda

Membuat akun layanan dan kunci

Akun layanan dan kunci akun layanan diperlukan untuk memanggil Google Wallet API. Akun layanan adalah identitas yang memanggil Google Wallet API. Kunci akun layanan berisi kunci pribadi yang mengidentifikasi aplikasi Anda sebagai akun layanan. Kunci ini bersifat sensitif, jadi pastikan kerahasiaannya terjaga.

Membuat akun layanan

  1. Di konsol Google Cloud, buka Akun Layanan
  2. Masukkan nama, ID, dan deskripsi untuk akun layanan Anda
  3. Pilih CREATE AND CONTINUE
  4. Pilih SELESAI

Membuat kunci akun layanan

  1. Pilih akun layanan Anda
  2. Pilih menu KEYS
  3. Pilih ADD KEY, lalu Create new key
  4. Pilih jenis kunci JSON
  5. Pilih BUAT

Anda akan diminta untuk menyimpan file kunci ke workstation lokal. Pastikan untuk mengingat lokasinya.

Menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS

Variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS digunakan oleh Google SDK untuk mengautentikasi sebagai akun layanan dan mengakses API yang berbeda untuk project Google Cloud.

  1. Ikuti petunjuk dalam dokumentasi Kunci akun layanan Google Cloud untuk menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS
  2. Pastikan variabel lingkungan ditetapkan di sesi terminal (MacOS/Linux) atau command line (Windows) baru (Anda mungkin perlu memulai sesi baru jika sudah membukanya)
    echo $GOOGLE_APPLICATION_CREDENTIALS

Memberikan otorisasi ke akun layanan

Terakhir, Anda harus memberikan otorisasi kepada akun layanan untuk mengelola kartu Google Wallet.

  1. Buka Konsol Google Pay & Wallet
  2. Pilih Pengguna
  3. Pilih Undang pengguna
  4. Masukkan alamat email akun layanan (misalnya, test-svc@myproject.iam.gserviceaccount.com)
  5. Pilih Developer atau Admin dari menu drop-down Tingkat akses
  6. Pilih Undang

3. Membuat class kartu Umum

Pada langkah ini, Anda akan membuat class dasar untuk kartu. Setiap kali kartu baru dibuat untuk pengguna, kartu tersebut akan mewarisi properti yang ditentukan di class kartu.

Class kartu yang akan Anda buat selama codelab ini menggunakan fleksibilitas kartu Generik untuk membuat objek yang berfungsi sebagai badge identitas dan pelacak poin tantangan. Saat objek kartu dibuat dari class ini, objek tersebut akan terlihat seperti grafik berikut.

Class kartu dapat dibuat langsung di Konsol Google Pay & Wallet atau menggunakan Google Wallet API. Dalam codelab ini, Anda akan membuat class kartu Umum menggunakan API. Hal ini mengikuti proses yang akan digunakan server backend pribadi untuk membuat class kartu.

  1. Clone repositori GitHub google-pay/wallet-android-codelab ke workstation lokal Anda
    git clone https://github.com/google-pay/wallet-android-codelab.git
  2. Buka repositori yang di-clone di terminal atau command line prompt
  3. Buka direktori backend (skrip ini meniru tindakan server backend)
    cd backend
  4. Menginstal dependensi Node.js
    npm install .
  5. Di direktori backend, buka generic_class.js
  6. Ganti nilai issuerId dengan ID Penerbit Anda dari Konsol Google Pay & Wallet
    // TODO: Define Issuer ID
    let issuerId = 'ISSUER_ID';
  7. Di terminal atau command prompt, jalankan skrip generic_class.js
    node generic_class.js

Saat kode Anda berjalan, kode tersebut akan membuat class kartu baru dan menampilkan ID class. ID class terdiri dari ID penerbit yang diikuti dengan akhiran yang ditentukan developer. Dalam hal ini, akhiran ditetapkan ke codelab_class (ID class akan terlihat mirip dengan 1234123412341234123.codelab_class). Log output juga akan menyertakan respons dari Google Wallet API.

4. Membuka project di Android Studio

Repositori GitHub yang Anda clone berisi project Android dengan aktivitas kosong. Pada langkah ini, Anda akan mengedit aktivitas ini untuk menyertakan tombol Tambahkan ke Google Wallet di halaman produk.

  1. Membuka Android Studio
  2. Pilih File, lalu Open
  3. Pilih direktori android di repositori
  4. Pilih Buka

Menambahkan Google Wallet SDK ke aplikasi

  1. Buka file build Gradle level modul (android/app/build.gradle)
  2. Menambahkan Google Wallet SDK ke bagian dependencies
    // 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. Menyimpan file
  4. Pilih File, lalu Sync Project with Gradle Files

5. Membuat tombol Tambahkan ke Google Wallet

Pada langkah ini, Anda akan membuat tombol Tambahkan ke Google Wallet dan menambahkannya ke aktivitas yang ada. Aset untuk tombol telah disertakan dalam project. Untuk menyertakan tombol, Anda akan membuat file tata letak terpisah. Setelah ditambahkan, tombol akan terlihat seperti berikut.

Tombol Tambahkan ke Google Wallet

  1. Buat file tata letak baru: app/src/main/res/layout/add_to_google_wallet_button.xml
  2. Tambahkan konten berikut ke file tata letak baru
    <?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. Sertakan tata letak add_to_google_wallet_button.xml dalam file tata letak aktivitas checkout (app/src/main/res/layout/activity_checkout.xml)
    <!--
        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. Memeriksa apakah Google Wallet API tersedia

Jika pengguna membuka aplikasi Anda di perangkat yang tidak mendukung Google Wallet API, hal ini dapat menimbulkan pengalaman negatif saat mereka mencoba menambahkan kartu. Jika perangkat pengguna tidak mendukung Google Wallet API, menyembunyikan tombol Tambahkan ke Google Wallet akan menghindari potensi kebingungan. Ada berbagai alasan mengapa API mungkin tidak tersedia, seperti versi Android atau Layanan Google Play yang sudah tidak berlaku atau Google Wallet tidak tersedia di negara pengguna.

Pada langkah ini, Anda akan menambahkan logika ke aplikasi yang memeriksa apakah Google Wallet API tersedia di perangkat. Jika demikian, tombol akan dirender dalam aktivitas. Jika tidak, tombol akan disembunyikan.

  1. Open file CheckoutActivity.kt di app/src/main/java/com/google/android/gms/samples/wallet/activity/
  2. Membuat properti class untuk instance PayClient
    // TODO: Create a client to interact with the Google Wallet API
    private lateinit var walletClient: PayClient
  3. Buat instance properti PayClient dalam metode onCreate
    // TODO: Instantiate the client
    walletClient = Pay.getClient(this)
  4. Buat metode yang memeriksa apakah SDK dan API Google Wallet tersedia di perangkat dan tangani hasilnya
    // 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. Panggil metode fetchCanUseGoogleWalletApi dalam metode onCreate untuk memeriksa apakah Google Wallet API tersedia
    // TODO: Check if the Google Wallet API is available
    fetchCanUseGoogleWalletApi()

Saat menjalankan aplikasi, Anda akan melihat tombol Tambahkan ke Google Wallet di UI.

Tombol Tambahkan ke Google Wallet kini muncul di aktivitas aplikasi

7. Membuat objek kartu Umum

Setelah memverifikasi bahwa Google Wallet API tersedia, Anda dapat membuat kartu dan meminta pengguna untuk menambahkannya ke dompet mereka. Ada dua alur untuk membuat objek kartu bagi pengguna.

Membuat objek kartu di server backend

Dalam pendekatan ini, objek kartu dibuat di server backend dan ditampilkan ke aplikasi klien sebagai JWT yang ditandatangani. Hal ini paling cocok untuk kasus saat adopsi pengguna tinggi, karena memastikan objek ada sebelum pengguna mencoba menambahkannya ke dompet.

Membuat objek kartu saat pengguna menambahkannya ke dompet

Dalam pendekatan ini, objek kartu ditentukan dan dienkode menjadi JWT yang ditandatangani di server backend. Tombol Tambahkan ke Google Wallet kemudian dirender di aplikasi klien yang mereferensikan JWT. Saat pengguna memilih tombol, JWT digunakan untuk membuat objek kartu. Hal ini paling sesuai untuk kasus saat adopsi pengguna bersifat variabel atau tidak diketahui, karena mencegah objek kartu dibuat dan tidak digunakan. Pendekatan ini akan digunakan dalam codelab.

  1. Buka file backend/generic_pass.js.
  2. Ganti nilai issuerId dengan ID Penerbit Anda dari Konsol Google Pay & Wallet
    // TODO: Define Issuer ID
    let issuerId = 'ISSUER_ID';
  3. Di terminal atau command line prompt, jalankan file generic_pass.js
    node generic_pass.js
  4. Salin token output ke papan klip atau editor teks

Saat berjalan, kode Anda akan menentukan objek kartu baru dan menyematkannya dalam JWT. JWT kemudian ditandatangani oleh kunci akun layanan yang Anda buat sebelumnya. Tindakan ini mengautentikasi permintaan ke Google Wallet API sehingga kredensial tidak perlu disimpan di aplikasi klien.

Di lingkungan produksi, sistem backend Anda akan bertanggung jawab untuk membuat JWT dan menampilkannya kepada klien. Dalam codelab ini, skrip generic_pass.js mengemulasi perilaku ini dan "menampilkan" token untuk Anda gunakan di aplikasi klien.

8. Menambahkan kartu ke Google Wallet

Setelah memverifikasi bahwa Google Wallet API tersedia dan telah membuat JWT yang ditandatangani, Anda dapat meminta pengguna untuk menambahkan kartu ke dompet mereka. Pada langkah ini, Anda akan menambahkan pemroses ke tombol Tambahkan ke Google Wallet yang menggunakan Google Wallet API untuk menyimpan kartu di dompet pengguna.

  1. Buka file app/src/main/CheckoutActivity.kt.
  2. Ganti nilai token dengan JWT yang Anda buat sebelumnya
    // TODO: Save the JWT from the backend "response"
    private val token = "TOKEN"
  3. Membuat properti class untuk menyimpan kode permintaan
    // TODO: Add a request code for the save operation
    private val addToGoogleWalletRequestCode = 1000
  4. Menetapkan pemroses untuk tombol Tambahkan ke Google Wallet
    // TODO: Set an on-click listener on the "Add to Google Wallet" button
    addToGoogleWalletButton = layout.addToGoogleWalletButton.

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

Saat pengguna memilih tombol Tambahkan ke Google Wallet, metode walletClient.savePassesJwt akan dipanggil. Metode ini meminta pengguna untuk menambahkan objek kartu baru ke Google Wallet mereka.

9. Menangani hasil savePassesJwt

Pada langkah terakhir codelab ini, Anda akan mengonfigurasi aplikasi untuk menangani hasil operasi walletClient.savePassesJwt.

  1. Buka file app/src/main/CheckoutActivity.kt.
  2. Ganti metode onActivityResult agar berisi kode berikut
    // 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
          }
        }
      }
    }

Sekarang aplikasi Anda dapat menangani skenario berikut:

  • Penambahan kartu berhasil
  • Pembatalan pengguna
  • Error tak terduga

Jalankan aplikasi Anda untuk mengonfirmasi bahwa Anda dapat menambahkan kartu dan menangani hasilnya seperti yang diharapkan.

10. Selamat

Contoh objek kartu Umum.

Selamat, Anda telah berhasil mengintegrasikan Google Wallet API di Android.

Pelajari lebih lanjut

Lihat integrasi lengkap di repositori GitHub google-pay/wallet-android-codelab.

Membuat kartu dan meminta akses produksi

Jika sudah siap untuk menerbitkan kartu Anda ke tahap produksi, buka Konsol Google Pay & Wallet untuk meminta akses produksi dan memberi otorisasi pada aplikasi Android Anda.

Lihat Prasyarat Android SDK untuk mempelajari lebih lanjut.