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

كيت جيفريز

كايس باسك

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

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

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

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

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

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

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

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

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

• نظام التشغيل macOS: Brave وEdge وSafari
• iOS

الإعداد

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

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

1. انقر على إنشاء ريمكس لتعديله ليصبح المشروع قابلاً للتعديل.

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

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

1. في "واجهة مستخدم Glitch"، انقر على أدوات، ثم انقر على الطرفية لفتح "محطة glitch".
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. أغلِق Glitch Terminal.

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

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

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

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. لمعاينة الموقع الإلكتروني، اضغط على عرض التطبيق، ثم اضغط على ملء الشاشة .

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

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

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

1. في واجهة مستخدم Glitch، انقر على عرض المصدر للرجوع إلى الرمز.
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. ارجع إلى علامة تبويب التطبيق وانقر على الاشتراك لإرسال الإشعارات. من المحتمل أن يسألك المتصفح أو نظام التشغيل الذي تستخدمه عما إذا كنت تريد السماح لموقع الويب بإرسال إشعارات فورية إليك. انقر على السماح (أو أي عبارة مكافئة يستخدمها المتصفح/نظام التشغيل). في وحدة التحكم، من المفترض أن تظهر رسالة تشير إلى ما إذا تم قبول الطلب أو رفضه.

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

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

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. تُستخدم هذه القيمة للمصادقة بين خادمك وخدمة الدفع

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

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

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;
}

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

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

1. افتح 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
);

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

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

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

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

1. استبدل التعليق // TODO في معالج أحداث notificationclick لمشغّل الخدمات بالرمز التالي:

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

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

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

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