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

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

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

الخلفية

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

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

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

• يجب أن تكون الإشعارات مفعّلة في البطاقات لدى المستخدمين لتلقّي الإشعارات الفورية المرتبطة بالرسائل.
• قد تحتوي الرسائل على معرّفات موارد منتظمة (URI) لموقعك الإلكتروني أو تطبيقك. يجب أن تكون الروابط التشعّبية موقعًا إلكترونيًا أو تطبيقًا مرتبطًا بالبطاقة. يشكّل إرسال المستخدمين إلى روابط غير مرتبطة بالبطاقة انتهاكًا ل سياسة الاستخدام المقبول .
• يمكنك إرسال 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 إلى تشغيل إشعار، شرط أن يكون الحقل المعدَّل متوافقًا حاليًا.

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

LoyaltyClass

• rewardsTier
• secondaryRewardsTier
• programName

LoyaltyObject

• loyaltyPoints.balance
• secondaryLoyaltyPoints.balance