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

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

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

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

ประเภทบัตร

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

เช่น อินสแตนซ์ต่อไปนี้ของ 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"
}
  

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

ส่งวัตถุ

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

ตัวอย่างเช่น เมื่อสร้างตั๋วเข้างานด้วย 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": ""
  }
}
  

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

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

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

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

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

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

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

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

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