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

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

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

الخلفية

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

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

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

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

خطوات الدمج

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

مثال على طلب 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 إلى تشغيل إشعار، شرط أن يكون الحقل المعدَّل متوافقًا حاليًا.

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

EventTicketClass

• eventName
• eventVenue.name
• eventvenue.address
• eventDateTime.doorsOpen
• eventDateTime.start

EventTicketObject

• eventSeat.seat
• eventSeat.row
• eventSeat.section
• eventSeat.gate