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

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

  • צריך לבקש הרשאה לשלוח התראות
  • שליחת התראות
  • ניסוי עם אפשרויות של התראות

תמיכה בדפדפן

  • Chrome: 20.
  • קצה: 14.
  • Firefox: 22.
  • Safari: 7.

מקור

ההתראות חסומות באופן אוטומטי באפליקציית Glitch המוטמעת, כך שלא ניתן להציג תצוגה מקדימה של האפליקציה בדף הזה. במקום זאת:

  1. לוחצים על רמיקס לעריכה כדי לערוך את הפרויקט.
  2. כדי לראות תצוגה מקדימה של האתר, לוחצים על הצגת האפליקציה. לאחר מכן לוחצים על מסך מלא מסך מלא.

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

צילום מסך שבו מוצגת האפליקציה בשידור חי שעברה רמיקס בכרטיסייה חדשה

במהלך העבודה ב-Codelab הזה, יש לבצע שינויים בקוד ב-Glitch שמוטמע בדף הזה. כדאי לרענן את הכרטיסייה החדשה עם האפליקציה הפעילה כדי לראות את השינויים.

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

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

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

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

    Notification permission is default
    

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

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

    המסוף מדפיס את TODO מכמה כרטיסיות פונקציות: requestPermission ו-sendNotification. אלו הפונקציות שתטמיעו ב-Codelab הזה.

עכשיו נסתכל על הקוד של האפליקציה לדוגמה מתוך תקלה שמוטמעת בדף הזה. מומלץ לפתוח את 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 היא 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. לא ניתן להציג למשתמש חלונות קופצים והתראות של בקשות הרשאה.

    נכון לזמן הכתיבה, התנהגות הדפדפן בתגובה לחלונות קופצים עם הרשאה לשליחת התראות עדיין עשויה להשתנות. הדרך הטובה ביותר לטפל בכך היא תמיד לבקש הרשאה לשליחת התראות בתגובה לאינטראקציה כלשהי שהמשתמש התחיל, כדי שהם יוכלו לצפות לקבל אותה ולדעת מה קורה.

שליחת התראה

בשלב הזה, שולחים התראה למשתמש.

תשתמשו ב-constructor של 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 זה: glitch.com/edit/#!/codelab-notifications-get-started-completed

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