جزئیات فنی بلیط های Motics در Google Wallet

این صفحه جزئیات فنی را ارائه می دهد که یک اپراتور حمل و نقل عمومی (PTO) و یکپارچه کننده سیستم آنها باید با Google ادغام شوند تا بلیط های Motics را در Google Wallet ارائه دهند. این راه حل از Google Wallet API استفاده می کند و همچنین به PTO که یک نقطه پایانی فعال سازی را پیاده سازی می کند، متکی است.

معماری سیستم

این بخش معماری سیستم و جریان ذخیره Motics را نشان می دهد.

شکل 1. Motics Ticket Save Flow

شکل 1 جریان ایجاد، فعال سازی و پین کردن بلیط Motics در Google Wallet را در چندین نهاد نشان می دهد:

• سرورهای گوگل
• سرور PTO (System Integrator).
• سرور Motics SCE
• فروشگاه اینترنتی

در زیر این جریان با جزئیات بیشتری توضیح داده شده است:

1. در مرحله راه‌اندازی اولیه، سرور PTO transitClass ایجاد می‌کند و ownerId و activationUrl با استفاده از transitClass:Insert Google Wallet API پایان می‌دهد. این یک فعالیت یکباره است.
2. در مرحله بعد، زمانی که کاربر بلیطی را از فروشگاه اینترنتی خریداری می کند، سرور PTO ، transitObject:Insert را که حاوی اطلاعات اولیه بلیط و برخی فیلدهای اولیه است که نشان می دهد این بلیط Motics است، فرا می خواند.
3. سپس سرور PTO و فروشگاه وب با هم کار می کنند تا دکمه Add to Google Wallet را ارائه دهند و در نهایت JWT بلیط را با استفاده از پیوند ذخیره به Google برگردانند.
4. اکنون مرحله پین ​​کردن بلیط می تواند آغاز شود، زمانی که سرور Google نقطه پایان فعال سازی را در پشت activationUrl فراخوانی می کند.
5. در پاسخ به مرحله 4، سرور PTO امضا (sigSTB) حاوی SCE_ID امضا شده با SAM را تولید می کند.
6. قبل از پاسخ دادن به تماس activationUrl ، سرور PTO باید ابتدا transitObject:Patch حاوی تمام اطلاعات Motics لازم، از جمله Motics applicationData را فراخوانی کند.
7. تنها پس از موفقیت آمیز بودن فراخوان transitObject:Patch ، سرور PTO باید یک پاسخ موفقیت آمیز (HTTP-200) را به تماس activationUrl بازگرداند.

جریان انتقال و لغو پیوند را اجرا کنید

برای ارائه یک تجربه کاربری خوب، یک کاربر باید بتواند بلیط Motics خود را از یک دستگاه به دستگاه دیگر، در محدوده های مشخصی که توسط صادرکننده تعریف شده است، منتقل کند. برای این کار، صادرکننده باید Move and Unlink Flow را پیاده سازی کند.

نقطه پایانی فعال سازی

صادرکننده/PTO (یا یکپارچه‌کننده سیستم آنها) باید یک نقطه پایانی فعال‌سازی بلیط را پیاده‌سازی کند که Google هنگام ذخیره بلیط از آن فراخوانی می‌کند. URL این نقطه پایانی باید در فراخوانی transitClass:Insert ارائه شود. نقطه پایانی فعال‌سازی، امضا (sigSTB) را تولید می‌کند و متد transitObject:Patch را با پارامترهای تعریف‌شده در بخش زیر فراخوانی می‌کند.

مهم: سرور PTO (یکپارچه ساز سیستم) باید 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 با بدنه خالی، باید برگردانده شود اگر:

• sigSTB حاوی SCE_ID تولید و با SAM امضا شد
• متد transitObject:Patch با موفقیت فراخوانی شد

Status: 200 - OK
Body: {}

اهداف تأخیر

نقطه پایانی فعال سازی باید به اهداف تأخیر زیر پایبند باشد:

• حداقل 50% از تمام درخواست ها باید در عرض 200ms پاسخ داده شود
• حداقل 95% از تمام درخواست ها باید در عرض 2s پاسخ داده شود
• حد بالایی سخت 10s وجود دارد

