نظرة عامة

تتيح واجهة برمجة التطبيقات Google Wallet Pass API للشركاء إمكانية تحديد نقطة نهاية لتفعيل بطاقة نقل عام. وعند الحاجة إلى التفعيل، سيظهر الزر "تفعيل" للمستخدم الذي سيقوم باستدعاء نقطة النهاية المحددة عند النقر عليه مع المَعلمات الموضحة أدناه. يجب أن تتأكد نقطة النهاية من احتواء البطاقة على معلومات صالحة لتحصيل القيمة (إما الرمز الشريطي أو الفحص المرئي) قبل العودة. وفي تلك الحالة، سيتم تعديل البطاقة في "محفظة Google" لعرض المعلومات المتعلّقة بتحصيل القيمة. يُرجى العلم أنّه لن يتم عرض أي معلومات حالية حول تحصيل القيمة قبل التفعيل.

واجهة برمجة تطبيقات التفعيل

يتم تحديد نقطة نهاية التفعيل في واجهة برمجة التطبيقات باستخدام 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 الذي يتم تلقّيه مع معلَمات التفعيل بالإضافة إلى ضبط hasLinkedDevice على "صحيح" في طلب البيانات من واجهة برمجة التطبيقات نفسه. ويمكن بعد ذلك إلغاء ربط طلب الدعم بالجهاز من خلال ضبط القيمة hasLinkedDevice على "خطأ" في طلب بيانات مستقبلي من واجهة برمجة التطبيقات.

مَعلَمات التفعيل

سيحتوي طلب نقطة نهاية التفعيل على المعلمات التالية.

مثال على تنسيق 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 لتمثيل الجهاز الذي يتخذ المستخدم إجراءً بشأنه. يجب استخدام هذا المعرّف عند إجراء تعديلات تربط بين عنصر وهذا الجهاز. وقد لا يكون رقم التعريف هذا ثابتًا للطلبات المستقبلية من جهاز معيّن.