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

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

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

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

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

1. اضغط على Control+Shift+J (أو Command+Option+J على أجهزة Mac) لفتح "أدوات مطوّلي البرامج". انقر على علامة التبويب وحدة التحكم.

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

   Notification permission is default
   

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

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

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

لنلقِ الآن نظرة على الرمز البرمجي للتطبيق النموذجي. افتح 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. في واجهة التطبيق المباشر، انقر على طلب الإذن بإرسال الإشعارات. ستظهر نافذة منبثقة.

يمكن للمستخدم تقديم إحدى الاستجابات الثلاث التالية لنافذة الإذن المنبثقة.

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

• تم ضبط 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 للحصول على المزيد من الأفكار.

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