배경
자동 연결된 패스 기능을 사용하면 Google 월렛에 이미 기존 패스가 있는 사용자에게 패스를 추가로 보낼 수 있습니다. 사용자가 기본(메인) 패스를 저장할 때 패스를 기본 패스에 미리 연결할 수도 있습니다. 자동 연결된 패스는 기본 패스와 그룹화되며 기본 패스 위에 새 패스가 연결되었음을 알리는 콜아웃이 표시됩니다. 다음 패스 유형은 기본 패스 또는 연결된 패스로 지원됩니다.
- 이벤트 티켓
- 탑승권
- 대중교통 이용권
- 혜택
- 기프트 카드
- 포인트 패스
- 일반 패스
|
|
| 새 패스가 추가되었다는 콜아웃이 있는 기본 패스 | 기본 패스에 연결된 새 패스 |
사용 사례
패스를 기존 패스에 연결하는 데는 다양한 사용 사례가 있을 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.
- 혜택을 기존 포인트 카드에 연결합니다.
- 식사 쿠폰을 탑승권 또는 이벤트 티켓에 연결합니다.
- 주차권을 이벤트 티켓에 연결합니다.
자동 연결된 패스를 사용할 때의 몇 가지 고려사항
- 기본 객체와 연결된 객체는 동일한 issuerId를 사용해야 합니다.
- 기본 객체당 연결된 객체는 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개에 도달했습니다. |