تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

درس تطبيقي حول الترميز: إنشاء عميل للإشعارات الفورية

Kate Jeffreys

Kayce Basques

يوضّح لك هذا الدرس التطبيقي حول الترميز خطوة بخطوة كيفية إنشاء برنامج عميل للإشعارات الفورية. بنهاية هذا الدرس، سيكون لديك عميل:

يشترك المستخدم في الإشعارات الفورية.
يتلقّى رسائل فورية ويعرضها كإشعارات.
يؤدي هذا الإجراء إلى إلغاء اشتراك المستخدم في الإشعارات الفورية.

تركّز ورشة رموز البرمجة هذه على مساعدتك في التعلّم من خلال الممارسة، ولا تتناول كثيرًا من المفاهيم. اطّلِع على المقالة كيف تعمل الإشعارات الفورية؟ للتعرّف على مفاهيم الإشعارات الفورية.

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

اطّلِع على push-notifications-client-codelab-complete (source) للاطّلاع على الرمز الكامل.

توافُق المتصفح

من المعروف أنّ ورشة رموز البرامج هذه تعمل مع مجموعات أنظمة التشغيل والمتصفّحات التالية:

نظام التشغيل Windows: Chrome وEdge
‫macOS: Chrome وFirefox
Android: Chrome وFirefox

من المعروف أنّ ورشة رموز البرامج هذه لا تعمل مع أنظمة التشغيل التالية (أو مجموعات أنظمة التشغيل والمتصفّحات):

‫macOS: Brave وEdge وSafari
iOS

ضبط إعدادات الجهاز

الحصول على نسخة قابلة للتعديل من الرمز

يُعرف محرِّر الرموز البرمجية الذي يظهر على يسار هذه التعليمات باسم واجهة مستخدم Glitch خلال هذا الدليل التعليمي.

انقر على Remix to Edit (إنشاء ريمكس لتعديل المحتوى) ليصبح المشروع قابلاً للتعديل.

إعداد المصادقة

قبل أن تتمكّن من تفعيل الإشعارات الفورية، عليك إعداد الخادم والعميل باستخدام مفاتيح المصادقة. اطّلِع على توقيع طلبات بروتوكول إشعارات الويب لمعرفة السبب.

في واجهة مستخدم Glitch، انقر على الأدوات ثم على الوحدة الطرفية لفتح وحدة طرفية Glitch.
في Glitch Terminal، شغِّل npx web-push generate-vapid-keys. انسخ قيم المفتاح الخاص والمفتاح العام.
في واجهة مستخدم 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"

أغلِق Glitch Terminal.

تكون قيم متغيّرات البيئة (العناصر في .env) فريدة لمشروع Glitch واحد. إذا أعدت إنشاء مشروعك، لن يتم نسخ القيم في .env.

فتح "public/index.js"
استبدِل VAPID_PUBLIC_KEY_VALUE_HERE بقيمة مفتاحك العام.

تسجيل مشغّل خدمات

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

استبدِل التعليق // 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);

لمعاينة الموقع الإلكتروني، اضغط على عرض التطبيق. ثم اضغط على ملء الشاشة .

اضغط على Ctrl ‏+ Shift ‏+ J (أو Command ‏+ Option ‏+ J على نظام التشغيل Mac) لفتح DevTools.
انقر على علامة التبويب وحدة التحكم. من المفترض أن تظهر لك الرسالة Service worker was registered. في وحدة التحكّم.

طلب إذن الإشعارات الفورية

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

في واجهة مستخدم Glitch، انقر على عرض المصدر للرجوع إلى الرمز.
في 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.');
}

ارجع إلى علامة تبويب التطبيق وانقر على الاشتراك في الإشعارات الفورية. سيسألك المتصفّح أو نظام التشغيل على الأرجح ما إذا كنت تريد السماح للموقع الإلكتروني بإرسال إشعارات فورية إليك. انقر على سماح (أو أي عبارة مماثلة يستخدمها المتصفّح/نظام التشغيل). من المفترض أن تظهر لك رسالة في وحدة التحكّم تشير إلى ما إذا تم قبول الطلب أو رفضه.

