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

الإشعارات التي يتم إرسالها من الشريك

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

خلفية

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

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

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

• يجب أن تكون الإشعارات مفعّلة في بطاقات المستخدمين لتلقّي الإشعارات الفورية المرتبطة بالرسائل.
• قد تحتوي الرسائل على عناوين URI لموقعك الإلكتروني أو تطبيقك. يجب أن تكون الروابط التشعبية مرتبطة بموقع إلكتروني أو تطبيق ذي صلة بالبطاقة. ويُعدّ إرسال المستخدمين إلى روابط غير مرتبطة بالبطاقة انتهاكًا لـ سياسة الاستخدام المقبول.
• يمكنك إرسال 3 رسائل كحد أقصى تؤدي إلى إرسال إشعار فوري خلال 24 ساعة. وقد تحدّ Google من حصتك المسموح بها لإرسال الإشعارات الفورية إذا تبيّن لها أنّك ترسل رسائل غير مرغوب فيها إلى المستخدمين.
• تتحكّم "محفظة Google" في الإشعار الفوري الذي يظهر للمستخدمين على شاشة القفل.
• يمكنك استخدام طريقتَي 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 ساعات أو أقل لتجنُّب إرسال رسائل غير مرغوب فيها إلى المستخدمين.
• يمكنك إرسال 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

إشعارات بشأن الأجهزة المجاورة

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

خطوات التكامل

كيفية الاستخدام

لاستخدام هذه الميزة، عليك إضافة مواقع جغرافية إلى الفئات والعناصر. يمكنك إضافة ما يصل إلى 10 مواقع جغرافية لكل فئة و10 لكل عنصر. استخدِم MerchantLocations في تعريف الفئة أو العنصر. يمكنك إضافة هذه المواقع الجغرافية عند استخدام طُرق insert أو patch أو update.

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

في ما يلي مثال على LoyaltyClass تم ضبط MerchantLocations فيها:

{
  "kind": "walletobjects#loyaltyClass",
  "programLogo": {
  "kind": "walletobjects#image",
  "sourceUri": {
    "uri":
    ...
  }
  },
  "localizedProgramName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Program Name",
    }
  },
  "id": Id1234,
  "version": "1",
  "allowMultipleUsersPerObject": true,
  "reviewStatus": "underReview",
  "enableSmartTap": false,
  "localizedIssuerName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Issuer Name"
    }
  },
  "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
  "merchantLocations": [
    {
      "latitude": 37.79020867928078,
      "longitude": -122.39004
    },
    {
      "latitude": 37.42587,
      "longitude": -122.08620
    },
  ]
}

السلوك المتوقع

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