Menyesuaikan Kartu Google Wallet

Google Wallet menawarkan alat canggih untuk menyesuaikan tampilan dan tata letak kartu pas apa pun, mulai dari Tiket Acara dan Boarding Pass hingga Kartu Voucher dan Loyalitas. Panduan ini memberikan ringkasan komprehensif tentang cara menyesuaikan pengalaman pengguna dengan menentukan struktur kartu dan menampilkan informasi dinamis yang spesifik per pengguna.

Sebelum memulai, pastikan untuk melihat dokumentasi referensi REST API khusus untuk jenis kartu Anda guna melihat daftar lengkap kolom yang tersedia.

• Loyalitas
• Penawaran
• Kartu Voucher
• Tiket Acara
• Boarding Pass
• Tiket QR

Fondasi: cardTemplateOverride

Alat utama untuk menyesuaikan tata letak kartu adalah objek classTemplateInfo.cardTemplateOverride, yang Anda tentukan dalam resource Class kartu (misalnya, EventTicketClass, LoyaltyClass). Objek ini memungkinkan Anda menyusun kartu dengan menentukan baris dan item di dalamnya, sehingga Anda dapat mengontrol cara informasi ditampilkan.

Anda dapat mereferensikan data dari resource Class (untuk informasi yang dibagikan kepada semua pengguna) dan resource Object (untuk detail khusus pengguna).

1. Menyesuaikan dengan Kolom Wallet Bawaan

Kolom bawaan adalah properti standar yang tersedia di Google Wallet API untuk jenis kartu tertentu. Kolom ini memiliki nama tertentu dan dirender oleh Wallet secara konsisten. Contohnya mencakup kode batang, nama acara, nomor penerbangan, atau saldo kartu voucher.

Dengan mereferensikan fieldPath kolom bawaan ini, Anda dapat menyusunnya di mana saja pada kartu Anda.

Contoh: Menampilkan Detail Khusus Kartu dan Kode Batang

Contoh kartu ini memiliki "Baris atas" dan 3 kolom data di dalam baris ke-2. Item pertama menampilkan nilai spesifik pengguna dari Object seperti poin atau nomor kursi khusus untuk pengguna. Item kedua menampilkan detail dari Class seperti nama acara atau tingkat program loyalitas, dan item ketiga menampilkan nilai spesifik pengguna dari Object seperti poin sekunder atau nomor bagian / pelatih.

Definisi Class:

...
"classTemplateInfo": {
      "cardTemplateOverride": {
        "cardRowTemplateInfos": [
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                    "fieldPath": "object.accountName",
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.balance"
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.loyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.loyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "class.rewardsTierLabel"
                    },
                    {
                      "fieldPath": "class.rewardsTier"
                    }
                  ]
                }
              }
            }
          },
        ]
      }
    }
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",
...

Definisi Objek

...
"accountName": "Camille Walsh",
"loyaltyPoints": {
    "balance": {
        "string": "1500"
    },
    "label": "Points"
},
"secondaryLoyaltyPoints" : {
    "balance": {
        "money": {
            "micros" : "35050000",
            "currencyCode": "USD",
        }
    },
    "label": "Balance"
}
...

Catatan: Nilai fieldPath bergantung pada jenis kartu. Misalnya, untuk menampilkan nama acara, Anda akan menggunakan "fieldPath": "class.eventName.defaultValue.value". Lihat dokumentasi referensi Class dan Object tertentu untuk mengetahui daftar lengkap kolom yang tersedia.

Memformat Kolom Tanggal dan Waktu

Untuk kolom tanggal atau waktu apa pun di kartu yang didukung, Anda dapat menentukan format kustom menggunakan properti dateFormat. Dengan begitu, Anda dapat mengontrol cara tanggal ditampilkan di kartu pas, seperti hanya menampilkan waktu, tanggal dan waktu lengkap, atau hanya tanggal. Jika dateFormat tidak ditentukan, format default akan digunakan.

"fields": [
  {
    "fieldPath": "object.validTimeInterval.start.date",
    "dateFormat": "DATE_ONLY"
  }
]

Untuk mengetahui daftar lengkap format yang tersedia, lihat dokumentasi DateFormat.

2. Menyesuaikan dengan Kolom yang Ditentukan Developer

Untuk fleksibilitas maksimal, Google Wallet memungkinkan Anda membuat kolom data kustom sendiri menggunakan textModulesData. Bagian ini sangat cocok untuk menampilkan informasi unik yang tidak sesuai dengan kolom yang telah ditentukan, seperti catatan singkat kustom, manfaat anggota, atau detail khusus lokasi.

Penting: Sebelum membuat kolom kustom, selalu tinjau kolom standar dalam dokumentasi referensi untuk jenis kartu Anda. Kolom standar mungkin sudah ada untuk kasus penggunaan Anda. Penggunaan kolom yang telah ditentukan sebelumnya dapat meningkatkan pengalaman pengguna secara signifikan dengan mengaktifkan fitur cerdas di seluruh platform Google seperti notifikasi proaktif, info terbaru di layar utama Pixel, dan visibilitas di Penelusuran—jika pengguna telah memberikan izin yang diperlukan.

