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

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

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

دعم المتصفح

  • Chrome: 20.
  • الحافة: 14.
  • Firefox: 22.
  • Safari: الإصدار 7-

المصدر

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

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

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

لقطة شاشة تعرض تطبيق البث المباشر المُعاد مزجه في علامة تبويب جديدة

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

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

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

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

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

    Notification permission is default
    

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

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

    تطبع وحدة التحكم "قائمة المهام" رسالتان من توّلي دوال: 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. في واجهة التطبيق المباشرة، انقر على طلب الإذن لإرسال الإشعارات. ستظهر نافذة منبثقة.

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

ردّ المستخدم حالة إذن إرسال الإشعارات
يختار المستخدم السماح. 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. استبدل دالة tub للدالة 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. انقر على رمز القفل بجانب شريط عناوين 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'
    },],
  */
}

يمكنك الاطّلاع على منشئ إشعارات بيتر بيفيرلو للحصول على مزيد من الأفكار.

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

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