إضافات تذاكر Google Transit

تحدّد هذه الصفحة مجموعة فرعية من مواصفات تذاكر GTFS، التي تكون في مرحلة الاقتراح أثناء إنشاء هذا المستند. تتضمّن هذه الصفحة أيضًا عدة قيود إضافية من Google.

المتطلبات

يجب ملء الحقل departure_time في stop_times.txt.

أنواع حقول إضافية

ويوضّح هذا القسم أنواع الحقول الإضافية وتلك التي لها إضافات من Google. وتتطلّب بعض الحقول قيمًا في شكل معرّف موارد منتظم (URI).

  • معرّف الموارد المنتظم (URI): معرّف موارد منتظم (URI) مؤهَّل بالكامل يتضمن المخطط. يجب أن تستخدم أي أحرف خاصة في معرّف الموارد المنتظم (URI) أحرف إلغاء صحيحة. للحصول على وصف حول كيفية إنشاء قيم معرّف الموارد المنتظم (URI) المؤهّلة بالكامل، يمكنك الاطّلاع على معرّف الموارد المنتظم (URI) للمعيار RFC 3986: البنية العامة.

امتدادات الملفات أو إضافاتها

الملفات النصية بالحالة إضافة هي ملفات متوفّرة حاليًا وعليك تمديدها. وعليك إضافة الحقول الجديدة التي نحدّدها في الجدول التالي.

الملفات النصية بالحالة إضافة هي ملفات جديدة تقدّمها إضافات تذاكر Google Transit. عليك إنشاء هذه الملفات وفقًا لتعريفات الحقول التي تم تقديمها بعد الجدول التالي. تأكّد من تضمين هذه الملفات في خلاصتك.

اسم الملف الحالة التعريف
agency.txt الإضافة تتم إضافة agency.ticketing_deep_link_id.
routes.txt الإضافة تتم إضافة routes.ticketing_deep_link_id.
trips.txt الإضافة يضيف trips.trip_ticketing_id وtrips.ticketing_type.
stop_times.txt الإضافة تتم إضافة stop_times.ticketing_type.
ticketing_identifiers.txt الجمع ملف جديد لمعرفة مزيد من التفاصيل، يُرجى الاطِّلاع على تعريفات الحقول.
ticketing_deep_links.txt الجمع ملف جديد لمعرفة مزيد من التفاصيل، يُرجى الاطِّلاع على تعريفات الحقول.

تعريفات الحقول

agency.txt (تم تمديد الملف)

اسم الحقل التواجد في المنزل التفاصيل
ticketing_deep_link_id عنصر اختياري

(رقم التعريف من ticketing_deep_links.txt) يحدّد الرابط لصفحة معيّنة الذي يجب استخدامه لهذه الوكالة. يمكن استبداله في routes.txt.

routes.txt (تم تمديد الملف)

اسم الحقل التواجد في المنزل التفاصيل
ticketing_deep_link_id عنصر اختياري (رقم التعريف من ticketing_deep_links.txt) يحدّد الرابط لصفحة معيّنة الذي يجب استخدامه لهذا المسار. في حال توفّره، يتم استبدال الحقل في agency.txt.

trips.txt (تم تمديد الملف)

اسم الحقل التواجد في المنزل التفاصيل
ticketing_trip_id عنصر اختياري

(رقم التعريف) رقم التعريف الذي يتطلّب التمرير في الرابط لصفحة في التطبيق ولا يُشترط أن يكون فريدًا.

إذا كانت السياسة ticketing_trip_id فارغة، يستخدم النظام قيمة trip_id بدلاً من ذلك.
ticketing_type عنصر اختياري

(Enum) حدّد ما إذا كانت إمكانية بيع التذاكر من خلال رابط لصفحة في التطبيق متاحة لهذه الرحلة:

  • 0 أو فارغ:
    • وإذا حدّدت ticketing_deep_link_id للمسار أو الوكالة، ستكون هذه السمة متاحة.
    • غير متاح بخلاف ذلك.
  • 1: غير متوفر

stop_times.txt (تم تمديد الملف)

اسم الحقل التواجد في المنزل التفاصيل
ticketing_type عنصر اختياري

