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

1. บทนำ

ภาพรวม

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

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

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

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

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

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

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

ประเภทบัตรและออบเจ็กต์

Google Wallet API มีเมธอดสำหรับสร้างสิ่งต่อไปนี้

ประเภท

คำอธิบาย

ประเภทบัตร

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

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

อินสแตนซ์ของประเภทบัตรที่ไม่ซ้ำกันสำหรับรหัสผู้ใช้

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

ใน Codelab นี้ คุณจะได้ทำภารกิจต่อไปนี้

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

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

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

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

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

การสนับสนุน

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

2. ตั้งค่า

ในขั้นตอนนี้ คุณจะได้สร้างบัญชีผู้ออกบัตรในโหมดสาธิต ซึ่งจะช่วยให้คุณสร้างประเภทบัตรและออบเจ็กต์บัตรที่เพิ่มลงใน Wallet ของผู้ใช้ได้ จากนั้น คุณจะได้สร้างโปรเจ็กต์ 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. เพิ่มอีเมลที่คุณจะใช้ใน Codelab นี้

เปิดใช้ 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 SDK ใช้ตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เพื่อตรวจสอบสิทธิ์เป็นบัญชีบริการและเข้าถึง 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 ใน Codelab นี้ คุณจะได้สร้างประเภทบัตรทั่วไปโดยใช้ 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://codelabs.developers.google.com/static/add-to-wallet-web/images/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 เพื่อสร้างออบเจ็กต์บัตร วิธีนี้เหมาะที่สุดสำหรับกรณีที่ผู้ใช้ยอมรับการใช้งานไม่แน่นอนหรือไม่ทราบ เนื่องจากวิธีนี้จะป้องกันไม่ให้มีการสร้างออบเจ็กต์บัตรแล้วไม่ได้ใช้งาน เราจะใช้วิธีนี้ใน Codelab

  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://developers.google.com/static/wallet/site-assets/images/pass-builder/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://developers.google.com/static/wallet/site-assets/images/pass-builder/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