สร้างบัตรบนเว็บโดยใช้ Google Wallet API

1. บทนำ

ภาพรวม

Google Wallet API ช่วยให้คุณเข้าถึงผู้ใช้ผ่านบัตรประเภทต่างๆ ได้ เช่น บัตรสะสมคะแนน ข้อเสนอ บัตรของขวัญ ตั๋วเข้างาน ตั๋วโดยสาร บอร์ดดิ้งพาส และอื่นๆ บัตรแต่ละประเภทหรือคลาสบัตรจะมีช่องและฟีเจอร์เฉพาะสำหรับ Use Case เพื่อปรับปรุงประสบการณ์ของผู้ใช้

อย่างไรก็ตาม วิธีการเหล่านี้อาจไม่เหมาะกับทุกกรณีการใช้งาน หากต้องการสร้างประสบการณ์การใช้งานที่ปรับแต่งมากขึ้น คุณสามารถใช้บัตรประเภททั่วไปได้ ตัวอย่างกรณีการใช้งานสำหรับบัตรประเภททั่วไปมีดังนี้

  • บัตรจอดรถ
  • บัตรสมาชิกห้องสมุด
  • บัตรกำนัลมูลค่าที่เก็บไว้
  • บัตรสมาชิกฟิตเนส
  • การจอง

คุณใช้บัตรทั่วไปสำหรับ Use Case ใดก็ได้ที่แสดงได้ด้วยสิ่งต่อไปนี้

  • ข้อมูลสูงสุด 3 แถว
  • (ไม่บังคับ) กราฟิกบาร์โค้ด
  • (ไม่บังคับ) ส่วนรายละเอียด

ตัวอย่างบัตร Google Wallet สำหรับกิจกรรมการประชุม

ดูข้อมูลเพิ่มเติมเกี่ยวกับ Google Wallet API หรือการเพิ่มปุ่มเพิ่มลงใน Google Wallet ลงในหน้าเว็บได้ที่เอกสารสำหรับนักพัฒนาซอฟต์แวร์ของ Google Wallet

ส่งคลาสและออบเจ็กต์

Google Wallet API เปิดเผยวิธีการสร้างรายการต่อไปนี้

ประเภท

คำอธิบาย

คลาสบัตร

เทมเพลตสำหรับออบเจ็กต์บัตรแต่ละใบ ซึ่งมีข้อมูลที่ใช้ร่วมกันในออบเจ็กต์บัตรทั้งหมดที่อยู่ในคลาสนี้

ออบเจ็กต์บัตร

อินสแตนซ์ของคลาสบัตรที่ไม่ซ้ำกันสำหรับรหัสผู้ใช้

เกี่ยวกับ Codelab นี้

ในโค้ดแล็บนี้ คุณจะได้ทํางานต่อไปนี้

  1. สร้างบัญชีผู้ออกบัตรใหม่ในโหมดสาธิต
  2. สร้างบัญชีบริการสำหรับการออกบัตร
  3. สร้างคลาสบัตรทั่วไปใหม่
  4. สร้างออบเจ็กต์บัตรใหม่
  5. สร้างปุ่มเพิ่มลงใน Google Wallet เพื่อบันทึกบัตร
  6. แสดงปุ่มในหน้าเว็บ
  7. จัดการผลการบันทึกบัตร

ข้อกำหนดเบื้องต้น

วัตถุประสงค์

หลังจากทำ Codelab นี้เสร็จแล้ว คุณจะทำสิ่งต่อไปนี้ได้

  • สร้างออบเจ็กต์บัตรโดยใช้ Google Wallet
  • สร้างปุ่มเพิ่มลงใน Google Wallet

การสนับสนุน

หากติดขัดในส่วนใดของ Codelab ที่เก็บ google-pay/wallet-web-codelab บน GitHub มีโซลูชันที่สมบูรณ์สำหรับการอ้างอิง

2. ตั้งค่า

ในขั้นตอนนี้ คุณจะได้สร้างบัญชีผู้ออกบัตรในโหมดสาธิต ซึ่งจะช่วยให้คุณสร้างคลาสและออบเจ็กต์บัตรที่เพิ่มลงในกระเป๋าเงินของผู้ใช้ได้ จากนั้นคุณจะสร้างโปรเจ็กต์และบัญชีบริการของ Google Cloud โดยจะใช้เพื่อสร้างคลาสและออบเจ็กต์บัตรแบบเป็นโปรแกรมในลักษณะเดียวกับเซิร์ฟเวอร์แบ็กเอนด์ สุดท้าย คุณจะให้สิทธิ์บัญชีบริการ Google Cloud ในการจัดการบัตรในบัญชีผู้ออกบัตร Google Wallet

ลงชื่อสมัครใช้บัญชีผู้ออกบัตร Google Wallet

