Google 월렛의 Motics 티켓 기술 세부정보

이 페이지에서는 대중교통 사업자 (PTO) 및 시스템 통합업체가 Google과 통합하여 Motics 티켓을 제공해야 함 Google 월렛에서 사용할 수 있습니다. 이 솔루션은 Google Wallet API를 사용하며 활성화 엔드포인트를 구현하는 PTO

시스템 아키텍처

이 섹션에서는 시스템 아키텍처와 Motics 저장 흐름을 보여줍니다.

Motics 티켓 저장 흐름그림 1. Motics 티켓 저장 흐름

그림 1은 다음에서 Motics 티켓을 생성, 활성화, 고정하는 흐름을 보여줍니다. 여러 법인에서 사용할 수 있는 Google 월렛:

  • Google 서버
  • PTO (System Integrator) 서버
  • Motics SCE 서버
  • 웹 매장

다음은 흐름을 자세히 설명합니다.

  1. 초기 설정 단계에서 PTO 서버는 transitClass를 만듭니다. transitClass:Insert를 사용하여 ownerId 및 activationUrl 전달 Google Wallet API 엔드포인트 일회성 활동입니다.
  2. 다음으로 사용자가 웹 상점에서 티켓을 구매하면 PTO 서버는 transitObject:Insert에는 기본 티켓 판매 정보와 일부 정보가 포함되어 있습니다. 이 Motics 티켓임을 나타내는 초기 필드입니다.
  3. 그런 다음 PTO 서버와 웹샵이 함께 작동하여 Google 월렛에 추가 버튼 및 최종적으로 티켓의 JWT를 Google에서 저장 링크를 사용합니다.
  4. 이제 Google 서버가 activationUrl 뒤의 활성화 엔드포인트.
  5. 4단계에 대한 응답으로 PTO 서버는 서명 (sigSTB)을 생성합니다. 여기에는 SAM으로 서명된 SCE_ID가 포함됩니다.
  6. activationUrl 호출에 응답하기 전에 PTO 서버가 먼저 필요한 모든 Motics 정보가 포함된 transitObject:Patch를 호출합니다. Motics applicationData가 포함됩니다.
  7. transitObject:Patch 호출이 성공한 후에만 PTO 서버가 activationUrl에 성공 (HTTP-200) 응답을 반환해야 합니다. 있습니다.

우수한 사용자 환경을 제공하려면 사용자가 Motics를 이동할 수 있어야 합니다. 티켓을 다른 기기로 전송하는 데 사용할 수 있습니다. 이를 위해 발급기관에서 이동 및 연결 해제 흐름을 구현해야 합니다.

활성화 엔드포인트

발급기관/PTO (또는 시스템 통합업체)가 티켓을 구현해야 합니다. 활성화 엔드포인트이며 티켓이 저장되면 Google에서 호출합니다. URL transitClass:Insert 호출에 제공되어야 합니다. 활성화 엔드포인트는 서명 (sigSTB)을 생성하고 transitObject:Patch 메서드 섹션으로 이동합니다.

요청

활성화 엔드포인트에 대한 요청의 형식은 다음과 같습니다.

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

응답

다음과 같은 경우 본문이 비어 있는 HTTP-200 성공 응답이 반환되어야 합니다.

  • SCE_ID가 포함된 sigSTB가 생성되고 SAM으로 서명됨
  • transferObject:Patch 메서드가 성공적으로 호출되었습니다.
Status: 200 - OK
Body: {}

지연 시간 목표

활성화 엔드포인트는 다음 지연 시간 목표를 준수해야 합니다.

  • 모든 요청의 50% 이상이 200ms 이내에 응답해야 합니다.
  • 모든 요청의 95% 이상이 2s 이내에 응답해야 합니다.
  • 10s의 엄격한 상한선은 다음과 같습니다.

Google Wallet API 변경사항

다음은 Google Wallet API 엔드포인트의 변경사항을 요약한 내용입니다. 시스템 아키텍처에 설명된 대로 Motics를 지원해야 합니다.

메서드: transitClass:insert

Google 월렛에서 transitClass을(를) 만드는 Google Wallet API 엔드포인트입니다. 사용할 수 있습니다 시스템 통합자는 다음을 사용하여 이 API를 호출해야 합니다. 요청 매개변수와 적용 가능한 다른 모든 필드를 함께 제공합니다. 다음을 참고하세요. transitClass 및 transitClass.Insert API 문서를 참조하세요. (비모틱) 매개변수 및 세부정보

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

JSON 표현

Motics 통합에는 최소한 다음과 같은 JSON 표현이 필요합니다. transitClass:insert 요청 본문의 transitClass 기타 필수 항목 transitClass 메타데이터 필드도 설정해야 합니다.

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

certEnvironment = PRODUCTION인 경우 Google 서버가 인증서를 가져옵니다. 컨테이너 이미지를 가져올 수 있습니다 certEnvironment = Google 샌드박스 Motics 서버에서 인증서를 가져옵니다.

메서드: transferObject:insert

새transitObject Google 월렛에 추가하려고 하는 티켓입니다. 시스템 통합자는 주로 티켓 정보가 포함된 transitObject를 전달해야 합니다. 확인할 수 있습니다. transitObject 및 transitObject.Insert API 문서를 참조하세요.

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitObject

JSON 표현

Motics 통합에는 최소한 다음과 같은 JSON 표현이 필요합니다. transitObject:insert 요청 본문의 transitObject 기타 객체 metadata 필드도 설정할 수 있으며 다른 모든 필수 필드도 포함됩니다.

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

참고:

  • API를 사용하려면 applicationData 필드가 포함되어야 합니다. 이 시점에서 Motics 활성화 흐름에서 applicationData 값은 아직 알려지지 않았습니다. 따라서 빈 문자열로 설정해야 합니다
    • applicationData는 나중에 transitObject:Patch에서 설정됩니다. 있습니다.
  • validTimeInterval DateTime 객체에는 시간대 오프셋이 있어야 합니다. 지정(예: 2024-04-12T19:20:50.52-04:00)

메서드: transitObject:patch

다음 데이터로 transitObject를 패치할 Google Wallet API 엔드포인트입니다. Motics 바코드 생성 및 VDV eTicket Service 가져오기에 Google에서 사용 있습니다 transitObject 및 transitObject.Patch API 문서를 참조하세요.

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

JSON 표현

Motics 통합에는 transitObject:patch 요청 본문의 transitObject Note that is on this applicationData 필드가 채워지는 시점입니다.

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

애플리케이션 데이터 사양

다음은 applicationData (태그:0x5F07) applicationData는 다음과 같이 생성되어야 합니다. 태그-길이-값 (TLV) 형식의 시스템 통합업체입니다. 나중에 더 큰 데이터 구조로 캡슐화되어 최종적으로 QR 코드 내의 일부로 인코딩됩니다. 있습니다.

태그 길이 값
0x9E 81 80 서명
OctetString, 서명된 사용 권한 데이터의 처음 128바이트
Google 검색어: sigSTB
0x9A 경우에 따라 다름 잔여 데이터
OctetString, 잔여 사용 권한 데이터
Google 검색어: sigSTB cont.
0x7F21 81 C8 발급 인증서
OctetString, 인증서 데이터
Google 검색어: Cert(puk_SAM)
0x42 08 인증 기관 참조 (CAR)
OctetString, CAR 금액
Google 검색어: CAR