بدء استخدام notifications API

في هذا الدرس التطبيقي، ستستخدم الميزات الأساسية لواجهة برمجة التطبيقات Notifications API لإجراء ما يلي:

  • طلب الإذن بإرسال الإشعارات
  • إرسال إشعارات
  • تجربة خيارات الإشعارات

توافق المتصفّح

  • Chrome: 20
  • ‫Edge: 14
  • Firefox: 22.
  • Safari: 7

المصدر

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

  1. انقر على Remix to Edit (إنشاء ريمكس للتعديل) ليصبح المشروع قابلاً للتعديل.
  2. لمعاينة الموقع الإلكتروني، اضغط على عرض التطبيق. ثم اضغط على ملء الشاشة ملء الشاشة.

من المفترض أن يتم فتح Glitch في علامة تبويب جديدة في Chrome:

لقطة شاشة تعرض التطبيق المباشر الذي تم إنشاء ريمكس له في علامة تبويب جديدة

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

التعرّف على التطبيق الأوّلي ورمزه

ابدأ بالاطّلاع على التطبيق المباشر في علامة التبويب الجديدة على Chrome:

  1. اضغط على Ctrl ‏+ Shift ‏+ J (أو Command ‏+ Option ‏+ J على نظام التشغيل Mac) لفتح DevTools. انقر على علامة التبويب وحدة التحكم.

    من المفترض أن تظهر لك الرسالة التالية في وحدة التحكّم:

    Notification permission is default

    إذا لم تكن تعرف ما يعنيه ذلك، لا داعي للقلق، سنكشف لك كل التفاصيل قريبًا.

  2. انقر على الزرَّين في التطبيق المنشور: طلب إذن لإرسال الإشعارات وإرسال إشعار.

    تطبع وحدة التحكّم رسائل "TODO" من نموذجَين للدوالّ: requestPermission وsendNotification. في ما يلي الدوالّ التي ستنفّذها في هذا الدليل التعليمي.

لنلقِ الآن نظرة على رمز نموذج التطبيق في Glitch المضمّن في هذه الصفحة. افتح public/index.js واطّلِع على بعض الأجزاء المهمة من الرمز الحالي:

  • تستخدِم الدالة showPermission Notifications API للحصول على حالة الأذونات الحالية للموقع الإلكتروني وتسجيلها في وحدة التحكّم:

    // Print current permission state to console;
    // update onscreen message.
    function showPermission() {
      let permission
    = Notification.permission;
      console
    .log('Notification permission is ' + permission);
      let p
    = document.getElementById('permission');
      p
    .textContent = 'Notification permission is ' + permission;
    }

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

  • الدالة requestPermission هي دالة نموذجية:

    // Use the Notification API to request permission to send notifications.
    function requestPermission() {
      console
    .log('TODO: Implement requestPermission()');
    }

    ستنفّذ هذه الدالة في الخطوة التالية.

  • الدالة sendNotification هي دالة نموذجية:

    // Use the Notification constructor to create and send a new Notification.
    function sendNotification() {
      console
    .log('TODO: Implement sendNotification()');
    }

    ستنفّذ هذه الدالة بعد تنفيذ requestPermission.

  • يُطلِق مستمع أحداث window.onload الدالة showPermission عند تحميل الصفحة، ما يعرض حالة الإذن الحالية في وحدة التحكّم وعلى الصفحة:

    window.onload = () => { showPermission(); };

طلب الإذن بإرسال الإشعارات

في هذه الخطوة، ستضيف وظيفة لطلب إذن المستخدم لإرسال الإشعارات.

ستستخدم الطريقة Notification.requestPermission() لعرض نافذة منبثقة تطلب من المستخدم السماح بالإشعارات من موقعك الإلكتروني أو حظرها.

  1. استبدِل الرمز البرمجي المخصّص للدالة requestPermission في public/index.js بالرمز البرمجي التالي:

    // Use the Notification API to request permission to send notifications.
    function requestPermission() {
     
    Notification.requestPermission()
       
    .then((permission) => {
          console
    .log('Promise resolved: ' + permission);
          showPermission
    ();
       
    })
       
    .catch((error) => {
          console
    .log('Promise was rejected');
          console
    .log(error);
       
    });
    }
  2. أعِد تحميل علامة التبويب في Chrome التي تعرض تطبيقك المباشر.

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

يمكن للمستخدم تقديم أحد الخيارات الثلاثة على النافذة المنبثقة للسماح.

استجابة المستخدم حالة إذن إرسال الإشعارات
يختار المستخدم السماح. granted
يختار المستخدم حظر. denied
إغلاق المستخدم للنافذة المنبثقة بدون إجراء اختيار default

إذا نقر المستخدم على "السماح":

  • تم ضبط Notification.permission على granted.

  • سيتمكّن الموقع الإلكتروني من عرض الإشعارات.

  • ستؤدي المكالمات اللاحقة إلى Notification.requestPermission إلى إعادة التوجيه إلى granted بدون نافذة منبثقة.

إذا نقر المستخدم على "حظر":

  • تم ضبط Notification.permission على denied.

  • لن يتمكّن الموقع الإلكتروني من عرض الإشعارات للمستخدم.

  • ستؤدي المكالمات اللاحقة إلى Notification.requestPermission إلى إعادة التوجيه إلى denied بدون نافذة منبثقة.

