תחילת השימוש ב-Notification API

ב-codelab הזה תשתמשו בתכונות בסיסיות של Notifications API כדי:

  • בקשת הרשאה לשליחת התראות
  • שליחת התראות
  • ניסוי אפשרויות להתראות

Browser Support

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

Source

היכרות עם אפליקציית ההתחלה והקוד שלה

כדאי להתחיל בבדיקת האפליקציה הפעילה בכרטיסיית Chrome חדשה:

  1. מקישים על Control+Shift+J (או על Command+Option+J ב-Mac) כדי לפתוח את כלי הפיתוח. לוחצים על הכרטיסייה מסוף.

    ההודעה הבאה אמורה להופיע במסוף:

    Notification permission is default

    אם אתם לא יודעים מה זה אומר, אל דאגה, בקרוב הכול יתגלה!

  2. לוחצים על הלחצנים באפליקציה הפעילה: בקשת הרשאה לשליחת התראות ושליחת התראה.

    במסוף מודפסות הודעות TODO מכמה פונקציות stub: ‏ 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 היא stub:

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

    תטמיעו את הפונקציה הזו בשלב הבא.

  • הפונקציה sendNotification היא stub:

    // 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. מחליפים את ה-stub של הפונקציה 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);
}

    ה-constructor של 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'
    },],
  */
}

אפשר לקבל עוד רעיונות במחולל ההתראות של פיטר בברלו.

כדאי לעיין ב-Codelab הבא בסדרה הזו, טיפול בהתראות באמצעות Service Worker, כדי לקבל מידע נוסף.