تغییرات API Google Wallet

در زیر تغییرات در نقاط پایانی API Google Wallet به منظور پشتیبانی از Motics همانطور که در معماری سیستم ذکر شده است، توضیح داده شده است.

مهم: موارد زیر فرض می‌کند که قبلاً یکپارچه‌سازی استاندارد Google Wallet API را تکمیل کرده‌اید. فقط به روز رسانی ها و تغییرات در نقاط پایانی برای پشتیبانی از Motics در اینجا نشان داده شده است.

روش: transitClass:insert

این نقطه پایانی Google Wallet API برای ایجاد transitClass در باطن Google است. یکپارچه ساز سیستم باید این API را با پارامترهای درخواستی زیر به همراه هر فیلد دیگری که قابل اجرا است فراخوانی کند. برای فهرست کامل پارامترهای (غیر Motics) و جزئیات بیشتر، به transitClass & transitClass مراجعه کنید. اسناد API را درج کنید.

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

نمایندگی JSON

ادغام Motics حداقل به نمایش JSON زیر از transitClass در بدنه درخواست transitClass:insert نیاز دارد. سایر فیلدهای فراداده اجباری transitClass نیز باید تنظیم شوند.

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

وقتی certEnvironment = PRODUCTION، سرور Google گواهی را از سرور Motics تولیدی دریافت می کند. وقتی certEnvironment = STAGING سرور Google گواهی را از سرور sandbox Motics دریافت می کند.

روش: transitObject:insert

این نقطه پایانی Google Wallet API برای درج transitObject برای بلیط جدیدی است که کاربر می‌خواهد بخرد و به Google Wallet اضافه کند. یکپارچه ساز سیستم باید یک transitObject با اطلاعات بلیط در این نقطه ارسال کند. برای لیست کامل پارامترهای (غیر Motics) و جزئیات بیشتر، به اسناد transitObject و transitObject.Insert API مراجعه کنید.

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

نمایندگی JSON

ادغام Motics حداقل به نمایش JSON زیر از transitObject در بدنه درخواست transitObject:insert نیاز دارد. سایر فیلدهای فراداده شی نیز ممکن است تنظیم شوند و تمام فیلدهای اجباری دیگر نیز باید گنجانده شوند.

{
  "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

این نقطه پایانی Google Wallet API برای وصله کردن transitObject با داده‌هایی است که توسط Google برای تولید بارکد Motics و واکشی گواهی‌های VDV eTicket Service استفاده می‌شود. برای لیست کامل پارامترهای (غیر Motics) و جزئیات بیشتر به مستندات transitObject و transitObject.Patch API مراجعه کنید.

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

نمایندگی JSON

ادغام Motics به نمایش زیر از transitObject در بدنه درخواست transitObject:patch نیاز دارد. توجه داشته باشید که در این مرحله است که فیلد applicationData پر می شود.

نکته: نقطه پایانی transitObject:patch از معنای پچ پشتیبانی می‌کند، بنابراین کافی است در هنگام فراخوانی وصله، اطلاعات خاص Motics زیر را شامل شود.

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

مشخصات داده های کاربردی

در زیر مشخصات Motics برای محتویات applicationData (برچسب: 0x5F07 ) آمده است. applicationData باید توسط یکپارچه ساز سیستم در قالب برچسب طول-مقدار (TLV) تولید شود. این داده ها بعداً در یک ساختار داده بزرگتر کپسوله می شوند تا در نهایت به عنوان بخشی از کد QR کدگذاری شوند.

برچسب بزنید	طول	ارزش
0x9E	81 80	امضا OctetString ، 128 بایت اول داده های حق امضا شده اصطلاح گوگل: sigSTB
0x9A	متفاوت است	داده های باقی مانده OctetString ، داده های حق باقی مانده اصطلاح گوگل: sigSTB cont.
0x7F21	81 C8	گواهی صدور OctetString ، داده های گواهی اصطلاح Google: Cert(puk_SAM)
0x42	08	مرجع مرجع صدور گواهی (CAR) OctetString ، مقدار CAR اصطلاح گوگل: CAR