(Enum) يحدّد ما إذا كانت إمكانية بيع التذاكر من خلال رابط لصفحة في التطبيق متاحة لوقت الإيقاف هذا. في حال تحديد السمة stop_times.ticketing_type، يؤدي ذلك إلى إلغاء القيمة المحدّدة في trip.ticketing_type.

  • فارغة: تستخدم القيمة من trip.ticketing_type.
  • 0:
    • وإذا حدّدت ticketing_deep_link_id للمسار أو الوكالة، ستكون هذه السمة متاحة.
    • غير متاح بخلاف ذلك.
  • 1: غير متوفر

ticketing_identifiers.txt (تمت إضافة الملف)

والحالة الأكثر شيوعًا لبيع التذاكر هي أنّ كل محطة تتضمّن معرّفًا لمعالجة الفوترة. قد تستخدم وكالات مختلفة المعرّف نفسه لأي محطة معيّنة. وعند وصول وكالات متعددة إلى المحطة نفسها، كرِّر عملية الربط هذه لكل وكالة.

اسم الحقل التواجد في المنزل التفاصيل
ticketing_stop_id مطلوب (رقم التعريف) يُعرِّف رقم تعريف التذاكر التلقائي لهذه المحطة.
stop_id مطلوب (رقم التعريف من stops.txt)، هو المحطة التي يتمّ فيها تحديد السمة ticketing_stop_id التلقائية.
agency_id مطلوب (رقم التعريف من agency.txt): وكالة المحطة التي تمّ تحديد السمة التلقائية ticketing_stop_id لها.

ticketing_deep_links.txt (تمت إضافة الملف)

اسم الحقل التواجد في المنزل التفاصيل
ticketing_deep_link_id مطلوب (رقم التعريف) يُعرِّف رقم تعريف للرابط لصفحة في التطبيق.
web_url عنصر اختياري

(عنوان URL) لزيارة عنوان URL للربط بصفحة معيّنة

لا يمكن ترجمة هذا الحقل من خلال translations.txt.
android_intent_uri عنصر اختياري

(معرّف الموارد المنتظم (URI)) الذي سيتم تمريره إلى تطبيق Android أصلي مع هدف android.intent.action.VIEW.

إذا كان الحقل فارغًا، يعني هذا أنّه لا يمكنك الربط بصفحة معيّنة بتطبيق Android محلي.

لمزيد من المعلومات حول الروابط لصفحات في التطبيق على أجهزة Android، يُرجى الاطّلاع على إنشاء روابط لصفحات معيّنة في محتوى التطبيق.

لا يمكن ترجمة هذا الحقل من خلال translations.txt.
ios_universal_link_url عنصر اختياري

(عنوان URL) لعنوان URL للرابط العام لاستدعاءه في iOS.

في حال ترك هذا الحقل فارغًا، لن يتم عرض الربط بصفحة معيّنة على نظام التشغيل iOS.

للحصول على مزيد من المعلومات، يُرجى الاطّلاع على الروابط العامة على نظام التشغيل iOS.

لا يمكن ترجمة هذا الحقل من خلال translations.txt.

العناصر النائبة للحقل في طلب البيانات من واجهة برمجة التطبيقات

يستدعي محرّك بحث Google عناوين URL المحدّدة في السمة ticketing_deep_links.txt مع المعلَمات التالية:

اسم الحقل التفاصيل
service_date

(التاريخ، متكرر) يوم الخدمة للرحلة.

استخدِم هذا الحقل للتاريخ الذي تغادر فيه الرحلة من محطتها الأولى.

يتم تنسيق هذا الحقل كمصفوفة JSON.
ticketing_trip_id

(رقم تعريف من trips.txt، رقم تعريف قابل للتكرار).

يتم تنسيق هذا الحقل كمصفوفة JSON.
from_ticketing_stop_time_id

(قابل للتكرار) معرّف stop_time الذي تبدأ فيه الساق.

بالنسبة إلى وقت إيقاف معيّن، تكون القيمة هي:

  • السمة ticketing_stop_id المحدّدة في ticketing_identifiers.txt للسمة agency_id وstop_id للسمة stop_time.

  • في حالات أخرى، يتراجع النظام إلى stop_sequence.

يتم تنسيق هذا الحقل كمصفوفة JSON.
to_ticketing_stop_time_id

(قابل للتكرار) معرّف stop_time الذي تنتهي فيه الساق.

للحصول على شرح حول اشتقاق القيمة، يمكنك الاطّلاع على from_ticketing_stop_time_id.

يتم تنسيق هذا الحقل كمصفوفة JSON.
boarding_time

