تشغيل الإشعارات الفورية

أنواع الإشعارات

إضافة رسالة وإشعار

الخلفية

بعد أن يضيف المستخدم بطاقة، يمكنك إرسال رسالة إليه حول البطاقة والتأكّد من أنّه تم إشعاره بها. عند استخدام طلب Add Message API مع message_type يساوي TEXT_AND_NOTIFY، يحدث ما يلي:

1. تتم إضافة عنصر "رسالة" إلى "الجهة الخلفية للبطاقة" (يُعرف أيضًا باسم نموذج التفاصيل) ويتم إرسال إشعار فوري إلى المستخدمين الذين تم حفظ البطاقة لديهم.
2. بعد أن ينقر المستخدم على الإشعار، سيتم فتح "محفظة Google" لعرض البطاقة (المعروفة أيضًا باسم "عرض البطاقة")، وسيظهر للمستخدم مربّع معلومات في أعلى الشاشة يتضمّن زر "عرض الرسالة".
3. سينقل النقر على العنصر المميّز المستخدمين إلى الجزء الخلفي من البطاقة، حيث يتم تمييز الرسائل الجديدة غير المقروءة.

بعض النقاط التي يجب مراعاتها عند إرسال رسائل تتضمّن إشعارات إلى المستخدمين

• يجب أن تكون الإشعارات مفعّلة في البطاقات لدى المستخدمين لتلقّي الإشعارات الفورية المرتبطة بالرسائل.
• قد تحتوي الرسائل على عناوين URL تؤدي إلى موقعك الإلكتروني أو تطبيقك. ويجب أن تكون الروابط التشعبية متعلّقة بموقع إلكتروني أو تطبيق مرتبطَين بالبطاقة. يشكّل إرسال المستخدمين إلى روابط غير مرتبطة بالبطاقة انتهاكًا ل سياسة الاستخدام المقبول .
• يمكنك إرسال 3 رسائل كحد أقصى تؤدي إلى ظهور إشعار فوري في مهلة 24 ساعة. قد تحدّ Google من حصة إرسال الإشعارات الفورية إذا رأت أنّك ترسل إشعارات غير مرغوب فيها إلى المستخدمين.
• يتحكّم تطبيق "محفظة Google" في الإشعارات الفورية التي تظهر للمستخدمين على شاشة القفل.
• يمكنك استخدام الطريقتَين UPDATE أو PATCH لتعديل بيانات الرسائل أو إزالتها باستخدام نقطة نهاية الإجراء العادي للصف أو العنصر.

خطوات الدمج

عندما تريد إشعار المستخدمين بشأن رسالة جهة إصدار جديدة تمت إضافتها باستخدام واجهة برمجة التطبيقات AddMessage API، عليك تعديل العنصر AddMessageRequest لكي تعرض قيمة MessageType TEXT_AND_NOTIFY بدلاً من TEXT في حقل Message.

مثال على طلب JSON لإضافة رسالة وإشعار في فئة "التصاريح"

  …
  "id": ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Class message header",
        "body": "My Class message body with a <a href="https://wallet.google">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

مثال على طلب بتنسيق JSON لإضافة رسالة وإرسال إشعار في عنصر بطاقات

  …
  "id": OBJECT_ID",
  "classId": "ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Object message header",
        "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

مثال على الرد لإضافة رسالة وإشعار بشأن فئة "بطاقة"

  // The updated resource
  …
    {
      "kind": "walletobjects#walletObjectMessage",
      "header": "My Object message header",
      "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
      "id": "message_id",
      "messageType": "textAndNotify"
    },
  …

التعامل مع الاستثناءات

ستؤدي أي محاولات لإرسال الإشعار أكثر من 3 مرات إلى تلقي استجابة QuotaExceededException . يمكن ضبط أي تعديلات أخرى على العبارة باستخدام "TEXT" بدلاً من "TEXT_AND_NOTIFY" كما هو موضّح في خطواتتكامل.

تعديل الحقل والإشعار

الخلفية

بعد أن يضيف المستخدم بطاقة، قد تحتاج إلى تشغيل إشعار فوري عند تعديل حقول معيّنة . سيظهر الإشعار على شاشة القفل لدى المستخدم لإبلاغه بأنّ هناك تعديلاً على البطاقة. لن يتم تشغيل هذا الإشعار إلا لمجموعة فرعية معيّنة من الحقول المحدّدة أدناه باستخدام طريقتَي واجهة برمجة التطبيقات UPDATE وPATCH . بعد إجراء طلب بيانات من واجهة برمجة التطبيقات لتعديل البطاقة، يحدث ما يلي:

1. يتم تشغيل إشعار فوري وعرضه على شاشة القفل الخاصة بالمستخدم لإعلامه بتعديل البطاقة.
2. عندما ينقر المستخدم على الإشعار، يتم فتح "محفظة Google" في مقدّمة البطاقة (أي عرض البطاقة)، وسيرى المستخدم وسيلة شرح في أعلى الشاشة تتضمّن الزر "مراجعة التحديث".
3. يؤدي النقر على الزر إلى نقل المستخدم إلى شاشة يمكنه فيها الاطّلاع على الحقول التي تم تغييرها من خلال التحديث.

بعض الاعتبارات عند إرسال إشعارات تعديل الحقول

• يجب أن تكون الإشعارات مفعّلة في البطاقات لدى المستخدمين لتلقّي الإشعارات الفورية المتعلّقة بالأخبار.
• يمكنك إرسال 3 تعديلات كحدّ أقصى تؤدي إلى ظهور إشعار فوري في غضون 24 ساعة. قد تحدّ Google من حصة إرسال الإشعارات الفورية إذا اعتبرت أنّك ترسل إشعارات غير مرغوب فيها إلى المستخدمين.
• يتحكّم تطبيق "محفظة Google" في الإشعارات الفورية التي تظهر للمستخدمين على شاشة القفل.
• الحقل notifyPreference هو حقل مؤقت لا يتوفّر إلا في هذا الطلب. بالنسبة إلى الطلبات المستقبلية التي تريد فيها تشغيل إشعار، عليك إعادة ضبط هذا الحقل في طلب الفئة أو الطلب المتعلق بالجسم.

خطوات الدمج

لتشغيل هذه الإشعارات، عليك استخدام طلبات UPDATE أو PATCH الحالية وتحديد notifyPreference. عند تعديل حقل في فئة أو عنصر، يمكنك إضافة حقل جديد، notifyPreference، إلى طلب الفئة أو العنصر لتشغيل الإشعار.

مثال على طلب JSON لتعديل الإشعار في الصف

    …
    "dateTime":
        {
            "kind": "walletobjects#eventDateTime",
            "doorsOpen": "2024-09-23T19:20:50.00"
        },
    "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
    "notifyPreference": "notifyOnUpdate",
    …
  

سيؤدي ضبط القيمة notifyPreference على notifyOnUpdate إلى تشغيل إشعار، شرط أن يكون الحقل المعدَّل متوافقًا حاليًا.

الحقول المتوافقة

FlightObject

• boardingAndSeatingInfo.seatNumber
• boardingAndSeatingInfo.seatAssignment