Codelab: יצירת לקוח התראות בדחיפה

קייט ג'פריס

קייס בסקית

בשיעור הזה תלמדו בצורה מפורטת איך לפתח לקוח להתראות. בסוף ה-Codelab יהיה לקוח אשר:

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

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

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

כדי לראות את הקוד המלא, צריך לבדוק את push-notifications-client-codelab-complete (מקור).

תאימות דפדפן

ידוע ש-Codelab הזה פועל עם השילובים הבאים של מערכת הפעלה ודפדפנים:

• Windows: Chrome, Edge
• macOS: Chrome, Firefox
• Android: Chrome, Firefox

ידוע ש-Codelab הזה לא פועל עם מערכות ההפעלה הבאות (או השילובים של מערכת ההפעלה והדפדפנים):

• macOS: Brave, Edge, Safari
• iOS

הגדרה

קבלת עותק שניתן לעריכה של הקוד

עורך הקוד שמופיע מימין להוראות האלו ייקרא ממשק המשתמש של Glitch בכל ה-Codelab הזה.

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

מגדירים אימות

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

1. בממשק המשתמש של Glitch, לוחצים על Tools (כלים) ואז על Terminal (מסוף) כדי לפתוח את Glitch Terminal.
2. ב-Glitch Terminal, מריצים את npx web-push generate-vapid-keys. מעתיקים את המפתח הפרטי ואת ערכי המפתח הציבורי.
3. בממשק המשתמש של Glitch, פותחים את .env ומעדכנים את VAPID_PUBLIC_KEY ואת VAPID_PRIVATE_KEY. מגדירים את VAPID_SUBJECT לערך mailto:test@test.test. את כל הערכים האלה צריך להקיף במירכאות כפולות. אחרי ביצוע העדכונים, קובץ .env אמור להיראות כך:

VAPID_PUBLIC_KEY="BKiwTvD9HA…"
VAPID_PRIVATE_KEY="4mXG9jBUaU…"
VAPID_SUBJECT="mailto:test@test.test"

1. סוגרים את מסוף תקלה.

1. פתיחת public/index.js.
2. מחליפים את VAPID_PUBLIC_KEY_VALUE_HERE בערך של המפתח הציבורי.

רישום קובץ שירות (service worker)

בסופו של דבר הלקוח שלכם יזדקק ל-Service Worker כדי לקבל ולהציג התראות. מומלץ לרשום את קובץ השירות (service worker) מוקדם ככל האפשר. למידע נוסף, ראו קבלה והצגה של הודעות שנשלחו כהתראות.

1. מחליפים את התגובה // TODO add startup logic here בקוד הבא:

// TODO add startup logic here
if ('serviceWorker' in navigator && 'PushManager' in window) {
  navigator.serviceWorker.register('./service-worker.js').then(serviceWorkerRegistration => {
    console.info('Service worker was registered.');
    console.info({serviceWorkerRegistration});
  }).catch(error => {
    console.error('An error occurred while registering the service worker.');
    console.error(error);
  });
  subscribeButton.disabled = false;
} else {
  console.error('Browser does not support service workers or push messages.');
}

subscribeButton.addEventListener('click', subscribeButtonHandler);
unsubscribeButton.addEventListener('click', unsubscribeButtonHandler);

1. כדי לראות תצוגה מקדימה של האתר, מקישים על View App ואז על Fullscreen .

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

בקשת הרשאה לשליחת התראות

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

1. בממשק המשתמש של גליץ', לוחצים על הצגת מקור כדי לחזור לקוד.
2. ב-public/index.js החלף את התגובה // TODO ב-subscribeButtonHandler() בקוד הבא:

// TODO
// Prevent the user from clicking the subscribe button multiple times.
subscribeButton.disabled = true;
const result = await Notification.requestPermission();
if (result === 'denied') {
  console.error('The user explicitly denied the permission request.');
  return;
}
if (result === 'granted') {
  console.info('The user accepted the permission request.');
}

1. חוזרים לכרטיסיית האפליקציה ולוחצים על הרשמה לדחיפה. סביר להניח שהדפדפן או מערכת ההפעלה ישאלו אתכם אם אתם רוצים לאפשר לאתר לשלוח התראות. לוחצים על Allow (או כל ביטוי מקביל שבו משתמשים בדפדפן או במערכת ההפעלה). במסוף תופיע הודעה שמציינת אם הבקשה אושרה או נדחתה.

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

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