(ISO 8601، قابل للتكرار)، وقت المغادرة، departure_time، من stop_time تبدأ فيه الساق.

استخدِم هذا الحقل للتاريخ والوقت الفعليَين لصعود الراكب إلى المركبة.

تتوافق القيمة الزمنية لهذا الحقل مع ISO 8601 مع تنسيق السلسلة التالي:

YYYY-MM-DDThh:mm:ss±hh:mm

جميع الأوقات أدناه هي نفسها، وفي مناطق زمنية مختلفة:

  • في لندن، المملكة المتحدة: 2019-07-29T18:26:00+01:00
  • في نيويورك، الولايات المتحدة-نيويورك: 2019-07-29T13:26:00-04:00
  • في طوكيو، اليابان: 2019-07-30T02:26:00+09:00

يتم تنسيق هذا الحقل كمصفوفة JSON.
arrival_time

(ISO 8601، قابل للتكرار)، وقت الوصول، ووقت_الوصول عند وقت_النهاية عند الساق.

تتوافق القيمة الزمنية لهذا الحقل مع ISO 8601 بتنسيق السلسلة التالي:

YYYY-MM-DDThh:mm:ss±,hh:mm

جميع الأوقات أدناه هي نفسها، وفي مناطق زمنية مختلفة:

  • في لندن، المملكة المتحدة: 2019-07-29، الساعة 18:46:00+01:00
  • في نيويورك، الولايات المتحدة-نيويورك: 2019-07-29T13:46:00-04:00
  • في طوكيو، اليابان: 2019-07-30T02:46:00+09:00

يتم تنسيق هذا الحقل كمصفوفة JSON.

أمثلة

في هذا المثال، ما يلي بأرجل الركّاب:

  • في تاريخ الخدمة 20190716، يبدأ معرّف تذكرة الرحلة ti1 من معرّف التذكرة بوقت التوقّف 11 لإيقاف رقم التعريف الخاص بحجز التذاكر 12. يركب الراكب الساعة 2:00 بعد الظهر بالتوقيت العالمي المُنسّق ويصل إلى الساعة 2:50 بعد الظهر بالتوقيت العالمي المُنسّق.
  • في تاريخ الخدمة 20190716، يبدأ معرّف تذكرة الرحلة ti2 من معرّف التذكرة بوقت التوقّف 21 لإيقاف رقم التعريف الخاص بحجز التذاكر 22. يركب الراكب الساعة 3:00 بعد الظهر بالتوقيت العالمي المُنسّق ويصل في الساعة 3:50 بعد الظهر بالتوقيت العالمي المُنسّق.

على سبيل المثال، web_url هو https://examplepetstore.com.

استنادًا إلى كل هذه المعلومات، استخدِم القيم التالية لمعلّمات الخلاصة لهذه الرحلة:

اسم الحقل التفاصيل
service_date ["20190716"، "20190716"]
ticketing_trip_id ["ti1"، "ti2"]
from_ticketing_stop_time_id ["11"، "21"]
to_ticketing_stop_time_id ["12"، "22"]
boarding_time ["2019-07-16T14:00:00+00:00"، "2019-07-16T15:00:00+00:00"]
arrival_time ["2019-07-16T14:50:00+00:00"، "2019-07-16T15:50:00+00:00"]

في ما يلي معرّف الموارد المنتظم (URI) النهائي بعد الترميز:

https://examplepetstore.com?service_date=%5B%2220190716%22,%2220190716%22%5D &ticketing_trip_id=%5B%22ti1%22,%22ti2%22%5D&from_ticketing_stop_time_id=%5B%2211%22,%2221%22%5D &to_ticketing_stop_time_id=%5B%2212%22,%2222%22%5D&boarding_time=%5B%222019-07-16T14:00:00%2B00:00 %22,%222019-07-16T15:00:00%2B00:00%22%5D&arrival_time=%5B%222019-07-16T14:50:00%2B00:00 %22,%222019-07-16T15:50:00%2B00:00%22%5D

أمثلة على قيم ticketing_stop_id مختلفة

يمكن استخدام معرّفات مختلفة للمحطات لأغراض بيع التذاكر باستخدام الحقل ticketing_identifiers.txt. القيم التي تظهر بالخط الغامق هي تلك الموجودة في مكالمة الويب الموضّحة بعد الملفات.

stop.txt

