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

الإشعارات التي يتم تشغيلها من قِبل الشريك

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

الخلفية

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

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

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

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

خطوات الدمج

عندما تريد إرسال إشعار إلى المستخدمين بشأن رسالة جديدة من جهة إصدار البطاقة تمت إضافتها باستخدام واجهة برمجة التطبيقات AddMessage، عليك تعديل 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 من حصة تسليم الإشعارات الفورية إذا تبيّن لها أنّك ترسل رسائل غير مرغوب فيها إلى المستخدمين.
  • تتحكّم &quot;محفظة Google&quot; في الإشعارات الفورية التي تظهر للمستخدمين على شاشة القفل.
  • الحقل 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

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

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

خطوات الدمج

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

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

الإشعارات التلقائية التي يتم تشغيلها من خلال "محفظة Google"

الإشعار القادم

ترسل &quot;محفظة Google&quot; إشعارًا إلى المستخدم قبل ثلاث ساعات من موعد الرحلة. يتم تحديد وقت الرحلة الجوية من خلال class.localScheduledDepartureDateTime.

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

يظهر الإشعار في مساحة الإشعارات وعلى شاشة القفل، إذا كان المستخدم قد فعّل الإشعارات على شاشة القفل.

يتضمّن الإشعار التنسيق التالي غير القابل للتعديل: 

  Boarding pass for your flight to class.destination.airportIataCode

إذا نقر على الإشعار وفتح قفل جهازه، ستظهر بطاقته في تطبيق "محفظة Google".

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

يتم تثبيت الإشعار ولن يتم رفضه تلقائيًا بعد أن يفتحه المستخدم. يحدث الإغلاق التلقائي بعد 60 دقيقة من class.localScheduledDepartureDateTime.

إشعار بشأن آخر الأخبار المتعلّقة بالرحلات الجوية

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

مبنى الركاب والبوابة في مطار المغادرة

إذا غيّرت class.origin.terminal أو class.origin.gate، وتم استيفاء الشرط التالي، سيتم إرسال إشعار بأنّه تم تغيير الحقل.

  • يتبقى أقل من ثلاث ساعات حتى ‎class.localScheduledDepartureDateTime.

يكون الإشعار بالتنسيق التالي: "عدّلت شركة Sample Airlines رقم البوابة إلى A1". لا يمكن تغيير التنسيق.

وقت ركوب الطائرة ووقت المغادرة

إذا غيّرت class.localBoardingDateTime أو class.localEstimatedOrActualDepartureDateTime، وتم استيفاء الشروط أدناه، سيتم إرسال إشعار بأنّه تم تغيير الحقل.

  • يتبقى أقل من 24 ساعة حتى class.localScheduledDepartureDateTime.
  • يجب أن يتغيّر الوقت المعنيّ بمقدار 10 دقائق على الأقل.

يكون الإشعار بالتنسيق التالي: "_Sample Airlines has updated your boarding time to 6:00PM._" ولا يمكن تخصيص التنسيق أو اللغة.