1. צריך להוסיף ל-subscribeButtonHandler() את הקוד המודגש הבא:

subscribeButton.disabled = true;
const result = await Notification.requestPermission();
if (result === 'denied') {
  console.error('The user explicitly denied the permission request.');
  return;
}
if (result === 'granted') {
  console.info('The user accepted the permission request.');
}
const registration = await navigator.serviceWorker.getRegistration();
const subscribed = await registration.pushManager.getSubscription();
if (subscribed) {
  console.info('User is already subscribed.');
  notifyMeButton.disabled = false;
  unsubscribeButton.disabled = false;
  return;
}
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlB64ToUint8Array(VAPID_PUBLIC_KEY)
});
notifyMeButton.disabled = false;
fetch('/add-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(subscription)
});

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

הערך applicationServerKey מסתמך על פונקציית כלי עזר שממירה מחרוזת base64 ל-Uint8Array. הערך הזה משמש לאימות בין השרת לבין שירות ה-Push.

ביטול ההרשמה להתראות

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

1. מחליפים את התגובה // TODO ב-unsubscribeButtonHandler() בקוד הבא:

// TODO
const registration = await navigator.serviceWorker.getRegistration();
const subscription = await registration.pushManager.getSubscription();
fetch('/remove-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({endpoint: subscription.endpoint})
});
const unsubscribed = await subscription.unsubscribe();
if (unsubscribed) {
  console.info('Successfully unsubscribed from push notifications.');
  unsubscribeButton.disabled = true;
  subscribeButton.disabled = false;
  notifyMeButton.disabled = true;
}

קבלת הודעה ב-Push והצגתה כהתראה

כפי שצוין קודם, צריך קובץ שירות (service worker) שיטפל בקבלה ובהצגה של הודעות שהועברו ללקוח מהשרת שלכם. לפרטים נוספים, ראו קבלה והצגה של הודעות שנשלחו כהתראות.

1. פותחים את public/service-worker.js ומחליפים את התגובה // TODO ב-handler של האירועים push של ה-Service Worker בקוד הבא:

// TODO
let data = event.data.json();
const image = 'https://cdn.glitch.com/614286c9-b4fc-4303-a6a9-a4cef0601b74%2Flogo.png?v=1605150951230';
const options = {
  body: data.options.body,
  icon: image
}
self.registration.showNotification(
  data.title, 
  options
);

1. חוזרים לכרטיסיית האפליקציה.
2. לוחצים על אני רוצה לקבל עדכון. אתם אמורים לקבל התראה.
3. נסו לפתוח את כתובת ה-URL של כרטיסיית האפליקציה בדפדפנים אחרים (או אפילו במכשירים אחרים), לעבוד על תהליך ההרשמה, ואז ללחוץ על Notify all. אתם אמורים לקבל את אותה התראה בכל הדפדפנים שנרשמתם אליהם. אפשר לחזור לדף תאימות הדפדפן כדי לראות רשימה של שילובי דפדפנים ומערכת הפעלה שידועים שפועלים או לא פועלים.

יש הרבה דרכים להתאים אישית את ההתראה. למידע נוסף, עיינו בפרמטרים של ServiceWorkerRegistration.showNotification().

פתיחת כתובת URL כשמשתמש לוחץ על התראה

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

1. מחליפים את ההערה // TODO ב-handler של האירועים notificationclick של ה-Service Worker בקוד הבא:

// TODO
event.notification.close();
event.waitUntil(self.clients.openWindow('https://web.dev'));

1. חזרו לכרטיסיית האפליקציה, שלחו לעצמכם התראה נוספת ולחצו על ההתראה. הדפדפן אמור לפתוח כרטיסייה חדשה ולטעון את https://web.dev.

השלבים הבאים

• כדאי לקרוא את ServiceWorkerRegistration.showNotification() כדי לגלות את כל הדרכים השונות להתאמה אישית של ההתראות.
• קראו את הסקירה הכללית על התראות כדי להבין טוב יותר איך פועלות התראות.
• כדאי לקרוא את המאמר Codelab: בניית שרת התראות Push כדי ללמוד איך לפתח שרת שמנהל מינויים ושולח בקשות לפרוטוקול אינטרנט בדחיפה.
• כדאי לנסות את מחולל ההתראות כדי לבדוק את כל הדרכים שבהן אפשר להתאים אישית את ההתראות.