자동 연결 패스
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
배경
자동 연결된 패스 기능을 사용하면 Google 월렛에 이미 기존 패스가 있는 사용자에게 패스를 추가로 보낼 수 있습니다. 사용자가 기본(기본) 패스를 저장할 때 패스를 기본 패스에 미리 연결할 수도 있습니다. 자동 연결된 패스는 기본 패스와 그룹화되며 기본 패스 위에 새 패스가 연결되었음을 알리는 콜아웃이 표시됩니다. 다음 패스 유형은 기본 패스 또는 연결된 패스로 지원됩니다.
- 이벤트 티켓
- 탑승권
- 대중교통 이용권
- 혜택
- 기프트 카드
- 포인트 패스
- 일반 패스
|
|
|
새 패스가 추가되었다는 콜아웃이 있는 기본 패스
|
기본 패스에 연결된 새 패스
|
사용 사례
패스를 기존 패스에 연결하는 데는 다양한 사용 사례가 있을 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.
- 혜택을 기존 포인트 카드에 연결합니다.
- 식사 쿠폰을 탑승권 또는 이벤트 티켓에 연결합니다.
- 주차권을 이벤트 티켓에 연결합니다.
자동 연결된 패스를 사용할 때의 몇 가지 고려사항
- 기본 객체와 연결된 객체는 동일한 발급기관 ID를 사용해야 합니다.
- 연결된 객체는 기본 객체당 50개로 제한됩니다.
- 연결된 패스를 자동으로 푸시하는 것은 보장되지 않으며 최선의 방식으로 간주됩니다. 사용자는 자동 연결된 패스를 수신하지 않도록 선택할 수 있습니다. 사용 사례가 중요하고 사용자가 연결된 패스를 수신해야 하는 경우 다른 채널을 통해 사용자에게 패스를 추가하도록 안내하는 것이 좋습니다.
- Google 월렛 AUP 업데이트에는 준수해야 하는 자동 연결된 패스 사용에 관한 안내가 포함되어 있습니다.
통합 단계
이미 기본 객체를 만든 경우에는 1단계를 건너뛸 수 있습니다.
- 필수 매개변수와 함께 나열된 패스 유형의 객체를 만듭니다. 기본 객체입니다.
- 나열된 패스 유형의 다른 객체를 만듭니다. 이 객체가 연결된 객체가 됩니다.
- 기본 객체가 저장되기 전이나 후에 linkedObjectIds 매개변수의 연결된 객체 ID로 기본 객체를 업데이트합니다.
기본 패스에서 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를 잘못 사용하면 다음과 같은 오류가 발생할 수 있습니다.
| 메시지 |
이유 |
| 기본 객체와 연결된 객체의 발급기관 ID가 동일하지 않습니다. |
연결된 객체는 다른 발급자의 객체에 연결할 수 없습니다. |
| 기본 객체와 연결된 객체가 동일한 객체를 참조합니다. |
linkedObject와 동일한 객체를 연결할 수 없습니다. |
| 연결된 객체가 존재하지 않습니다. |
연결된 객체는 이미 월렛 API에 삽입되어야 합니다. |
| 연결된 객체에 이미 다른 연결된 객체가 있습니다. 중첩된 연결된 객체를 추가할 수 없습니다. |
연결된 객체에는 다른 연결된 객체가 있을 수 없습니다. |
| 객체가 이미 다른 객체에 연결되어 있습니다. 중첩된 연결된 객체를 추가할 수 없습니다. |
기본 객체 자체가 연결된 객체일 수 없습니다. |
| 한도를 초과하여 연결된 객체를 더 이상 추가할 수 없습니다. |
기본 패스의 연결 패스 한도인 50개에 도달했습니다. |
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 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. |"]]
