Mengintegrasikan Google Wallet API untuk mendigitalkan kartu di Android

1. Sebelum memulai

Google Wallet API memungkinkan Anda terlibat dengan pengguna melalui berbagai jenis kartu yang telah ditetapkan sebelumnya: kartu loyalitas, penawaran, kartu voucher, tiket acara, tiket transit, dan boarding pass, yang semuanya dilengkapi dengan kolom dan fitur khusus kasus penggunaan. Namun, kami menyadari bahwa hal ini mungkin tidak sesuai dengan setiap kasus penggunaan. Itulah sebabnya kami membuat jenis kartu umum. Seperti namanya, jenis kartu umum harus digunakan jika kasus penggunaan Anda tidak cocok dengan jenis kartu khusus lainnya. Berikut adalah beberapa contoh kasus penggunaan untuk jenis kartu umum:

• Kartu parkir
• Kartu keanggotaan perpustakaan
• Voucher nilai tersimpan
• Kartu keanggotaan gym
• Kartu asuransi
• Berbagai jenis reservasi

Anda dapat menggunakan kartu umum untuk semua kasus penggunaan yang dapat ditampilkan kepada pengguna dalam bentuk kartu dengan maksimal tiga baris informasi, dengan kode batang opsional dan bagian detail opsional, selama kartu tersebut berada dalam Kebijakan Penggunaan yang Dapat Diterima.

Google Wallet API memungkinkan Anda membuat:

• Class kartu. Anggaplah class sebagai template dengan informasi umum yang dibagikan semua kartu dalam suatu program atau acara. Semua objek kartu termasuk dalam satu class.
• Objek kartu memiliki tujuan konkret yang terkait dengan aktivitas Anda sebagai bisnis dan pengguna Anda (mis.: kartu parkir, kartu keanggotaan gym). Setiap item ini terkait dengan class yang ditentukan sebelumnya, dan mewarisi properti umum darinya.

Codelab ini akan memberikan class yang telah ditentukan sebelumnya, dan memandu Anda dalam menentukan JSON untuk objek kartu, dan menyertakan tombol "Tambahkan ke Google Wallet" ke aplikasi Android Anda, yang akan memungkinkan pengguna untuk menyimpan kartu ke Google Wallet mereka.

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

Prasyarat

• Komputer yang dilengkapi Android Studio.
• Kemampuan untuk membuat dan menjalankan project di Android Studio.
• git diinstal.

Yang Akan Anda Pelajari

• Cara menambahkan Google Wallet SDK ke aplikasi Android.
• Cara memeriksa apakah Wallet API tersedia.
• Cara mengimplementasikan UI, yang memungkinkan pengguna untuk menambahkan kartu ke Google Wallet mereka.

2. Memulai persiapan

Membuat akun penerbit sementara

Untuk membuat kartu bagi pengguna, Anda harus membuat akun penerbit terlebih dahulu, mengaktifkan Wallet API, lalu membuat class, yang semuanya dapat dilakukan melalui Konsol Bisnis Google Pay. Namun, akses ke konsol hanya diberikan setelah proses persetujuan selesai, sehingga untuk codelab ini, kita akan membuat akun penerbit sementara dan class kartu untuk Anda.

Pastikan untuk membuat akun pengujian dengan alamat email yang dapat digunakan dengan perangkat seluler tempat Anda berencana menguji integrasi.

1. Klik Buat akun penerbit sementara dan class contoh.

Catatan: Jangan gunakan akun sementara atau class ini untuk tujuan produksi. Akses ke akun sementara dibatasi sampai tujuh hari.

2. Catat ID penerbit dan ID class, yang akan Anda perlukan di langkah mendatang.

Meng-clone repositori git

Clone repositori git, yang berisi project Android yang akan Anda edit, menggunakan perintah berikut:

git clone -b wallet-lab [e-mail]:google-pay/android-quickstart.git

Membuka di Android Studio

Buka Android Studio, pilih "Open" dari layar selamat datang, lalu pilih folder kotlin dalam repositori yang baru di-clone untuk dibuka sebagai project.

3 Menambahkan Google Wallet SDK ke aplikasi

Project Android berisi aktivitas kosong yang akan segera kami edit, tetapi pertama-tama mari kita tambahkan Google Wallet SDK sebagai dependensi. Di Android Studio, pilih skrip "build.gradle" tingkat modul, lalu tambahkan baris berikut ke bagian dependencies:

dependencies {
    ...
    implementation 'com.google.android.gms:play-services-pay:16.0.3'
}

Setelah diubah, klik tombol Gradle "Sync Project" di kanan atas Android Studio.