Anda menentukan item textModulesData dengan id unik dalam Object atau Class, lalu merujuk id tersebut dalam cardTemplateOverride.

Menyusun Baris Kartu

Anda dapat mendesain kartu dengan satu, dua, atau tiga item data per kartu, sehingga Anda dapat mengatur informasi secara logis. Tidak ada batasan jumlah baris yang dapat Anda tambahkan, tetapi untuk pengalaman pengguna yang bersih, pertimbangkan apa yang paling penting untuk ditampilkan di bagian depan kartu.

• Praktik Terbaik: Untuk informasi tambahan, gunakan bagian bawah kartu pas atau fitur Wallet lainnya seperti messages, linksModuleData, atau linkedOfferIds. Hal ini membuat tampilan kartu utama tidak berantakan.

Contoh: Baris Tiga Item dengan Data Kustom

Buat baris untuk menampilkan detail kustom. Untuk kartu loyalitas, ini bisa berupa poin, tingkat, dan saldo. Untuk tiket acara, bisa berupa "Bagian", "Baris", dan "Kursi".

Definisi Class: cardTemplateOverride mereferensikan tiga ID unik: detail1, detail2, dan detail3.

...
"classTemplateInfo": {
      "cardTemplateOverride": {
        "cardRowTemplateInfos": [
        {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                    "fieldPath": "object.accountName",
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                     "fieldPath": "object.textModulesData['mem_since']",
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.loyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.loyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "class.rewardsTierLabel"
                    },
                    {
                      "fieldPath": "class.rewardsTier"
                    }
                  ]
                }
              }
            }
          },
          {
            "twoItems": {
              "startItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.label"
                    },
                    {
                      "fieldPath": "object.secondaryLoyaltyPoints.balance"
                    }
                  ]
                }
              },
              "endItem": {
                "firstValue": {
                  "fields": [
                    {
                      "fieldPath": "object.textModulesData['visits']",
                    }
                  ]
                }
              }
            }
          },
        ]
      }
    }
...
"rewardsTier": "Gold",
"rewardsTierLabel": "Tier",

Definisi Objek: Object menyediakan data dan ID yang sesuai untuk setiap kolom.

...
"accountName": "Camille Walsh",
"loyaltyPoints": {
    "balance": {
        "string": "1500"
    },
    "label": "Points"
},
"secondaryLoyaltyPoints" : {
    "balance": {
        "money": {
            "micros" : "28250000",
            "currencyCode": "USD",
        }
    },
    "label": "Balance"
},
"textModulesData": [
{
    "header": "Visits",
    "body": "17",
    "id": "visits"
  },
  {
    "header": "Member since",
    "body": "Mar 01, 2024",
    "id": "mem_since"
  },
]
...

Data Class versus Objek untuk Variasi

Anda dapat menggabungkan data tingkat kelas dan tingkat objek untuk membuat kartu dinamis yang dipersonalisasi. Hal ini berguna untuk membuat beberapa versi kartu yang sama.

• Tingkat kelas textModulesData: Gunakan ini untuk detail yang sama untuk sekelompok pengguna (misalnya, pesan "Selamat datang di VIP" untuk semua pemegang tiket VIP).
• textModulesData tingkat objek: Gunakan ini untuk detail khusus satu pengguna (misalnya, "Jane, kursi Anda memiliki pandangan yang terhalang").

Contoh: Menampilkan Tiket Khusus Tingkatan

Anda dapat membuat berbagai resource Class untuk berbagai variasi kartu, seperti "Tiket Masuk Umum" versus "VIP" untuk acara, atau "Ekonomi" versus "Bisnis" untuk penerbangan. Setiap kelas dapat memiliki desain unik (gambar utama, warna) dan teks default.

Anggota yang memulai dengan Silver	Anggota diupgrade ke Gold	Anggota Lain di Tingkat Diamond

Konten di bagian bawah kartu

Kolom dari linksModuleData, imageModulesData tidak dirender saat direferensikan di cardTemplateOverride. Konten ini otomatis ditampilkan di bagian bawah kartu, sehingga pengguna dapat mengakses link layanan pelanggan, gambar promosi, persyaratan dan ketentuan, serta informasi tambahan lainnya dengan lebih baik.

3. Di Luar Tampilan Kartu: Penggantian Template Lainnya

Objek classTemplateInfo menawarkan lebih dari sekadar cardTemplateOverride. Anda dapat menyesuaikan bagian lain dari pengalaman Google Wallet untuk memberikan presentasi kartu Anda yang lebih kaya dan intuitif.

Untuk mengetahui detail lengkap tentang semua penggantian yang tersedia, lihat dokumentasi referensi ClassTemplateInfo.

• listTemplateOverride: Menyesuaikan tata letak baris di tampilan daftar utama aplikasi Google Wallet, sehingga Anda dapat menandai kolom yang paling penting sebelum pengguna membuka kartu mereka.
• detailsTemplateOverride: Menyusun baris dan tata letak bagian bawah kartu, sehingga memberi Anda ruang yang fleksibel untuk informasi tambahan, link, dan teks.
• cardBarcodeSectionDetails: Memungkinkan Anda menyesuaikan bagian kode batang pada kartu.