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

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

Kate Jeffreys

Kayce Basques

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

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

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

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

يُرجى الانتقال إلى push-notifications-client-codelab-complete (المصدر) للاطّلاع على الرمز الكامل.

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

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

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

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

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

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

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

سيُطلق على أداة تعديل الرموز الظاهرة على يسار هذه التعليمات اسم واجهة مستخدم 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"

أغلِق المحطة الطرفية للأعطال.

تكون قيم متغيّرات البيئة (العناصر في .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);

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

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

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

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

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