Membuat kartu di Web 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

Contoh kartu Google Wallet untuk acara konferensi

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

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 halaman web Anda
  7. Menangani hasil penyimpanan kartu

Prasyarat

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

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

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, test-svc@myproject.iam.gserviceaccount.com)
  5. Pilih Developer atau Admin dari menu drop-down Tingkat akses
  6. Pilih Undang.

3. Mulai aplikasi Node.js contoh

Durasi 10:00

Pada langkah ini, Anda akan menjalankan aplikasi Node.js contoh 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. Buat clone repositori ke workstation lokal Anda
    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 Anda
  2. Buka direktori web (ini adalah aplikasi yang akan Anda ubah di bagian selanjutnya dalam codelab ini)
    cd web
  3. Menginstal dependensi Node.js
    npm install .
  4. Mulai aplikasi
    node app.js
  5. Buka aplikasi yang berjalan di http://localhost:3000

Contoh aplikasi web dengan kolom untuk memasukkan alamat email dan tombol Buat kartu

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

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

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. 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. Temukan fungsi createPassClass
  4. Di 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 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.

5. Membuat objek Kartu umum

Pada langkah ini, Anda akan mengonfigurasi aplikasi Node.js untuk membuat objek Kartu generik menggunakan class yang Anda buat sebelumnya. 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 web/app.js.
  2. Temukan 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 Anda 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 pas 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 mereka.

  1. Buat klaim JWT, enkode menggunakan kunci pribadi akun layanan, dan tampilkan tombol Tambahkan ke Google Wallet dengan link yang disematkan
    // 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

Tombol Tambahkan ke Google Wallet berhasil dirender di frontend aplikasi

7. Selamat

Contoh objek Kartu umum

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