نمای کلی

Google Wallet Passes API این امکان را برای شرکا فراهم می کند تا نقطه پایانی را برای فعال سازی بلیط حمل و نقل مشخص کنند. در صورت نیاز به فعال‌سازی، دکمه «فعال‌سازی» برای کاربر نمایش داده می‌شود که با ضربه زدن، نقطه پایانی مشخص شده را با پارامترهای شرح داده شده در زیر فراخوانی می‌کند. نقطه پایانی باید اطمینان حاصل کند که گذرنامه دارای اطلاعات بازخرید معتبر (اعم از بارکد یا بازرسی بصری) قبل از بازگشت است، در این مرحله مجوز در کیف پول کاربر برای نمایش اطلاعات بازخرید به‌روزرسانی می‌شود. توجه داشته باشید که قبل از فعال سازی، هرگونه اطلاعات بازخرید موجود نمایش داده نخواهد شد.

API فعال سازی

نقطه پایان فعال سازی در API با استفاده از activationOptions در کلاس حمل و نقل مشخص می شود. شریک مسئول حفظ یک نقطه پایان فعال سازی کاری با تأخیر معقول است.

  activationOptions: {
    activationUrl: string
  }

میدان	توضیحات
activationUrl	string URL برای نقطه پایانی شریک که برای درخواست‌های فعال‌سازی فراخوانی می‌شود. URL باید در HTTPS میزبانی شود و robots.txt باید اجازه دهد مسیر URL توسط UserAgent:Google-Valuables قابل دسترسی باشد.

وضعیت فعال سازی با استفاده از فیلد 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 دریافت می شود

پین کردن دستگاه

پین کردن دستگاه قابلیتی است که به کاربر امکان می دهد بلیط را در یک دستگاه فعال کند و اطلاعات بازخرید بلیط را فقط در آن دستگاه نمایش دهد. این جدا از وضعیت multipleDevicesAndHoldersAllowedStatus هولدرهای مجاز ONE_USER_ONE_DEVICE است که فقط اجازه می‌دهد بلیت در یک دستگاه نمایش داده شود. توصیه می شود از وضعیت ONE_USER_ALL_DEVICES با پین کردن دستگاه استفاده کنید.

قبل از فعال‌سازی، کاربر می‌تواند بلیت و دکمه فعال‌سازی را در هر دستگاهی که دارد ببیند. پس از فعال شدن و پین شدن به دستگاه، دستگاه پین ​​شده اطلاعات بازخرید را نشان می‌دهد و سایر دستگاه‌ها دکمه فعال‌سازی را نمایش می‌دهند تا به کاربر اجازه دهد بلیط را به دستگاه دیگری منتقل کند. اگر جابه‌جایی بلیت عملکرد مطلوبی ندارد، اما فعال‌سازی در هر دستگاهی انجام می‌شود، می‌توانید به‌جای استفاده از پین کردن دستگاه، بلیت را در حین فعال‌سازی به ONE_USER_ONE_DEVICE به‌روزرسانی کنید.

برای پیاده‌سازی پین کردن دستگاه، شی باید با فیلد deviceToken که با پارامترهای فعال‌سازی دریافت می‌شود و همچنین در همان فراخوانی API hasLinkedDevice روی true تنظیم کنید. در صورت تمایل، با تنظیم hasLinkedDevice روی false در تماس API آینده، بلیت را می توان از دستگاهی جدا کرد.

پارامترهای فعال سازی

درخواست به نقطه پایانی فعال سازی شامل پارامترهای زیر خواهد بود.

مثال JSON:

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

شناسه	توضیحات
classId	شناسه کلاس کاملاً واجد شرایط از فرمت زیر استفاده می کند: <issuer_id.class_id>
objectIds	آرایه کاملاً واجد شرایط شناسه شی که از فرمت زیر استفاده می کنند: <issuer_id.object_id>
expTimeMillis	زمان انقضا بر حسب میلی ثانیه از زمان EPOCH. پس از اتمام زمان، پیام باید نامعتبر تلقی شود.
eventType	همیشه "activate" .
nonce	برای ردیابی هر گونه تحویل تکراری وجود ندارد.
deviceContext	شناسه منحصربه‌فردی که توسط Google تولید می‌شود و نشان‌دهنده دستگاهی است که کاربر روی آن اقدام می‌کند. این شناسه باید هنگام به‌روزرسانی‌هایی استفاده شود که یک شی را به دستگاه متصل می‌کند. ممکن است این شناسه برای درخواست‌های آینده از یک دستگاه مشخص ثابت نباشد.