배경
자동 연결 패스 기능을 사용하면 Google 월렛에 기존 패스가 있는 사용자에게 추가 패스를 보낼 수 있습니다. 사용자가 기본 패스를 저장할 때 패스를 기본 패스에 미리 연결할 수도 있습니다. 자동 연결된 패스는 기본 패스와 함께 그룹화되며, 기본 패스 위에 사용자에게 새 패스가 연결되었음을 알리는 콜아웃이 포함되어 있습니다. 다음 패스 유형은 기본 또는 연결된 패스로 지원됩니다.
- 이벤트 티켓
- 탑승권
- 교통카드
- 제안
- 기프트 카드
- 포인트 패스
- 일반 패스
|
|
| 새 패스가 추가되었다는 콜아웃이 있는 기본 패스 | 기본 패스에 연결된 새 패스 |
사용 사례
패스를 기존 패스에 연결하는 사용 사례가 다를 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.
- 혜택을 기존 포인트 카드에 연결합니다.
- 식사 쿠폰을 탑승권이나 이벤트 티켓에 연결하세요.
- 이벤트 티켓에 주차권을 연결합니다.
자동 연결 패스 사용 시 고려사항
- 기본 객체와 연결된 객체는 동일한 발급기관 ID를 사용해야 합니다.
- 연결된 객체는 기본 객체당 50개로 제한됩니다.
- 연결된 패스를 자동으로 푸시하는 것은 보장되지 않으며 최선의 노력으로 간주됩니다. 사용자는 자동 연결 패스 수신을 거부할 수 있습니다. 사용 사례가 중요하고 사용자가 연결된 패스를 수신해야 하는 경우 다른 채널을 통해 통신하여 사용자가 패스를 추가하도록 하는 것이 좋습니다.
- Google 월렛 AUP 업데이트에는 준수해야 하는 자동 연결 패스의 사용에 대한 안내가 포함되어 있습니다.
통합 단계
이미 기본 객체를 만든 경우 1단계를 건너뛰어도 됩니다.
- 필수 매개변수와 함께 나열된 모든 패스 유형의 객체를 만듭니다. 기본 객체입니다.
- 나열된 패스 유형의 다른 객체를 만듭니다. 이 객체가 linked 객체가 됩니다.
- 기본 객체를 저장하기 전이나 후에 기본 객체를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를 공유하지 않습니다. | 연결된 객체는 다른 발급기관의 객체에 연결할 수 없습니다. |
| 기본 개체와 연결된 개체는 동일한 개체를 참조합니다. | linkObject와 동일한 객체를 연결할 수 없습니다. |
| 연결된 객체가 없습니다. | 연결된 객체가 이미 Wallet API에 삽입되어 있어야 합니다. |
| 연결된 객체에 이미 다른 연결된 객체가 있습니다. 중첩된 연결된 객체는 추가할 수 없습니다. | 연결된 객체에는 다른 연결된 객체가 있을 수 없습니다. |
| 객체가 이미 다른 객체에 연결되어 있습니다. 중첩된 연결된 객체는 추가할 수 없습니다. | 기본 객체 자체는 연결된 객체일 수 없습니다. |
| 한도를 초과하여 연결된 객체를 더 이상 추가할 수 없습니다. | 기본 패스의 연결된 패스 한도인 50개에 도달했습니다. |