stop_id،stop_name

si1، "باريس غار دو ليون"

si2، "ليون بار ديو"
routes.txt

route_id،route_long_name،ticketing_deep_link_id

ri1,"TGV inOui London-Lyon",tdl1
trips.txt

trip_id،service_id،route_id،trip_short_name، ticketing_trip_id

ti1,everyday,ri1,"TGV INOUI 6603",FR_SNCF_6603

ti2,everyday,ri1,"TGV INOUI 6681",FR_SNCF_6681

ti3,everyday,ri1,"TGV INOUI 6607",FR_SNCF_6607
stop_times.txt

trip_id،stop_sequence،stop_id،arrival_time، departure_time

ti1،1،si1،06:59:00،06:59:00

ti1,2,si2,08:56:00,08:56:00

ti2,1,si1,07:53:00,07:53:00

ti2,2,si2,10:00:00,10:00:00

ti3,1,si1,08:59:00,08:59:00

ti3,2,si2,10:56:00,10:56:00
ticketing_identifiers.txt

stop_id،agency_id،ticketing_stop_id

si1,agency1,4924

si2,agency1,4676
ticketing_deep_links.txt

ticketing_deep_link_id، web_url، android_intent_uri، ios_universal_link_url

tdl1 وhttps://examplepetstore.com/api/gtfs/web و https://examplepetstore.com/api/gtfs/android وhttps://examplepetstore.com/api/gtfs/ios

إذا تم إرسال الطلب في 19-07-2019 وكانت أوقات مواصفات الخلاصة العامة للنقل العام (GTFS) بالمنطقة الزمنية بالتوقيت العالمي المُنسَّق 1+، سيتم إجراء المكالمة على الويب أدناه:

https://examplepetstore.com/api/gtfs/web?service_date=%5B%2220190719%22%5D&ticketing_trip_id= %5B%22FR_SNCF_6603%22%5D&from_ticketing_stop_time_id=%5B%224924%22%5D&to_ticketing_stop_time_id= %5B%224676%22%5D&boarding_time=%5B%222019-07-19T05:59:00%2B00:00%22%5&arrival_time=%5B%222019-07-19T07:56:00%2B00:00%22%5D

اتّبِع الاقتراحات التالية لتنفيذ إضافات بيع التذاكر في Google Transit:

الإرشادات
مشاركة الروابط لصفحات معيّنة بين الوكالات أو المسارات متى أمكن ذلك.

في الخلاصة الثابتة، عندما يكون لدى العديد من الوكالات أو المسارات عناوين URL نفسها لروابط الصفحات في التطبيقات، يجب أن تشارك قيمة واحدة للحقل ticketing_deep_link_id. ويسمح ذلك بعمليات النقل بين الوكالات أو المسارات.
ضبط قيم متسقة لـ ticketing_type

يجب أن تكون القيمة ticketing_type لمحطة معيّنة متسقة في جميع الصفوف ضمن الملف stop_times.txt.
ربط ticketing_stop_id لكل من محطتَي الوالدَين والطفل. نفِّذ عملية الربط لجميع محطات التوقّف الرئيسية والثانوية التي تتطلّب شراء التذاكر. في ملف ticketing_identifiers.txt، لا يتم نشر قيم ticketing_stop_id بين محطة توقّف رئيسية وعناصرها الثانوية.
ربط ticketing_stop_id لكل وكالة تستخدم المحطة نفسها في الخلاصة

في الخلاصة الثابتة، إذا كانت الوكالات المتعددة التي تتيح بيع التذاكر تتشارك في المحطة نفسها، يجب أن تكون عملية الربط متاحة لكل وكالة من الوكالات.

لمزيد من التفاصيل، راجِع قسم تعريفات الحقول ticketing_identifiers.txt.
استخدِم Android App Links عند الحاجة إلى رابط لصفحة في تطبيق Android.

إذا أراد الشريك فتح تطبيق Android من خلال رابط لصفحة في التطبيق، يمكنك إعداد الرابط لصفحة في التطبيق كرابط في تطبيق Android.
استخدِم الروابط العامة في نظام iOS عندما تحتاج إلى رابط لصفحة في تطبيق iOS. إذا أراد الشريك فتح تطبيق iOS من رابط لصفحة في التطبيق، يمكنك إعداد الرابط لصفحة في التطبيق كرابط عام لنظام التشغيل iOS.