Membuat kartu di Web menggunakan Google Wallet API

Membuat kartu di Web menggunakan Google Wallet API

Tentang codelab ini

Terakhir diperbarui Jan 19, 2023

Ditulis 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 multi-trip, 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 semua kasus penggunaan yang dapat ditampilkan dengan:

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

Untuk informasi Google Wallet API selengkapnya, atau menambahkan tombol Tambahkan ke Google Wallet ke halaman web, 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
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 halaman web
7. Menangani hasil penyimpanan kartu

Prasyarat

• 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:

• Membuat objek kartu menggunakan Google Wallet
• Membuat tombol Tambahkan ke Google Wallet

Dukungan

Jika Anda mengalami masalah di bagian mana pun dalam codelab, repositori GitHub google-pay/wallet-web-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 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

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 Google Pay & Wallet Console.

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 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 pastikan kerahasiaannya terjaga.

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

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, [e-mail])
5. Pilih Developer atau Admin dari menu drop-down Access level
6. Pilih Undang

3. Memulai aplikasi Node.js contoh

Durasi 10.00

Pada langkah ini, Anda akan menjalankan contoh aplikasi Node.js yang berfungsi sebagai situs belanja dan server backend.

Gandakan repositori sampel

Repositori google-pay/wallet-web-codelab berisi project contoh berbasis Node.js dan berbagai file skrip yang meniru server backend yang digunakan untuk menyediakan class dan objek kartu. Anda akan mengeditnya untuk menyertakan tombol Tambahkan ke Google Wallet di layar detail produk.

1. Membuat clone repositori ke workstation lokal

   git clone https://github.com/google-pay/wallet-web-codelab.git
   

Menginstal dependensi project

1. Buka repositori yang di-clone di terminal atau command line prompt
2. Buka direktori web (ini adalah aplikasi yang akan Anda ubah di bagian lain codelab ini)

   cd web
   

3. Menginstal dependensi Node.js

   npm install .
   

4. Memulai aplikasi

   node app.js
   

5. Buka aplikasi yang berjalan di http://localhost:3000

Jika Anda memasukkan alamat email dan memilih Buat kartu, tidak akan terjadi apa pun. Pada langkah berikutnya, Anda akan mengonfigurasi aplikasi untuk membuat class dan objek kartu baru.

4. Membuat class kartu Umum

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 di 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 tersebut 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 dengan 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. Buka file web/app.js.
2. Ganti nilai issuerId dengan ID Penerbit Anda dari Konsol Google Pay & Wallet

   // TODO: Define Issuer ID
   const issuerId = 'ISSUER_ID';
   

3. Menemukan fungsi createPassClass
4. Dalam fungsi, buat klien HTTP yang diautentikasi dan gunakan Google Wallet API untuk membuat class kartu baru

   // TODO: Create a Generic pass class
   let genericClass = {
     'id': `${classId}`,
     'classTemplateInfo': {
       'cardTemplateOverride': {
         'cardRowTemplateInfos': [
           {
             'twoItems': {
               'startItem': {
                 'firstValue': {
                   'fields': [
                     {
                       'fieldPath': 'object.textModulesData["points"]'
                     }
                   ]
                 }
               },
               'endItem': {
                 'firstValue': {
                   'fields': [
                     {
                       'fieldPath': 'object.textModulesData["contacts"]'
                     }
                   ]
                 }
               }
             }
           }
         ]
       },
       'detailsTemplateOverride': {
         'detailsItemInfos': [
           {
             'item': {
               'firstValue': {
                 'fields': [
                   {
                     'fieldPath': 'class.imageModulesData["event_banner"]'
                   }
                 ]
               }
             }
           },
           {
             'item': {
               'firstValue': {
                 'fields': [
                   {
                     'fieldPath': 'class.textModulesData["game_overview"]'
                   }
                 ]
               }
             }
           },
           {
             'item': {
               'firstValue': {
                 'fields': [
                   {
                     'fieldPath': 'class.linksModuleData.uris["official_site"]'
                   }
                 ]
               }
             }
           }
         ]
       }
     },
     'imageModulesData': [
       {
         'mainImage': {
           'sourceUri': {
             'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-2021-card.png'
           },
           'contentDescription': {
             'defaultValue': {
               'language': 'en-US',
               'value': 'Google I/O 2022 Banner'
             }
           }
         },
         'id': 'event_banner'
       }
     ],
     'textModulesData': [
       {
         'header': 'Gather points meeting new people at Google I/O',
         'body': 'Join the game and accumulate points in this badge by meeting other attendees in the event.',
         'id': 'game_overview'
       }
     ],
     'linksModuleData': {
       'uris': [
         {
           'uri': 'https://io.google/2022/',
           'description': 'Official I/O \'22 Site',
           'id': 'official_site'
         }
       ]
     }
   };
   
   let response;
   try {
     // Check if the class exists already
     response = await httpClient.request({
       url: `${baseUrl}/genericClass/${classId}`,
       method: 'GET'
     });
   
     console.log('Class already exists');
     console.log(response);
   } catch (err) {
     if (err.response && err.response.status === 404) {
       // Class does not exist
       // Create it now
       response = await httpClient.request({
         url: `${baseUrl}/genericClass`,
         method: 'POST',
         data: genericClass
       });
   
       console.log('Class insert response');
       console.log(response);
     } else {
       // Something else went wrong
       console.log(err);
       res.send('Something went wrong...check the console logs!');
     }
   }
   