4. Menambahkan tombol "Tambahkan ke Google Wallet"

Selanjutnya, Anda akan menambahkan tombol "Tambahkan ke Google Wallet" ke aktivitas. Aset untuk tombol telah ditambahkan ke project, Anda hanya perlu menambahkannya ke file tata letak. Untuk melakukannya, sebaiknya buat tata letak terpisah dengan tombol:

add_to_google_wallet_button.xml

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:clickable="true"
    android:focusable="true"
    android:layout_width="match_parent"
    android:layout_height="48sp"
    android:background="@drawable/add_to_google_wallet_button_background_shape"
    android:contentDescription="@string/add_to_google_wallet_button_content_description">
    <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>

Tampilan tombol akan terlihat seperti berikut:

Jika Anda menambahkan tombol ke aplikasi Anda sendiri, kunjungi halaman panduan tombol dan download file SVG untuk mengetahui tombol dengan tema warna dan 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, beri nama (mis.: add_to_google_wallet_button) dan cari file di drive lokal Anda untuk mengimpornya.

Kemudian, sertakan dalam file tata letak Anda:

<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"/>

5. Memeriksa apakah API tersedia

Sekarang saatnya untuk coding. Buka file tempat Anda akan melakukan panggilan terhadap Google Wallet API di Android Studio (file CheckoutActivity.kt jika Anda menggunakan aplikasi contoh), dan buat instance objek PayClient sebagai anggota class Anda. Objek ini membantu Anda melakukan panggilan terhadap Google Wallet API. Metode getClient menerima konteks class pembuatan instance, dalam hal ini, aktivitas pemanggilan.

private lateinit var walletClient: PayClient

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    walletClient = Pay.getClient(this)
    ...
}

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

Selanjutnya, pastikan aplikasi dan Google Wallet SDK tersedia di perangkat. Buat metode baru di class Anda (mis.: fetchCanUseGoogleWalletApi) untuk menentukan apakah Google Wallet API tersedia, dan kode lainnya untuk bereaksi terhadap hasil dengan menampilkan tombol "Tambahkan ke Google Wallet" jika API tersedia:

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
        }
}

Berbagai alasan mengapa API mungkin tidak tersedia meliputi versi Android atau Layanan Google Play sudah tidak berlaku, atau Google Wallet saat ini tidak tersedia di negara pengguna.

Terakhir, panggil metode fetchCanUseGoogleWalletApi di metode onCreate untuk menentukan apakah Google Wallet API tersedia:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    ...
    fetchCanUseGoogleWalletApi()
}

Sekarang Anda akan melihat tombol "Tambahkan ke Google Wallet" di UI saat menjalankan aplikasi:

Jika tombol "Tambahkan ke Google Wallet" tidak muncul, periksa error yang ditampilkan oleh metode getPayApiAvailabilityStatus dan log untuk mempelajari lebih lanjut. Jika API tidak tersedia, pertimbangkan untuk tidak menampilkan tombol "Tambahkan ke Google Wallet" dan kembali ke metode alternatif untuk menambahkan kartu (mis.: Link JWT). Perhatikan bahwa pengguna yang bersangkutan mungkin memenuhi syarat untuk menggunakan API ini di masa mendatang.

6. Menambahkan kartu ke Google Wallet

Sekarang, setelah memverifikasi bahwa Google Wallet API tersedia, Anda dapat meminta pengguna untuk menambahkan kartu ke Google Wallet mereka. Sebelum melakukannya, luangkan waktu untuk meninjau kartu yang dibuat di workshop ini:

Tata letak ini menggunakan fleksibilitas kartu umum untuk membuat objek yang berfungsi sebagai badge identitas, dan pada saat yang sama, mendukung tantangan yang meminta peserta untuk mengumpulkan poin selama acara berlangsung. Tampilan objek umum akan terlihat seperti berikut:

{
    "id": "999999.d1fa-4cca1...",
    "classId": "999999.a92b-129f...",
    "genericType": "GENERIC_TYPE_UNSPECIFIED",
    "hexBackgroundColor": "#4285f4",
    "logo": { ... },
    "cardTitle": { ... },
    "subheader": { ... },
    "header": { ... },
    "barcode": { ... },
    "heroImage": { ... },
    "textModulesData": []
}

Untuk memasukkan objek, API mengharapkan isi JWT yang belum ditandatangani menggabungkan elemen baru:

{
    "iss": <owner-email-address>,
    "aud": "google",
    "typ": "savetowallet",
    "iat": <unix-time>,
    "origins": [],
    "payload": {
        "genericObjects": [],
        "genericClasses": [],
        ...
    }
}