คุณต้องมีบัญชีผู้ออกบัตรเพื่อสร้างและเผยแพร่บัตรสำหรับ Google Wallet คุณลงชื่อสมัครใช้ได้โดยใช้ Google Pay & Wallet Console ในตอนแรก คุณจะมีสิทธิ์สร้างบัตรในโหมดสาธิต ซึ่งหมายความว่าเฉพาะผู้ใช้ทดสอบบางรายเท่านั้นที่จะเพิ่มบัตรที่คุณสร้างได้ คุณจัดการผู้ใช้ทดสอบได้ใน Google Pay และ Wallet Console

ดูข้อมูลเพิ่มเติมเกี่ยวกับโหมดสาธิตได้ที่ข้อกำหนดเบื้องต้นสำหรับบัตรทั่วไป

  1. เปิด Google Pay & Wallet Console
  2. ทำตามวิธีการบนหน้าจอเพื่อสร้างบัญชีผู้ออกบัตร
  3. เลือก Google Wallet API
  4. ยืนยันว่าคุณเข้าใจข้อกำหนดในการให้บริการและนโยบายความเป็นส่วนตัว
  5. คัดลอกค่ารหัสผู้ออกไปยังโปรแกรมแก้ไขข้อความหรือตำแหน่งอื่นๆ
  6. ในแท็บจัดการ ให้เลือกตั้งค่าบัญชีทดสอบ
  7. เพิ่มอีเมลที่คุณจะใช้ในโค้ดแล็บนี้

เปิดใช้ Google Wallet API

  1. ลงชื่อเข้าใช้คอนโซล Google Cloud
  2. หากยังไม่มีโปรเจ็กต์ Google Cloud ให้สร้างตอนนี้ (ดูข้อมูลเพิ่มเติมได้ที่การสร้างและการจัดการโปรเจ็กต์)
  3. เปิดใช้ Google Wallet API (หรือที่เรียกว่า Google Pay for Passes API) สำหรับโปรเจ็กต์

สร้างบัญชีบริการและคีย์

คุณต้องมีบัญชีบริการและคีย์บัญชีบริการเพื่อเรียกใช้ Google Wallet API บัญชีบริการคือข้อมูลประจำตัวที่เรียก Google Wallet API คีย์บัญชีบริการมีคีย์ส่วนตัวที่ระบุแอปพลิเคชันของคุณเป็นบัญชีบริการ คีย์นี้เป็นข้อมูลที่ละเอียดอ่อน ดังนั้นโปรดเก็บไว้เป็นความลับ

สร้างบัญชีบริการ

  1. เปิดบัญชีบริการในคอนโซล Google Cloud
  2. ป้อนชื่อ รหัส และคำอธิบายสำหรับบัญชีบริการ
  3. เลือกสร้างและดำเนินการต่อ
  4. เลือกเสร็จสิ้น

สร้างคีย์บัญชีบริการ

  1. เลือกบัญชีบริการ
  2. เลือกเมนูคีย์
  3. เลือกเพิ่มคีย์ แล้วเลือกสร้างคีย์ใหม่
  4. เลือกประเภทคีย์ JSON
  5. เลือกสร้าง

คุณจะได้รับข้อความแจ้งให้บันทึกไฟล์คีย์ลงในเวิร์กสเตชันในเครื่อง อย่าลืมจำตำแหน่งของไฟล์

ตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS

ตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS ใช้โดย Google SDK เพื่อตรวจสอบสิทธิ์ในฐานะบัญชีบริการและเข้าถึง API ต่างๆ สำหรับโปรเจ็กต์ Google Cloud

  1. ทำตามวิธีการในเอกสารประกอบเกี่ยวกับคีย์บัญชีบริการของ Google Cloud เพื่อตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS
  2. ตรวจสอบว่าได้ตั้งค่าตัวแปรสภาพแวดล้อมในเซสชันเทอร์มินัล (MacOS/Linux) หรือบรรทัดคำสั่ง (Windows) ใหม่แล้ว (คุณอาจต้องเริ่มเซสชันใหม่หากมีเซสชันที่เปิดอยู่แล้ว)
    echo $GOOGLE_APPLICATION_CREDENTIALS

ให้สิทธิ์บัญชีบริการ

สุดท้าย คุณจะต้องให้สิทธิ์บัญชีบริการในการจัดการบัตร Google Wallet

  1. เปิด Google Pay & Wallet Console
  2. เลือกผู้ใช้
  3. เลือกเชิญผู้ใช้
  4. ป้อนอีเมลของบัญชีบริการ (เช่น test-svc@myproject.iam.gserviceaccount.com)
  5. เลือกนักพัฒนาแอปหรือผู้ดูแลระบบจากเมนูแบบเลื่อนลงระดับการเข้าถึง
  6. เลือกเชิญ

