บัตรที่ลิงก์อัตโนมัติ
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
ข้อมูลเบื้องต้น
ฟีเจอร์บัตรที่ลิงก์โดยอัตโนมัติช่วยให้คุณส่งบัตรเพิ่มเติมไปยังผู้ใช้ที่มีบัตรของคุณอยู่แล้วใน Google Wallet ได้ นอกจากนี้ คุณยัง
ลิงก์บัตรล่วงหน้าไปยังบัตรหลักได้ด้วยเมื่อผู้ใช้บันทึกบัตรหลัก
(หลัก) ระบบจะจัดกลุ่มบัตรที่ลิงก์อัตโนมัติไว้กับบัตรหลักซึ่งมีข้อความไฮไลต์อยู่เหนือบัตรหลักเพื่อแจ้งผู้ใช้ว่าได้ลิงก์บัตรใบใหม่แล้ว ระบบรองรับบัตรประเภทต่อไปนี้เป็นบัตรหลักหรือบัตรที่ลิงก์
- ตั๋วกิจกรรม
- บอร์ดดิ้งพาส
- บัตรโดยสาร
- ข้อเสนอ
- บัตรของขวัญ
- บัตรสะสมคะแนน
- บัตรทั่วไป
|
|
|
บัตรหลักที่มีข้อความไฮไลต์ว่าได้เพิ่มบัตรใหม่แล้ว
|
บัตรใหม่ที่ลิงก์กับบัตรหลัก
|
กรณีการใช้งาน
คุณอาจมีกรณีการใช้งานที่แตกต่างกันสำหรับการลิงก์บัตรกับบัตรที่มีอยู่ ตัวอย่าง
- ลิงก์ข้อเสนอกับบัตรสะสมคะแนนที่มีอยู่
- ลิงก์บัตรกำนัลอาหารกับบอร์ดดิ้งพาสหรือตั๋วเข้างาน
- ลิงก์บัตรจอดรถกับตั๋วเข้างาน
ข้อควรพิจารณาบางประการเมื่อใช้บัตรที่ลิงก์โดยอัตโนมัติ
- ออบเจ็กต์หลักและออบเจ็กต์ที่ลิงก์ต้องใช้ issuerId เดียวกัน
- ออบเจ็กต์ที่ลิงก์จะมีได้สูงสุด 50 รายการต่อออบเจ็กต์หลัก
- เราไม่รับประกันการส่งบัตรที่ลิงก์โดยอัตโนมัติและถือว่าดำเนินการอย่างดีที่สุด ผู้ใช้สามารถเลือกไม่รับบัตรที่ลิงก์โดยอัตโนมัติได้ หากกรณีการใช้งานมีความสำคัญและผู้ใช้ต้องได้รับบัตรที่ลิงก์ไว้ เราขอแนะนำให้สื่อสารผ่านช่องทางอื่นเพื่อให้มั่นใจว่าผู้ใช้จะเพิ่มบัตร
- การอัปเดตข้อกำหนดในการให้บริการของ Google Wallet ประกอบด้วยหลักเกณฑ์ในการใช้บัตรที่ลิงก์โดยอัตโนมัติซึ่งต้องปฏิบัติตาม
ขั้นตอนการผสานรวม
หากสร้างออบเจ็กต์หลักไว้แล้ว ให้ข้ามขั้นตอนที่ 1
- สร้างออบเจ็กต์ของบัตรประเภทใดก็ได้ที่แสดงพร้อมพารามิเตอร์ที่จำเป็น นี่คือออบเจ็กต์หลัก
- สร้างออบเจ็กต์อีกรายการของบัตรประเภทใดก็ได้ที่แสดง รายการนี้จะเป็นออบเจ็กต์ที่ลิงก์
- ไม่ว่าจะก่อนหรือหลังบันทึกออบเจ็กต์หลัก ให้อัปเดตออบเจ็กต์หลักด้วยรหัสของออบเจ็กต์ที่ลิงก์ในพารามิเตอร์ linkedObjectIds
คุณต้องระบุเพย์โหลดขั้นต่ำเพื่อตั้งค่า linkedObjectIds ในพาสหลัก พารามิเตอร์ที่จำเป็น 3 รายการ ได้แก่
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- ISSUERID.LINKED_OBJECT_ID
ตัวอย่างคําขอ JSON เพื่อเพิ่มออบเจ็กต์ที่ลิงก์ไปยังออบเจ็กต์บัตร
…
{
"id": "ISSUERID.PASS_OBJECTID",
"classId": "ISSUERID.PASS_CLASSID",
"barcode": {
"type": "qrCode",
"value": "QR code"
},
"linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
}
…
ตัวอย่างการตอบกลับ JSON หลังจากลิงก์ออบเจ็กต์กับออบเจ็กต์บัตร
…
"state": "active",
"linkedObjectIds": {
"ISSUERID.LINKED_PASS_OBJECTID"
}
…
ลักษณะการทำงานที่ควรจะเป็น
หลังจากได้รับการตอบกลับเรียบร้อยแล้ว อุปกรณ์ที่มีบัตรที่คุณอัปเดตควรได้รับบัตรที่ลิงก์ ระบบจะจัดกลุ่มบัตรที่ลิงก์นี้กับบัตรหลัก ผู้ใช้จะเห็นบัตรที่ลิงก์ไว้ด้วยการปัดไปทางขวา
การจัดการข้อยกเว้น
ข้อผิดพลาดที่อาจเกิดขึ้นเมื่อใช้ API ไม่ถูกต้อง ซึ่งอาจรวมถึง
| ข้อความ |
เหตุผล |
| ออบเจ็กต์หลักและออบเจ็กต์ที่ลิงก์ไม่ได้ใช้รหัสผู้ออกเดียวกัน |
คุณจะแนบออบเจ็กต์ที่ลิงก์กับออบเจ็กต์ของผู้ออกบัตรรายอื่นไม่ได้ |
| ออบเจ็กต์หลักและออบเจ็กต์ที่ลิงก์หมายถึงออบเจ็กต์เดียวกัน |
คุณแนบออบเจ็กต์เดียวกับ linkedObject ไม่ได้ |
| ไม่มีออบเจ็กต์ที่ลิงก์ |
ควรแทรกออบเจ็กต์ที่ลิงก์ไว้ใน Wallet API แล้ว |
| ออบเจ็กต์ที่ลิงก์มีออบเจ็กต์ที่ลิงก์อื่นอยู่แล้ว เพิ่มออบเจ็กต์ที่ฝังไว้ซึ่งลิงก์กันไม่ได้ |
ออบเจ็กต์ที่ลิงก์ต้องไม่มีออบเจ็กต์ที่ลิงก์อีกรายการ |
| ออบเจ็กต์ลิงก์กับออบเจ็กต์อื่นอยู่แล้ว ไม่สามารถเพิ่มออบเจ็กต์ที่ลิงก์ที่ซ้อนอยู่ |
ออบเจ็กต์หลักต้องไม่ออบเจ็กต์ที่ลิงก์ |
| ไม่สามารถเพิ่มออบเจ็กต์ที่ลิงก์ได้อีก เนื่องจากเกินขีดจำกัดแล้ว |
บัตรหลักมีบัตรที่ลิงก์ครบตามจำนวนที่จำกัดแล้ว |
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-08-29 UTC
[null,null,["อัปเดตล่าสุด 2025-08-29 UTC"],[[["\u003cp\u003eAuto Linked Passes enable sending additional passes to users who already have an existing pass in their Google Wallet, linking them to a primary pass for easy access.\u003c/p\u003e\n"],["\u003cp\u003eSupported pass types include event tickets, boarding passes, transit passes, offers, gift cards, loyalty passes, and generic passes.\u003c/p\u003e\n"],["\u003cp\u003eLinking passes allows for various use cases such as attaching offers to loyalty cards, meal vouchers to boarding passes, or parking passes to event tickets.\u003c/p\u003e\n"],["\u003cp\u003eConsiderations include using the same issuer ID for primary and linked passes, a limit of 50 linked objects per primary object, and best-effort automatic pushing of linked passes.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves creating a primary and linked object, then updating the primary object with the linked object's ID in the \u003ccode\u003elinkedObjectIds\u003c/code\u003e parameter.\u003c/p\u003e\n"]]],["Auto Linked Passes enable grouping a new pass with an existing \"primary\" pass in Google Wallet. To implement, create a primary and a linked pass object, then update the primary object with the linked object's ID in the `linkedObjectIds` parameter. Both passes must share the same issuer ID, with a limit of 50 linked objects per primary pass. The system will group linked passes, but delivery is not guaranteed. Linked passes cannot be primary passes.\n"],null,["# Auto Linked Passes\n\n#### Background\n\nThe Auto Linked Passes feature lets you send additional passes to a\nuser who already has your existing pass in their Google Wallet. You can also\npre-link passes to a primary pass when a user saves the **primary**\n(main) pass. The Auto Linked Pass is grouped with the primary pass with a\ncallout above the primary pass informing the user that a new pass has been\nlinked. The following pass types are supported as primary or linked passes;\n\n- Event ticket\n- Boarding pass\n- Transit pass\n- Offer\n- Gift card\n- Loyalty pass\n- Generic pass\n\n|--------------------------------------------------------------|-------------------------------------|\n| | |\n| Primary pass with the callout that a new pass has been added | New pass linked to the primary pass |\n\n#### Use Cases\n\nYou may have different use cases for linking passes to an existing pass. Some\nexamples include:\n\n- Link an offer to an existing loyalty card.\n- Link a meal voucher to a boarding pass or event ticket.\n- Link a parking pass to an event ticket.\n\n#### Some considerations when using Auto Linked Passes\n\n- The primary object and linked object must use the same issuerId.\n- There is a limit of 50 linked objects per primary object.\n- Pushing linked passes automatically is not guaranteed and considered best-effort. Users can opt out of receiving Auto Linked Passes. If the use case is critical and the user must receive the linked pass, we recommend communicating through another channel to ensure the user adds the pass.\n- Updates to the [Google Wallet AUP](https://payments.developers.google.com/terms/aup) include guidance on the use of Auto Linked Passes which must be adhered to.\n\n#### Integration Steps\n\nIf you have already created a **primary** object you can skip step 1.\n\n1. Create an [object](/wallet/tickets/transit-passes/qr-code/use-cases/create) of any pass type listed with the required parameters. This is the **primary** object.\n2. Create another object of any pass type listed. This is going to be the **linked** object.\n3. Either before or after the primary object is saved, [update](/wallet/tickets/transit-passes/qr-code/use-cases/update) the primary object with the ID of the linked object in the linkedObjectIds parameter.\n\nThere is a minimum payload required to set the linkedObjectIds on a primary\npass. The 3 required parameters include;\n\n1. ISSUERID.PRIMARY_OBJECT_ID\n2. ISSUERID.PRIMARY_CLASS_ID\n3. ISSUERID.LINKED_OBJECT_ID\n\n#### Example JSON Request to add a linked object to a pass object\n\n```carbon\n ...\n {\n \"id\": \"ISSUERID.PASS_OBJECTID\",\n \"classId\": \"ISSUERID.PASS_CLASSID\",\n \"barcode\": {\n \"type\": \"qrCode\",\n \"value\": \"QR code\"\n },\n \"linkedObjectIds\": {\"ISSUERID.LINKED_PASS_OBJECTID\"}\n }\n ...\n```\n\n#### Example JSON Response after linking an object to a pass object\n\n```scdoc\n …\n \"state\": \"active\",\n \"linkedObjectIds\": {\n \"ISSUERID.LINKED_PASS_OBJECTID\"\n }\n …\n```\n\n#### Expected behavior\n\nAfter receiving a successful response, devices with the pass you updated\nshould receive the linked pass. This linked pass will be grouped together with\nthe primary pass. Users can see the linked pass by swiping right.\n\n#### Exception handling\n\nPotential errors may happen with incorrect use of the API which can\ninclude;\n\n| **Message** | **Reason** |\n|------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Primary object and linked object don't share the same issuer ID. | You cannot attach a linked object to another issuer's object. |\n| Primary object and linked object refer to the same object. | You cannot attach the same object as the linkedObject. |\n| Linked object does not exist. | The linked object should already be inserted into the Wallet API. |\n| Linked object already has another linked object. Cannot add nested linked objects. | Linked objects cannot have another linked object. |\n| Object is already linked to another object. Cannot add nested linked objects. | Primary object cannot be a linked object by itself. |\n| Cannot add any more linked objects, limit exceeded. | The limit of 50 linked passes has been reached for the primary pass. |"]]