Gabungkan semuanya (menggunakan nilai yang Anda peroleh sebelumnya saat membuat akun penerbit sementara) dan tetapkan objek yang dihasilkan ke variabel dalam class Anda:

private val issuerEmail = "<insert-your-issuer-email-address>"
private val issuerId = "<insert-your-issuer-id>"
private val passClass = "<insert-your-class-id>"
private val passId = UUID.randomUUID().toString()

private val newObjectJson = """
    {
      "iss": "$issuerEmail",
      "aud": "google",
      "typ": "savetowallet",
      "iat": ${Date().time / 1000L},
      "origins": [],
      "payload": {
        "genericObjects": [
          {
            "id": "$issuerId.$passId",
            "classId": "$passClass",
            "genericType": "GENERIC_TYPE_UNSPECIFIED",
            "hexBackgroundColor": "#4285f4",
            "logo": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/pass_google_logo.jpg"
              }
            },
            "cardTitle": {
              "defaultValue": {
                "language": "en",
                "value": "Google I/O '22  [DEMO ONLY]"
              }
            },
            "subheader": {
              "defaultValue": {
                "language": "en",
                "value": "Attendee"
              }
            },
            "header": {
              "defaultValue": {
                "language": "en",
                "value": "Alex McJacobs"
              }
            },
            "barcode": {
              "type": "QR_CODE",
              "value": "$passId"
            },
            "heroImage": {
              "sourceUri": {
                "uri": "https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg"
              }
            },
            "textModulesData": [
              {
                "header": "POINTS",
                "body": "${Random.nextInt(0, 9999)}",
                "id": "points"
              },
              {
                "header": "CONTACTS",
                "body": "${Random.nextInt(1, 99)}",
                "id": "contacts"
              }
            ]
          }
        ]
      }
    }
    """

Pada bagian definisi class, Anda akan melihat bahwa informasi pada bagian textModulesData direferensikan di class, yang berdasarkan template class-nya, menentukan cara kolom ini ditampilkan dalam kartu yang dihasilkan.

Ini adalah objek pengujian yang dibuat untuk tujuan pembelajaran. Jangan membuat kartu Anda sendiri dari klien publik (mis.: aplikasi seluler). Sebagai gantinya, buat dan masukkan kartu Anda dari klien rahasia (mis.: server backend) atau ambil secara opsional dari aplikasi klien melalui permintaan yang aman dan diautentikasi.

Terakhir, kembali ke metode onCreate dan tambahkan pengendali klik ke tombol "Tambahkan ke Google Wallet" untuk memulai operasi menggunakan metode savePasses di klien:

private val addToGoogleWalletRequestCode = 1000

private lateinit var layout: ActivityCheckoutBinding
private lateinit var addToGoogleWalletButton: View

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Use view binding to access the UI elements
    layout = ActivityCheckoutBinding.inflate(layoutInflater)
    setContentView(layout.root)

    addToGoogleWalletButton = layout.addToGoogleWalletButton.root
    addToGoogleWalletButton.setOnClickListener {
        walletClient.savePasses(newObjectJson, this, addToGoogleWalletRequestCode)
    }

    ...
}

Dengan demikian, Anda telah menentukan JSON untuk objek baru menggunakan ID penerbit dan ID class yang dibuat sebelumnya. Saat pengguna mengklik tombol "Tambahkan ke Google Wallet", payClient.savePasses dipanggil, dan meminta mereka untuk menambahkan objek kartu baru ke Google Wallet:

7. Menangani hasil

Anda hampir selesai. Terakhir, tangani hasil operasi yang berhasil atau tidak. Ganti metode onActivityResult agar berisi kode berikut:

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.
            }

            else -> {
                // Handle unexpected (non-API) exception
            }
        }
    }
}

Dengan kode ini, Anda menangani kartu yang berhasil ditambahkan, pengguna yang membatalkan tindakan, dan juga error yang mungkin terjadi. Lanjutkan dan jalankan aplikasi Anda sekali lagi untuk mengonfirmasi bahwa Anda dapat menambahkan kartu dan menangani hasilnya seperti yang diharapkan.

8 Selamat

Selamat, Anda berhasil mengintegrasikan Google Wallet API di Android.

Pelajari lebih lanjut

Lihat integrasi lengkap di contoh aplikasi di GitHub untuk melihat contoh lengkap.

Mendaftar untuk akun penerbit

Jika sudah siap untuk menerbitkan kartu Anda ke tahap produksi, buka Konsol Google Pay & Wallet untuk meminta akses ke Google Wallet API dan memberi otorisasi pada aplikasi Android Anda untuk melakukan panggilan terhadap API. Lihat dokumentasi untuk mempelajari lebih lanjut.