3. เริ่มแอป Node.js ตัวอย่าง

ระยะเวลา 10:00

ในขั้นตอนนี้ คุณจะเรียกใช้แอปพลิเคชัน Node.js ตัวอย่างซึ่งทำหน้าที่เป็นเว็บไซต์ช็อปปิ้งและเซิร์ฟเวอร์แบ็กเอนด์

โคลนที่เก็บตัวอย่าง

ที่เก็บ google-pay/wallet-web-codelab มีโปรเจ็กต์ตัวอย่างที่อิงตาม Node.js และไฟล์สคริปต์ต่างๆ ที่เลียนแบบเซิร์ฟเวอร์แบ็กเอนด์ที่ใช้ในการจัดสรรคลาสและออบเจ็กต์บัตร คุณจะแก้ไขปุ่มเหล่านี้เพื่อใส่ปุ่มเพิ่มลงใน Google Wallet ในหน้าจอรายละเอียดผลิตภัณฑ์

  1. โคลนที่เก็บไปยังเวิร์กสเตชันในเครื่อง
    git clone https://github.com/google-pay/wallet-web-codelab.git

ติดตั้งการอ้างอิงของโปรเจ็กต์

  1. เปิดที่เก็บที่โคลนในเทอร์มินัลหรือพรอมต์บรรทัดคำสั่ง
  2. ไปที่ไดเรกทอรี web (นี่คือแอปที่คุณจะแก้ไขใน Codelab ที่เหลือ)
    cd web
  3. ติดตั้งการอ้างอิง Node.js
    npm install .
  4. เริ่มแอป
    node app.js
  5. เปิดแอปที่ทำงานบน http://localhost:3000

ตัวอย่างเว็บแอปที่มีช่องสำหรับป้อนอีเมลและปุ่มสร้างบัตร

หากคุณป้อนอีเมลและเลือกสร้างบัตร ระบบจะไม่ดำเนินการใดๆ ในขั้นตอนถัดไป คุณจะกำหนดค่าแอปเพื่อสร้างคลาสและออบเจ็กต์บัตรใหม่

4. สร้างคลาสบัตรทั่วไป

ในขั้นตอนนี้ คุณจะได้สร้างคลาสฐานสำหรับบัตร ทุกครั้งที่มีการสร้างบัตรใหม่สำหรับผู้ใช้ บัตรนั้นจะรับค่าพร็อพเพอร์ตี้ที่กำหนดไว้ในคลาสบัตร

คลาสบัตรที่คุณจะสร้างใน Codelab นี้จะใช้ความยืดหยุ่นของบัตรทั่วไปเพื่อสร้างออบเจ็กต์ที่ใช้ได้ทั้งเป็นป้ายประจำตัวและเครื่องมือติดตามคะแนนความท้าทาย เมื่อสร้างออบเจ็กต์บัตรจากคลาสนี้ ออบเจ็กต์จะปรากฏเหมือนในกราฟิกต่อไปนี้

คุณสร้างคลาสบัตรได้โดยตรงใน Google Pay และ Wallet Console หรือจะใช้ Google Wallet API ก็ได้ ในโค้ดแล็บนี้ คุณจะได้สร้างคลาสบัตรทั่วไปโดยใช้ API ซึ่งเป็นไปตามกระบวนการที่เซิร์ฟเวอร์แบ็กเอนด์ส่วนตัวจะใช้เพื่อสร้างคลาสบัตร

  1. เปิดไฟล์ web/app.js
  2. แทนที่ค่าของ issuerId ด้วยรหัสผู้ออกบัตรจาก Google Pay & Wallet Console
    // TODO: Define Issuer ID
const issuerId = 'ISSUER_ID';
  3. ค้นหาฟังก์ชัน createPassClass
  4. ในฟังก์ชัน ให้สร้างไคลเอ็นต์ HTTP ที่ได้รับการตรวจสอบสิทธิ์ แล้วใช้ Google Wallet API เพื่อสร้างคลาสบัตรใหม่
    // 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!');
  }
}

เมื่อโค้ดทำงาน ระบบจะสร้างคลาสบัตรใหม่และแสดงผลรหัสคลาส รหัสคลาสประกอบด้วยรหัสผู้ออกตามด้วยคำต่อท้ายที่นักพัฒนาแอปกำหนด ในกรณีนี้ ระบบจะตั้งค่าคำต่อท้ายเป็น codelab_class (รหัสชั้นเรียนจะมีลักษณะคล้ายกับ 1234123412341234123.codelab_class) บันทึกเอาต์พุตจะมีการตอบกลับจาก Google Wallet API ด้วย

5. สร้างออบเจ็กต์บัตรทั่วไป

