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

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

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

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

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

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

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

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

التعرف على تطبيق البداية ورمزه

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

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

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

   Notification permission is default
   

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

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

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

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

• تستخدم الدالة showPermission واجهة برمجة التطبيقات Notification 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. استبدل دالة stub العامة 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 stub في 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. انقر على رمز القفل بجانب شريط عناوين URL في 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's Notification Generator لمزيد من الأفكار.

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

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