Saat dijalankan, kode 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.

5. Membuat objek kartu Umum

Pada langkah ini, Anda akan mengonfigurasi aplikasi Node.js untuk membuat objek kartu Umum menggunakan class yang Anda buat sebelumnya. 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 web/app.js.
2. Menemukan fungsi createPassObject
3. Dalam fungsi, tentukan objek kartu baru untuk pengguna Anda

   // TODO: Create a new Generic pass for the user
   let objectSuffix = `${req.body.email.replace(/[^\w.-]/g, '_')}`;
   let objectId = `${issuerId}.${objectSuffix}`;
   
   let genericObject = {
     'id': `${objectId}`,
     'classId': classId,
     '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'
       }
     },
     'subheader': {
       'defaultValue': {
         'language': 'en',
         'value': 'Attendee'
       }
     },
     'header': {
       'defaultValue': {
         'language': 'en',
         'value': 'Alex McJacobs'
       }
     },
     'barcode': {
       'type': 'QR_CODE',
       'value': `${objectId}`
     },
     'heroImage': {
       'sourceUri': {
         'uri': 'https://storage.googleapis.com/wallet-lab-tools-codelab-artifacts-public/google-io-hero-demo-only.jpg'
       }
     },
     'textModulesData': [
       {
         'header': 'POINTS',
         'body': '1234',
         'id': 'points'
       },
       {
         'header': 'CONTACTS',
         'body': '20',
         'id': 'contacts'
       }
     ]
   };
   
   // TODO: Create the signed JWT and link
   res.send("Form submitted!");
   

Jika memuat ulang aplikasi, memasukkan alamat email, dan mengirimkan formulir, Anda tidak akan melihat output apa pun. Objek kartu sedang ditentukan oleh aplikasi backend, tetapi tidak ada output yang ditampilkan. Selanjutnya, Anda akan mengubah kartu menjadi link Tambahkan ke Google Wallet.

6. Membuat tombol Tambahkan ke Google Wallet

Untuk langkah terakhir, Anda akan membuat JWT yang ditandatangani dan menampilkan link yang dapat digunakan di tombol Tambahkan ke Google Wallet. Saat pengguna memilih tombol, mereka akan diminta untuk menyimpan kartu ke dompet.

1. Buat klaim JWT, encode menggunakan kunci pribadi akun layanan, dan tampilkan tombol Tambahkan ke Google Wallet dengan link tersemat

   // TODO: Create the signed JWT and link
   const claims = {
     iss: credentials.client_email,
     aud: 'google',
     origins: [],
     typ: 'savetowallet',
     payload: {
       genericObjects: [
         genericObject
       ]
     }
   };
   
   const token = jwt.sign(claims, credentials.private_key, { algorithm: 'RS256' });
   const saveUrl = `https://pay.google.com/gp/v/save/${token}`;
   
   res.send(`<a href='${saveUrl}'><img src='wallet-button.png'></a>`);
   

2. Memuat ulang aplikasi yang berjalan di browser Anda
3. Masukkan alamat email Anda ke dalam formulir, lalu pilih Buat kartu
4. Saat muncul, pilih tombol Tambahkan ke Google Wallet

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

7. Selamat

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

Pelajari lebih lanjut

Lihat integrasi lengkap di repositori GitHub google-pay/wallet-web-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.

Lihat Prasyarat Web API untuk mempelajari lebih lanjut.