ภาพรวม

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

API การเปิดใช้งาน

มีการระบุปลายทางการเปิดใช้งานใน API โดยใช้ activationOptions ในคลาสขนส่งสาธารณะ พาร์ทเนอร์มีหน้าที่ดูแลรักษาปลายทางการเปิดใช้งานที่ใช้งานได้ให้มีเวลาในการตอบสนองที่สมเหตุสมผล

  activationOptions: {
    activationUrl: string
  }

ฟิลด์	คำอธิบาย
activationUrl	string URL สำหรับปลายทางพาร์ทเนอร์ที่ระบบจะเรียกใช้คำขอเปิดใช้งาน URL ควรโฮสต์อยู่บน HTTPS และ robots.txt ควรอนุญาตให้ UserAgent:Google-Valuables เข้าถึงเส้นทาง URL

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

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean

ฟิลด์	คำอธิบาย
activationStatus	enum (ActivationStatus) สถานะการเปิดใช้งานสำหรับออบเจ็กต์การส่งนี้ สถานะนี้จะเปลี่ยนการนำเสนอตั๋วและอนุญาตให้ผู้ใช้ดำเนินการ เช่น ปุ่มเปิดใช้งานจะแสดงบนรายละเอียดของตั๋วหากตั้งค่าเป็น NOT_ACTIVATED ค่าที่ยอมรับได้มีดังนี้ NOT_ACTIVATED ACTIVATED
deviceContext	object (DeviceContext) บริบทของอุปกรณ์ที่จะเชื่อมโยงกับออบเจ็กต์ หากตั้งค่าไว้ ระบบจะส่งข้อมูลการแลกสิทธิ์ไปยังอุปกรณ์ที่ระบุเท่านั้น
hasLinkedDevice	boolean ออบเจ็กต์นี้ลิงก์กับอุปกรณ์เครื่องเดียวอยู่หรือไม่

DeviceContext

ฟิลด์

คำอธิบาย

deviceToken

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

การปักหมุดอุปกรณ์

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

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

หากต้องการใช้การปักหมุดอุปกรณ์ คุณควรอัปเดตออบเจ็กต์ด้วยช่อง deviceToken ที่ได้รับพร้อมพารามิเตอร์การเปิดใช้งาน และตั้งค่า hasLinkedDevice เป็น "จริง" ในการเรียก API เดียวกัน หากต้องการ คุณจะยกเลิกการลิงก์ตั๋วจากอุปกรณ์ได้โดยการตั้งค่า hasLinkedDevice เป็น "เท็จ" ในการเรียก API ในอนาคต

พารามิเตอร์การเปิดใช้งาน

คำขอที่ส่งไปยังปลายทางการเปิดใช้งานจะมีพารามิเตอร์ต่อไปนี้

ตัวอย่าง JSON:

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

ตัวระบุ	คำอธิบาย
classId	รหัสชั้นเรียนที่มีคุณสมบัติครบถ้วน โดยใช้รูปแบบต่อไปนี้ <issuer_id.class_id>
objectIds	อาร์เรย์ที่มีคุณสมบัติครบถ้วนของรหัสออบเจ็กต์ที่ใช้รูปแบบต่อไปนี้ <issuer_id.object_id>
expTimeMillis	เวลาหมดอายุเป็นมิลลิวินาทีตั้งแต่ EPOCH หลังจากเวลาหมดอายุ จะถือว่าข้อความไม่ถูกต้อง
eventType	"activate" เสมอ
nonce	ไม่มีการติดตามการจัดส่งที่ซ้ำกัน
deviceContext	รหัสที่ไม่ซ้ำกันที่ Google สร้างขึ้นซึ่งแสดงถึงอุปกรณ์ที่ผู้ใช้กำลังดำเนินการ คุณควรใช้รหัสนี้เมื่อทำการอัปเดตที่ผูกออบเจ็กต์กับอุปกรณ์ รหัสนี้อาจไม่ได้เป็นค่าคงที่สำหรับคำขอในอนาคตจากอุปกรณ์หนึ่งๆ