الاشتراك في الإشعارات الفورية

تتضمن عملية الاشتراك التفاعل مع خدمة ويب يتحكّم فيها موفّر المتصفّح، وتُعرف هذه الخدمة باسم خدمة الدفع. بعد الحصول على معلومات الاشتراك في الإشعارات الفورية، عليك إرسالها إلى خادم وطلب تخزينها في قاعدة بيانات على المدى الطويل. اطّلِع على مقالة اشتراك العميل في الإشعارات الفورية لمزيد من المعلومات عن عملية الاشتراك.

أضِف الرمز المميّز التالي إلى 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. تُستخدَم هذه القيمة لتأكيد هوية العميل بين خادمك وخدمة الإرسال الفوري.

إلغاء الاشتراك في الإشعارات الفورية

بعد اشتراك المستخدم في الإشعارات الفورية، يجب أن تهدف واجهة المستخدم إلى توفير طريقة لإلغاء الاشتراك في حال غيّر المستخدم رأيه ولم يعد يريد تلقّي إشعارات فورية.

استبدِل التعليق // 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;
}

تلقّي رسالة فورية وعرضها كإشعار

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

افتح public/service-worker.js واستبدِل التعليق // TODO في معالِج الأحداث push الخاص بعامل الخدمة بالرمز التالي:

// 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
);

ارجع إلى علامة التبويب "التطبيق".
انقر على إشعاري. من المفترض أن يصلك إشعار فوري.
جرِّب فتح عنوان URL لعلامة التبويب الخاصة بالتطبيق على متصفّحات أخرى (أو حتى على أجهزة أخرى)، واتّبِع سير عمل الاشتراك، ثم انقر على إرسال إشعار إلى الجميع. من المفترض أن يصلك الإشعار الفوري نفسه على جميع المتصفّحات التي اشتركت فيها. يمكنك الرجوع إلى توافق المتصفّح للاطّلاع على قائمة بمجموعات المتصفّح/نظام التشغيل التي تعمل أو لا تعمل.

يمكنك تخصيص الإشعار بعدة طرق. اطّلِع على مَعلمات ServiceWorkerRegistration.showNotification() لمعرفة المزيد.

من المهم فهم طلب self.skipWaiting() في مستمع install الخاص بعامل الخدمة. اطّلِع على تخطّي مرحلة الانتظار للحصول على تفسير. بدون ذلك، لن تسري التغييرات التي تجريها على الرمز البرمجي في الخدمة العاملة على الفور. قد تحتاج إلى استخدام هذه الميزة على موقعك الإلكتروني أو لا تحتاج إليها، وذلك حسب احتياجاتك، ولكن في كلتا الحالتَين، من المهم فهم تأثيرها.

فتح عنوان URL عندما ينقر المستخدِم على إشعار

في الواقع، من المرجّح أن تستخدم الإشعار كطريقة لإعادة جذب المستخدِم وطلب زيارته لموقعك الإلكتروني. ولإجراء ذلك، عليك ضبط الخدمة العاملة بشكل أكبر.

استبدِل التعليق // TODO في معالِج الأحداث notificationclick لعامل الخدمة بالرمز البرمجي التالي:

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

ارجع إلى علامة تبويب التطبيق وأرسِل إليك إشعارًا آخر، ثم انقر على الإشعار. من المفترض أن يفتح المتصفّح علامة تبويب جديدة ويحمّل https://web.dev.

الخطوات التالية

اطّلِع على ServiceWorkerRegistration.showNotification() لاكتشاف جميع الطرق المختلفة التي يمكنك من خلالها تخصيص الإشعارات.
اطّلِع على نظرة عامة على الإشعارات الفورية لفهم آلية عمل الإشعارات الفورية بشكل أعمق.
اطّلِع على الدرس التطبيقي حول الترميز: إنشاء خادم إشعارات فورية لمعرفة كيفية إنشاء خادم يدير الاشتراكات ويرسل طلبات بروتوكول إشعارات الويب.
جرِّب أداة إنشاء الإشعارات لاختبار جميع الطرق التي يمكنك من خلالها تخصيص الإشعارات.