개요

Google 월렛 패스 API는 파트너가 대중교통 티켓 활성화를 위한 엔드포인트를 지정할 수 있는 기능을 제공합니다. 활성화가 필요한 경우 사용자에게 '활성화' 버튼이 표시되며, 이 버튼을 탭하면 아래에 설명된 매개변수를 사용하여 지정된 엔드포인트를 호출합니다. 엔드포인트는 돌아가기 전에 패스에 유효한 사용 정보 (바코드 또는 시각적 검사)가 있는지 확인해야 합니다. 이때 사용자의 월렛의 패스가 업데이트되어 사용 정보가 표시됩니다. 활성화 전에는 기존 사용 정보가 표시되지 않습니다.

활성화 API

활성화 엔드포인트는 대중교통 클래스에서 activationOptions를 사용하여 API에서 지정됩니다. 파트너는 합당한 지연 시간으로 작동하는 활성화 엔드포인트를 유지해야 합니다.

  activationOptions: {
    activationUrl: string
  }
필드 설명
activationUrl

string

활성화 요청을 위해 호출될 파트너 엔드포인트의 URL입니다. URL은 HTTPS에서 호스팅되어야 하며 robots.txt에서 UserAgent:Google-Valuables가 URL 경로에 액세스할 수 있도록 허용해야 합니다.

활성화 상태는 activationStatus 필드를 사용하여 객체에 저장됩니다. 유효한 상태에는 NOT_ACTIVATED 및 ACTIVATED가 포함됩니다. 활성화 엔드포인트는 객체를 ACTIVATED 상태로 업데이트하고 객체에 바코드 또는 시각적 검사 매개변수와 같은 유효한 사용 정보가 있는지 확인해야 합니다. deviceContext 필드는 기기 고정에 사용할 수 있습니다.

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
필드 설명
activationStatus

enum (ActivationStatus)

이 대중교통 객체의 활성화 상태입니다. 이 상태를 통해 티켓 표현이 변경되고 사용자가 조치를 취할 수 있습니다. 예를 들어 NOT_ACTIVATED로 설정된 경우 티켓 세부정보에 활성화 버튼이 렌더링됩니다.

사용 가능한 값:

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

객체를 연결할 기기 컨텍스트입니다. 설정할 경우 사용 정보는 지정된 기기로만 반환됩니다.
hasLinkedDevice

boolean

이 객체가 현재 단일 기기에 연결되어 있는지 여부입니다.
DeviceContext
필드 설명
deviceToken

string

설정하면 객체 활성화 시에만 사용 정보가 지정된 기기로 반환됩니다. 사용자 기기를 추적하기 위한 안정적인 식별자로 사용할 수 없습니다. 동일한 기기의 여러 패스에서 또는 동일한 기기의 서로 다른 활성화 간에 변경될 수 있습니다. 이를 설정할 때 호출자는 활성화 중인 객체에 hasLinkedDevice도 설정해야 합니다.

deviceToken는 활성화 매개변수 deviceContext 필드에서 수신합니다.

기기 고정

기기 고정은 사용자가 한 기기에서 티켓을 활성화하고 해당 기기에만 티켓 사용 정보를 표시할 수 있는 기능입니다. 이는 티켓이 단일 기기에만 표시되도록 허용하는 ONE_USER_ONE_DEVICE의 multipleDevicesAndHoldersAllowedStatus과는 별개입니다. 기기 고정과 함께 ONE_USER_ALL_DEVICES 상태를 사용하는 것이 좋습니다.

활성화 전에는 사용자가 소유한 모든 기기에서 티켓을 보고 활성화 버튼을 볼 수 있습니다. 활성화되고 기기에 고정되면 고정된 기기에 사용 정보가 표시되고 다른 기기에는 사용자가 티켓을 다른 기기로 이동할 수 있는 활성화 버튼이 표시됩니다. 티켓을 이동하는 기능이 바람직하지 않지만 모든 기기에서 활성화하는 기능이 있다면 기기 고정을 사용하는 대신 활성화 중에 티켓을 ONE_USER_ONE_DEVICE로 업데이트할 수 있습니다.

기기 고정을 구현하려면 활성화 매개변수와 함께 수신한 deviceToken 필드로 객체를 업데이트해야 하며 동일한 API 호출에서 hasLinkedDevice를 true로 설정해야 합니다. 원하는 경우 향후 API 호출에서 hasLinkedDevice를 false로 설정하여 티켓을 기기에서 연결 해제할 수 있습니다.

기기 고정 시퀀스 다이어그램

활성화 매개변수

활성화 엔드포인트에 대한 요청에는 다음 매개변수가 포함됩니다.

JSON 예: 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

식별자 설명
classId

정규화된 클래스 ID입니다. 다음 형식을 사용합니다.

<issuer_id.class_id>
objectIds

다음 형식을 사용하는 정규화된 객체 ID 배열입니다.

<issuer_id.object_id>
expTimeMillis EPOCH 이후 경과한 만료 시간(밀리초)입니다. 만료 시간이 지나면 메시지가 유효하지 않은 것으로 간주해야 합니다.
eventType 항상 "activate"입니다.
nonce 중복 전송을 추적하기 위한 nonce입니다.
deviceContext

사용자가 작업을 수행하는 기기를 나타내는 Google에서 생성한 고유 ID입니다. 이 ID는 객체를 기기에 연결하는 업데이트를 실행할 때 사용되어야 합니다.

이 ID는 특정 기기의 향후 요청에 대해 일정하지 않을 수 있습니다.