ภาพรวมคลาสและออบเจ็กต์ของบัตร

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

Google Wallet API มีชุดคลาสบัตรและออบเจ็กต์บัตรที่กำหนดไว้ล่วงหน้า ซึ่งคุณสร้างอินสแตนซ์ของคลาสและออบเจ็กต์เหล่านั้น แล้วใช้เพื่อสร้างบัตรที่ออกให้แก่ผู้ใช้ เช่น GiftCardClass และ GiftCardObject, GenericClass และ GenericObject รวมถึงอื่นๆ

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

ประเภทบัตร

ให้คิดว่า Passes Class เป็นเทมเพลตที่ใช้ร่วมกันซึ่งใช้สร้างบัตรผ่านอย่างน้อย 1 ใบ ที่คุณจะออกให้แก่ผู้ใช้ คลาสบัตรจะกำหนดชุดพร็อพเพอร์ตี้ทั่วไปที่จะรวมไว้ ในบัตรทั้งหมดที่อ้างอิงถึงคลาสดังกล่าว

ตัวอย่างเช่น อินสแตนซ์ต่อไปนี้ของ EventTicketClass จะกำหนดฟิลด์ที่ใช้ร่วมกันในตั๋วที่ออกทั้งหมดสำหรับกิจกรรมที่กำลังจะจัดขึ้น(สถานที่จัดงาน ชื่อกิจกรรม ผู้ออก วันที่/เวลา)

{
  "id": "ISSUER_ID.EVENT_CLASS_ID",
  "issuerName": "[TEST ONLY] Heraldic Event",
  "localizedIssuerName": {
    "defaultValue": {
      "language": "en-US",
      "value": "[TEST ONLY] Heraldic Event"
    }
  },
  "eventName": {
    "defaultValue": {
      "language": "en-US",
      "value": "Google Live"
    }
  },
  "venue": {
    "name": {
      "defaultValue": {
        "language": "en-US",
        "value": "Shoreline Amphitheater"
      }
    },
    "address": {
      "defaultValue": {
        "language": "en-US",
        "value": "ADDRESS_OF_THE_VENUE"
      }
    }
  },
  "dateTime": {
    "start": "2023-04-12T11:30"
  },
  "reviewStatus": "UNDER_REVIEW"
}
  

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

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

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

ตัวอย่างเช่น เมื่อสร้างบัตรตั๋วเข้าร่วมกิจกรรมด้วย Google Wallet API อินสแตนซ์ EventTicketObject จะมีพร็อพเพอร์ตี้สำหรับที่นั่งที่กำหนดให้กับตั๋วดังกล่าว เนื่องจากค่าเหล่านั้นจะเฉพาะเจาะจงสำหรับตั๋วแต่ละใบที่ออก

{
  "id": "ISSUER_ID.OBJECT_ID",
  "classId": "ISSUER_ID.EVENT_CLASS_ID",
  "state": "ACTIVE",
  "seatInfo": {
    "seat": {
      "defaultValue": {
        "language": "en-us",
        "value": "9"
      }
    },
    "row": {
      "defaultValue": {
        "language": "en-us",
        "value": "L"
      }
    },
    "section": {
      "defaultValue": {
        "language": "en-us",
        "value": "45"
      }
    },
    "gate": {
      "defaultValue": {
        "language": "en-us",
        "value": "7C"
      }
    }
  },
  "barcode": {
    "type": "BARCODE_TYPE_UNSPECIFIED",
    "value": "BARCODE_VALUE",
    "alternateText": ""
  }
}
  

ออบเจ็กต์บัตรแต่ละอินสแตนซ์ต้องมีพร็อพเพอร์ตี้ id ซึ่งคุณต้องระบุ Object ID นี้ ทําหน้าที่เป็นตัวระบุที่ไม่ซ้ำกันซึ่งคุณจะใช้อ้างอิงเมื่อออกบัตรให้ผู้ใช้

วิธีการทำงานของคลาสบัตรกับออบเจ็กต์บัตร

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

ตัวอย่างเช่น แผนภาพต่อไปนี้ของบัตรกิจกรรมอย่างง่ายแสดงให้เห็นว่าฟิลด์ที่กำหนดไว้ใน EventTicketClass ที่แชร์และฟิลด์สำหรับบัตรที่เฉพาะเจาะจงซึ่งกำหนดไว้ใน EventTicketObject จะรวมกันเพื่อสร้างบัตรที่ออกขั้นสุดท้ายได้อย่างไร โปรดสังเกตวิธีอ้างอิงรหัสของคลาสบัตรในพร็อพเพอร์ตี้ classId ของออบเจ็กต์บัตร

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

การเพิ่มบัตรลงใน Google Wallet ของผู้ใช้

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

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

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