자동 연결 패스

배경

자동 연결된 패스 기능을 사용하면 Google 월렛에 이미 기존 패스가 있는 사용자에게 패스를 추가로 보낼 수 있습니다. 사용자가 기본(기본) 패스를 저장할 때 패스를 기본 패스에 미리 연결할 수도 있습니다. 자동 연결된 패스는 기본 패스와 그룹화되며 기본 패스 위에 새 패스가 연결되었음을 알리는 콜아웃이 표시됩니다. 다음 패스 유형은 기본 패스 또는 연결된 패스로 지원됩니다.

  • 이벤트 티켓
  • 탑승권
  • 대중교통 이용권
  • 혜택
  • 기프트 카드
  • 포인트 패스
  • 일반 패스
자동 연결된 패스 기본 예 자동 연결된 패스 보조 예
새 패스가 추가되었다는 콜아웃이 있는 기본 패스 기본 패스에 연결된 새 패스

사용 사례

패스를 기존 패스에 연결하는 데는 다양한 사용 사례가 있을 수 있습니다. 몇 가지 예를 들면 다음과 같습니다.

  • 혜택을 기존 포인트 카드에 연결합니다.
  • 식사 쿠폰을 탑승권 또는 이벤트 티켓에 연결합니다.
  • 주차권을 이벤트 티켓에 연결합니다.

자동 연결된 패스를 사용할 때의 몇 가지 고려사항

  • 기본 객체와 연결된 객체는 동일한 발급기관 ID를 사용해야 합니다.
  • 연결된 객체는 기본 객체당 50개로 제한됩니다.
  • 연결된 패스를 자동으로 푸시하는 것은 보장되지 않으며 최선의 방식으로 간주됩니다. 사용자는 자동 연결된 패스를 수신하지 않도록 선택할 수 있습니다. 사용 사례가 중요하고 사용자가 연결된 패스를 수신해야 하는 경우 다른 채널을 통해 사용자에게 패스를 추가하도록 안내하는 것이 좋습니다.
  • Google 월렛 AUP 업데이트에는 준수해야 하는 자동 연결된 패스 사용에 관한 안내가 포함되어 있습니다.

통합 단계

이미 기본 객체를 만든 경우에는 1단계를 건너뛸 수 있습니다.

  1. 필수 매개변수와 함께 나열된 패스 유형의 객체를 만듭니다. 기본 객체입니다.
  2. 나열된 패스 유형의 다른 객체를 만듭니다. 이 객체가 연결된 객체가 됩니다.
  3. 기본 객체가 저장되기 전이나 후에 linkedObjectIds 매개변수의 연결된 객체 ID로 기본 객체를 업데이트합니다.

기본 패스에서 linkedObjectIds를 설정하는 데 필요한 최소 페이로드가 있습니다. 3가지 필수 매개변수는 다음과 같습니다.

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. 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개에 도달했습니다.