Membuat kartu di Android menggunakan Google Wallet API

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 menciptakan 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
• Pemesanan

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

• Hingga tiga baris informasi
• (Opsional) Grafik kode batang
• (Opsional) Bagian detail

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

Semua class dan objek kartu harus mematuhi Kebijakan Penggunaan yang Dapat Diterima.

Class dan objek kartu

Google Wallet API mengekspos metode untuk membuat hal berikut:

Jenis	Deskripsi
Kelas kartu	Template untuk objek kartu individual. Berisi informasi 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. Buat class Kartu generik baru
4. Membuat objek kartu baru
5. Membuat tombol Tambahkan ke Google Wallet untuk menyimpan kartu pas
6. Menampilkan tombol di aplikasi Android Anda
7. Menangani hasil penyimpanan kartu

Prasyarat

• Android Studio
• Git
• Akun Google dengan akses ke konsol Google Cloud
• Node.js versi 10 atau yang lebih baru

Tujuan

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

• Menambahkan Google Wallet SDK ke aplikasi Android Anda
• 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. Ini akan digunakan untuk membuat class dan objek kartu secara terprogram dengan cara yang sama seperti server backend. Terakhir, Anda akan memberikan otorisasi kepada akun layanan Google Cloud untuk mengelola kartu di akun penerbit Google Wallet Anda.

Anda dapat membuat class dan objek kartu dalam klien publik seperti aplikasi seluler. Namun, lebih aman untuk membuat kartu di klien pribadi seperti server backend atau dengan mengambilnya dari aplikasi klien melalui permintaan yang aman dan diautentikasi.

Mendaftar untuk 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 mengetahui informasi selengkapnya tentang mode demo, lihat Prasyarat kartu generik.

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

Aktifkan Google Wallet API

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

Membuat kunci dan akun layanan

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 jaga kerahasiaannya.

Berhati-hatilah saat menggunakan akun layanan yang ada untuk codelab ini, karena akun tersebut mungkin memiliki izin ke resource lain yang tidak diperlukan.

Membuat akun layanan

1. Di konsol Google Cloud, buka Service Accounts
2. Masukkan nama, ID, dan deskripsi untuk akun layanan Anda
3. Pilih BUAT DAN LANJUTKAN
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 berbagai API untuk project Google Cloud.

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

   echo $GOOGLE_APPLICATION_CREDENTIALS
   

Memberikan otorisasi akun layanan

Terakhir, Anda harus mengizinkan 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, [e-mail])
5. Pilih Developer atau Admin dari menu drop-down Tingkat akses
6. Pilih Undang.

3. Membuat class kartu Generic

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

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

Grafik ini mengilustrasikan sebagian kecil properti yang dapat ditetapkan pada kartu. Lihat Template kartu umum untuk melihat pengaruh berbagai properti kartu terhadap pengalaman pengguna.

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

1. Buat 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 Anda
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-line 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 kelas 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 Buka
3. Pilih direktori android di repositori
4. Pilih Buka.

Menambahkan Google Wallet SDK ke aplikasi Anda

1. Buka file build Gradle level modul (android/app/build.gradle)
2. Tambahkan 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. Simpan 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.

Jika Anda menambahkan tombol ke aplikasi Anda sendiri, buka Panduan merek untuk mendownload file SVG tombol dengan bahasa yang sesuai dengan kebutuhan Anda. Pastikan hanya menyertakan grafik untuk konfigurasi yang didukung. Anda dapat mengimpor aset vektor di Android Studio pada bagian File > New > Vector Asset. Pilih Local file di wizard, masukkan nama (misalnya add_to_google_wallet_button), lalu cari file di workstation Anda.

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. Periksa 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 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 ya, tombol akan dirender dalam aktivitas. Jika tidak, tombol akan disembunyikan.

Pertimbangkan untuk menempatkan logika bisnis khusus domain dengan tepat jika Anda menggunakan pola desain lain. Misalnya, jika Anda menggunakan pola Model-View-ViewModel (MVVM), tempatkan logika bisnis terkait UI di Aktivitas atau Fragmen Anda (misalnya: Elemen UI dan hasil aktivitas), dan logika operasional di ViewModel Anda (misalnya: pembuatan instance klien dan pemicu panggilan jaringan).

1. Open file CheckoutActivity.kt di app/src/main/java/com/google/android/gms/samples/wallet/activity/
2. Buat 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 di 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.

Jika tombol Tambahkan ke Google Wallet tidak muncul, periksa error yang ditampilkan oleh metode getPayApiAvailabilityStatus dan log untuk mempelajari lebih lanjut. Pengguna yang bersangkutan mungkin memenuhi syarat untuk menggunakan API ini di masa mendatang.

7. Membuat objek Kartu umum

Jika akun penerbit Anda dalam mode demo, Anda hanya dapat menerbitkan kartu untuk pengguna pengujian. Jika menjalankan aplikasi menggunakan alamat email yang berbeda, Anda tidak akan dapat menambahkan kartu ke dompet Anda.

Sekarang, setelah memverifikasi bahwa Google Wallet API tersedia, Anda dapat membuat kartu dan meminta pengguna untuk menambahkannya ke wallet mereka. Ada dua alur untuk membuat objek kartu untuk pengguna.

Buat objek kartu di server backend

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

Membuat objek kartu saat pengguna menambahkannya ke dompet mereka

Dalam pendekatan ini, objek kartu didefinisikan dan dienkode ke dalam JWT bertanda tangan 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. Setelan ini paling cocok untuk kasus ketika adopsi pengguna bervariasi 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 Anda

Saat kode Anda berjalan, kode tersebut 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.

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

8. Menambahkan kartu ke Google Wallet

Sekarang, setelah memverifikasi bahwa Google Wallet API tersedia dan telah membuat JWT yang ditandatangani, Anda dapat meminta pengguna untuk menambahkan kartu ke wallet mereka. Pada langkah ini, Anda akan menambahkan pemroses ke tombol Tambahkan ke Google Wallet yang menggunakan Google Wallet API untuk menyimpan kartu di Wallet 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. Buat 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.root
   
   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

Selamat, Anda 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.