إذا أغلق المستخدم النافذة المنبثقة:

  • يبقى سعر Notification.permission default.

  • ولن يتمكّن الموقع الإلكتروني من عرض الإشعارات للمستخدم.

  • ستؤدي المكالمات اللاحقة إلى Notification.requestPermission إلى ظهور المزيد من النوافذ المنبثقة.

    ومع ذلك، إذا استمرّ المستخدم في إغلاق النوافذ المنبثقة، قد يحظر المتصفّح الموقع الإلكتروني، ويضبط القيمة Notification.permission على denied. ولا يمكن بعد ذلك عرض إشعارات أو نوافذ منبثقة لطلب الأذونات للمستخدم.

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

إرسال إشعار

في هذه الخطوة، عليك إرسال إشعار إلى المستخدم.

ستستخدم عنصر الإنشاء Notification لإنشاء إشعار جديد ومحاولة عرضه. إذا كانت حالة الإذن هي granted، سيتم عرض إشعارك.

  1. استبدِل الرمز البرمجي المخصّص للدالة sendNotification في index.js بالرمز البرمجي التالي:

    // Use the Notification constructor to create and send a new Notification.
    function sendNotification() {
      let title
    = 'Test';
      let options
    = {
        body
    : 'Test body',
       
    // Other options can go here
     
    };
      console
    .log('Creating new notification');
      let notification
    = new Notification(title, options);
    }

    تأخذ الدالة الإنشائية Notification مَعلمتَين: title وoptions. options هو عنصر يتضمّن سمات تمثّل الإعدادات المرئية والبيانات التي يمكنك تضمينها في إشعار. اطّلِع على مستندات MDN حول مَعلمات الإشعارات للحصول على مزيد من المعلومات.

  2. أعِد تحميل علامة التبويب Chrome التي تعرض تطبيقك المباشر، ثم انقر على زر إرسال إشعار. من المفترض أن يظهر إشعار يتضمّن النص Test body.

ماذا يحدث عند إرسال إشعارات بدون إذن؟

في هذه الخطوة، ستضيف بضعة أسطر من الرموز البرمجية التي ستتيح لك معرفة ما يحدث عند محاولة عرض إشعار بدون إذن المستخدم.

  • في public/index.js، في نهاية الدالة sendNotification، حدِّد معالِج الحدث onerror للإشعار الجديد:
// Use the Notification constructor to create and send a new Notification.
function sendNotification() {
  let title
= 'Test';
  let options
= {
    body
: 'Test body',
   
// Other options can go here
 
};
  console
.log('Creating new notification');
  let notification
= new Notification(title, options);
  notification
.onerror = (event) => {
    console
.log('Could not send notification');
    console
.log(event);
 
};
}

لرصد خطأ في إذن إرسال الإشعارات:

  1. انقر على رمز القفل بجانب شريط عناوين Chrome وأعِد ضبط إعدادات إذن الإشعارات للموقع الإلكتروني على الإعدادات التلقائية.

  2. انقر على طلب الإذن لإرسال الإشعارات، واختَر هذه المرة حظر من النافذة المنبثقة.

  3. انقر على إرسال إشعار واطّلِع على ما يحدث. يتم تسجيل نص الخطأ (Could not send notification) وعنصر الحدث في وحدة التحكّم.

يمكنك اختياريًا إعادة ضبط أذونات إرسال الإشعارات للموقع الإلكتروني مرة أخرى. يمكنك محاولة طلب الإذن وإغلاق النافذة المنبثقة عدة مرات لمعرفة ما سيحدث.

تجربة خيارات الإشعارات

لقد اطّلعت الآن على أساسيات كيفية طلب الإذن وإرسال الإشعارات. ولاحظت أيضًا تأثير ردود المستخدمين في قدرة تطبيقك على عرض الإشعارات.

يمكنك الآن تجربة العديد من خيارات البيانات والمرئيات المتاحة عند إنشاء إشعار. في ما يلي المجموعة الكاملة للخيارات المتاحة. (اطّلِع على مستندات الإشعارات على MDN للحصول على مزيد من المعلومات عن هذه الخيارات).

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

let options = {
  dir
: 'auto',              // Text direction
  lang
: 'en-US',            // A language tag
  badge
: '/orange-cat.png', // Display when insufficient room
  body
: 'Hello World',      // Body text
  tag
: 'mytag',             // Tag for categorization
  icon
: '/line-cat.png',    // To display in the notification
  image
: '/orange-cat.png', // To display in the notification
  data
: {                   // Arbitrary data; any data type
    cheese
: 'I like cheese',
    pizza
: 'Excellent cheese delivery mechanism',
    arbitrary
: {
      faveNumber
: 42,
      myBool
: true
   
}},
  vibrate
: [200, 100, 200], // Vibration pattern for hardware
  renotify
: false,          // Notify if replaced? Default false
  requireInteraction
: false,// Active until click? Default false
 
/*
    actions:   // Array of NotificationActions
               // Only usable with a service worker
    [{
      action: 'shop',
      title: 'Shop!',
      icon: '/bags.png'
    },],
  */

}

يمكنك الاطّلاع على أداة إنشاء الإشعارات من Peter Beverloo للحصول على مزيد من الأفكار.

إذا واجهت مشكلة، إليك الرمز البرمجي المكتمل لهذا الدرس التطبيقي حول الترميز: glitch.com/edit/#!/codelab-notifications-get-started-completed

اطّلِع على الدرس التطبيقي التالي في هذه السلسلة، وهو معالجة الإشعارات باستخدام عامل خدمة، للتعرّف على مزيد من المعلومات.