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

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

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

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

คลาสของบัตร

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

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

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

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