ในขั้นตอนนี้ คุณจะกำหนดค่าแอป Node.js เพื่อสร้างออบเจ็กต์บัตรทั่วไปโดยใช้คลาสที่สร้างไว้ก่อนหน้านี้ การสร้างออบเจ็กต์บัตรสำหรับผู้ใช้มี 2 ขั้นตอน

สร้างออบเจ็กต์บัตรในเซิร์ฟเวอร์แบ็กเอนด์

ในแนวทางนี้ ระบบจะสร้างออบเจ็กต์บัตรบนเซิร์ฟเวอร์แบ็กเอนด์และส่งคืนไปยังแอปไคลเอ็นต์เป็น JWT ที่ลงชื่อ วิธีนี้เหมาะที่สุดสำหรับกรณีที่ผู้ใช้ยอมรับการใช้งานสูง เนื่องจากจะช่วยให้มั่นใจได้ว่าออบเจ็กต์มีอยู่ก่อนที่ผู้ใช้จะพยายามเพิ่มลงใน Wallet

สร้างออบเจ็กต์บัตรเมื่อผู้ใช้เพิ่มบัตรลงใน Wallet

ในแนวทางนี้ ระบบจะกำหนดและเข้ารหัสออบเจ็กต์บัตรเป็น JWT ที่ลงชื่อแล้วในเซิร์ฟเวอร์แบ็กเอนด์ จากนั้นระบบจะแสดงปุ่มเพิ่มลงใน Google Wallet ในแอปไคลเอ็นต์ที่อ้างอิง JWT เมื่อผู้ใช้เลือกปุ่ม ระบบจะใช้ JWT เพื่อสร้างออบเจ็กต์บัตร วิธีนี้เหมาะที่สุดสำหรับกรณีที่การยอมรับของผู้ใช้มีความผันแปรหรือไม่ทราบ เนื่องจากจะป้องกันไม่ให้มีการสร้างออบเจ็กต์บัตรและไม่ได้ใช้งาน เราจะใช้วิธีนี้ในโค้ดแล็บ

  1. เปิดไฟล์ web/app.js
  2. ค้นหาฟังก์ชัน createPassObject
  3. ในฟังก์ชัน ให้กำหนดออบเจ็กต์บัตรใหม่สำหรับผู้ใช้
    // 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!");

หากโหลดแอปซ้ำ ป้อนอีเมล และส่งแบบฟอร์ม คุณจะไม่เห็นเอาต์พุตใดๆ แอปพลิเคชันแบ็กเอนด์กำลังกำหนดออบเจ็กต์บัตร แต่ไม่มีการแสดงผลลัพธ์ จากนั้นคุณจะเปลี่ยนบัตรให้เป็นลิงก์เพิ่มลงใน Google Wallet

6. สร้าง ปุ่มเพิ่มลงใน Google Wallet

ในขั้นตอนสุดท้าย คุณจะต้องสร้าง JWT ที่ลงชื่อแล้วและส่งคืนลิงก์ที่ใช้ในปุ่มเพิ่มลงใน Google Wallet ได้ เมื่อผู้ใช้เลือกปุ่มดังกล่าว ระบบจะแจ้งให้บันทึกบัตรลงใน Wallet

  1. สร้างการอ้างสิทธิ์ JWT, เข้ารหัสโดยใช้คีย์ส่วนตัวของบัญชีบริการ และแสดงปุ่มเพิ่มลงใน Google Wallet พร้อมลิงก์ที่ฝังไว้
    // 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. โหลดแอปที่ทำงานในเบราว์เซอร์ซ้ำ
  3. ป้อนอีเมลลงในแบบฟอร์ม แล้วเลือกสร้างบัตร
  4. เมื่อปุ่มปรากฏขึ้น ให้เลือกปุ่มเพิ่มลงใน Google Wallet

ปุ่มเพิ่มลงใน Google Wallet แสดงผลสำเร็จในส่วนหน้าของแอป

7. ขอแสดงความยินดี

ตัวอย่างออบเจ็กต์บัตรทั่วไป

ขอแสดงความยินดี คุณผสานรวม Google Wallet API บนเว็บเรียบร้อยแล้ว

ดูข้อมูลเพิ่มเติม

ดูการผสานรวมที่สมบูรณ์ได้ในที่เก็บ google-pay/wallet-web-codelab ของ GitHub

สร้างบัตรและขอสิทธิ์เข้าถึงการผลิต

เมื่อพร้อมที่จะออกบัตรของคุณเองในเวอร์ชันที่ใช้งานจริงแล้ว ให้ไปที่ Google Pay และ Wallet Console เพื่อขอสิทธิ์เข้าถึงเวอร์ชันที่ใช้งานจริง

ดูข้อมูลเพิ่มเติมได้ที่ข้อกำหนดเบื้องต้นของ Web API