‫Codelab: ساختن کارخواه اعلان لحظه‌ای

Kate Jeffreys
Kate Jeffreys
Kayce Basques
Kayce Basques
X GitHub

این codelab گام‌به‌گام به شما نشان می‌دهد که چگونه یک کلاینت اعلان لحظه‌ای بسازید. در پایان codelab، کارخواهی خواهید داشت که:

  • کاربر را برای دریافت اعلان‌های لحظه‌ای مشترک می‌کند.
  • پیام‌های لحظه‌ای را دریافت می‌کند و آن‌ها را به‌عنوان اعلان نمایش می‌دهد.
  • اشتراک کاربر را از اعلان‌های لحظه‌ای لغو می‌کند.

این codelab بر کمک به شما برای یادگیری ازطریق انجام دادن تمرکز دارد و درباره مفاهیم زیاد صحبت نمی‌کند. برای آشنایی با مفاهیم اعلان لحظه‌ای، نحوه عملکرد اعلان لحظه‌ای را بخوانید.

کد سرور این codelab ازقبل تکمیل شده است. در این codelab، فقط کارخواه را پیاده‌سازی خواهید کرد. برای آشنایی با نحوه پیاده‌سازی سرور اعلان لحظه‌ای، Codelab: Build a push notification server (Codelab: ساختن سرور اعلان لحظه‌ای) را ببینید.

سازگاری مرورگر

این codelab با ترکیب‌های سیستم‌عامل و مرورگر زیر کار می‌کند:

  • Windows: Chrome،‏ Edge
  • macOS: Chrome،‏ Firefox
  • Android: Chrome،‏ Firefox

این codelab با سیستم‌عامل‌های زیر (یا ترکیب‌های سیستم‌عامل و مرورگر) کار نمی‌کند:

  • macOS: Brave،‏ Edge،‏ Safari
  • iOS

راه‌اندازی

راه‌اندازی اصالت‌سنجی

قبل‌از اینکه بتوانید اعلان‌های لحظه‌ای را فعال کنید، باید سرور و سرویس‌گیرنده خود را با کلیدهای اصالت‌سنجی راه‌اندازی کنید. برای اطلاع از دلیل آن، به امضا کردن درخواست‌های پروتکل ارسال وب مراجعه کنید. معمولاً، اطلاعات محرمانه را در فایل .env ذخیره می‌کنید، مشابه این.

VAPID_PUBLIC_KEY="BKiwTvD9HA…"
VAPID_PRIVATE_KEY="4mXG9jBUaU…"
VAPID_SUBJECT="mailto:test@test.test"
  1. باز کردن public/index.js.
  2. VAPID_PUBLIC_KEY_VALUE_HERE را با مقدار کلید عمومی‌تان جایگزین کنید.

ثبت‌نام عامل خدماتی

کارخواه شما برای دریافت و نمایش اعلان‌ها به کارگر خدماتی نیاز دارد. بهتر است عامل خدماتی را در اسرع وقت ثبت کنید. برای اطلاعات بیشتر، به دریافت و نمایش پیام‌های ارسالی به‌عنوان اعلان مراجعه کنید.

  1. نظر // 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);

  2. در Chrome، کنسول DevTools را باز کنید.

  3. باید پیام Service worker was registered. را که در «کنسول» ثبت شده است ببینید.

درخواست اجازه اعلان لحظه‌ای

هرگز نباید هنگام بار شدن صفحه، اجازه ارسال اعلان لحظه‌ای را درخواست کنید. درعوض، واسط کاربری شما باید از کاربر بپرسد که آیا می‌خواهد اعلان لحظه‌ای دریافت کند یا نه. وقتی کاربر به‌طور صریح تأیید کرد (مثلاً با کلیک کردن روی دکمه)، می‌توانید فرایند رسمی دریافت اجازه اعلان لحظه‌ای را از مرورگر شروع کنید.

  1. در public/index.js، نظر // TODO را در subscribeButtonHandler() با کد زیر جایگزین کنید:

    // 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.');
}

  2. به برگه برنامه برگردید و روی مشترک شدن در ارسال کلیک کنید. مرورگر یا سیستم‌عاملتان از شما می‌پرسد که آیا می‌خواهید به وب‌سایت اجازه دهید برایتان اعلان لحظه‌ای ارسال کند یا نه.

  3. مجاز کردن (یا عبارت معادل استفاده‌شده توسط مرورگر یا سیستم‌عاملتان) را انتخاب کنید. در «کنسول» باید پیامی ببینید که نشان می‌دهد درخواست پذیرفته شده است یا رد شده است.

مشترک شدن در اعلان‌های لحظه‌ای

فرایند اشتراک شامل تعامل با سرویس وبی است که توسط فروشنده مرورگر کنترل می‌شود و سرویس 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 استفاده می‌شود.

لغو اشتراک از اعلان‌های لحظه‌ای

پس‌از اینکه کاربر در اعلان‌های لحظه‌ای مشترک شد، واسط کاربر شما باید راهی برای لغو اشتراک ارائه دهد تا اگر کاربر نظرش تغییر کرد و دیگر نخواست اعلان‌های لحظه‌ای دریافت کند، بتواند اشتراکش را لغو کند.

  • نظر // TODO را در unsubscribeButtonHandler() با کد زیر جایگزین کنید:
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;
}

دریافت پیام لحظه‌ای و نمایش آن به‌عنوان اعلان

همان‌طور که قبلاً ذکر شد، برای مدیریت دریافت و نمایش پیام‌هایی که از سرور شما به مشتری ارسال شده‌اند، به یک کارمند خدماتی نیاز دارید. برای جزئیات بیشتر، دریافت و نمایش پیام‌های ارسالی به‌عنوان اعلان را ببینید.

  1. public/service-worker.js را باز کنید و نظر // TODO در گرداننده رویداد push در سرویس‌کار را با کد زیر جایگزین کنید:

    let data = event.data.json();
const image = 'logo.png';
const options = {
  body: data.options.body,
  icon: image
}
self.registration.showNotification(
  data.title,
  options
);

  2. به برگه برنامه برگردید.

  3. روی به من اطلاع داده شود کلیک کنید. باید اعلان لحظه‌ای دریافت کنید.

  4. نشانی وب برگه برنامه‌تان را در مرورگرهای پشتیبانی‌شده دیگر باز کنید. گردش کار اشتراک را طی کنید و روی اعلان به همه کلیک کنید. باید در هرکدام از آن‌ها اعلان لحظه‌ای یکسانی دریافت کنید.

می‌توانید اعلان را به روش‌های مختلفی سفارشی‌سازی کنید. برای کسب اطلاعات بیشتر، پارامترهای ServiceWorkerRegistration.showNotification() را ببینید.

باز کردن نشانی وب وقتی کاربر روی اعلان کلیک می‌کند

در دنیای واقعی، احتمالاً از اعلان به‌عنوان راهی برای تعامل مجدد با کاربر و ترغیب او به بازدید از سایتتان استفاده خواهید کرد. برای انجام این کار، باید کارگر سرویس خود را کمی بیشتر پیکربندی کنید.

  1. نظر // TODO را در گرداننده رویداد notificationclick سرویس‌کار با کد زیر جایگزین کنید:

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

  2. به برگه برنامه برگردید، اعلان دیگری برای خودتان ارسال کنید، و سپس روی اعلان کلیک کنید. مرورگرتان باید برگه جدیدی باز کند و https://web.dev را بار کند.

مراحل بعدی