شارات لرموز التطبيقات

تسمح واجهة برمجة التطبيقات App Badging API لتطبيقات الويب المثبَّتة بوضع شارة على مستوى التطبيق على رمز التطبيق.

Pete LePage

ما هي واجهة App Badging API؟

مثال على Twitter مع ثمانية إشعارات وتطبيق آخر يعرض شارة نوع الإبلاغ
مثال على تطبيق Twitter يتضمّن ثمانية إشعارات وتطبيق آخر يعرض شارة نوع علامة.

تسمح واجهة App Badging API لتطبيقات الويب المثبَّتة بضبط شارة على مستوى التطبيق تظهر في مكان خاص بنظام التشغيل ومرتبط بالتطبيق (مثل الرف أو الشاشة الرئيسية).

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

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

حالات الاستخدام المحتمَلة

تشمل أمثلة التطبيقات التي قد تستخدم واجهة برمجة التطبيقات هذه ما يلي:

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

الدعم

تعمل واجهة برمجة التطبيقات App Badging API على نظامَي التشغيل Windows وmacOS، في الإصدار 81 من Chrome والإصدار 81 من Edge أو الإصدارات الأحدث. لا تزال ميزة "التبديل السريع" غير متاحة على نظام التشغيل ChromeOS، ولكنّها قيد التطوير وستتوفّر في إصدار قادم. لا تتوفّر واجهة برمجة التطبيقات Badging API على نظام التشغيل Android. بدلاً من ذلك، يعرض Android تلقائيًا شارة على رمز تطبيق الويب المثبَّت عند توفّر إشعار لم تتم قراءته، تمامًا كما هو الحال مع تطبيقات Android.

تجربة الميزة

  1. افتح الإصدار التجريبي من App Badging API.
  2. انقر على تثبيت لتثبيت التطبيق عندما يُطلب منك ذلك، أو استخدِم ملف Chrome القائمة لتثبيته.
  3. افتح التطبيق كتطبيق ويب تقدّمي مثبّت. تجدر الإشارة إلى أنّه يجب أن يعمل التطبيق كتطبيق ويب تقدّمي (PWA) مثبَّت (في شريط المهام أو شريط الإرساء).
  4. انقر على الزر ضبط أو محو لضبط الشارة أو محوها من رمز التطبيق. ويمكنك أيضًا توفير رقم لقيمة الشارة.

كيفية استخدام واجهة برمجة التطبيقات App Badging API

لاستخدام واجهة App Badging API، يجب أن يستوفي تطبيق الويب معايير قابلية التثبيت في Chrome، وعلى المستخدمين إضافته إلى الشاشات الرئيسية.

تتألّف واجهة برمجة التطبيقات Badge API من طريقتَين في navigator:

  • setAppBadge(number): لضبط شارة التطبيق. في حال توفّر قيمة، اضبط الشارة على القيمة المقدَّمة، وإلا اعرض نقطة بيضاء عادية (أو علامة أخرى حسب ما يناسب المنصة). يماثل ضبط number على 0 طريقة استدعاء clearAppBadge().
  • clearAppBadge(): لإزالة شارة التطبيق

ويعرض كلاهما وعدًا فارغًا يمكنك استخدامه لمعالجة الأخطاء.

يمكن ضبط الشارة من الصفحة الحالية أو من مشغّل الخدمة المسجَّل. لضبط الشارة أو محوها (سواء في صفحة المقدّمة أو عامل الخدمة)، يمكنك الاتصال بما يلي:

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

في بعض الحالات، قد لا يسمح نظام التشغيل بعرض الشارة بالشكل الدقيق. وفي مثل هذه الحالات، سيحاول المتصفّح تقديم أفضل تمثيل لجهازك. على سبيل المثال، بسبب عدم توفّر Badging API على Android، يعرض Android نقطة فقط بدلاً من قيمة رقمية.

لا تفترض أيّ شيء بشأن كيفية عرض وكيل المستخدم للشارة. قد تأخذ بعض وكلاء المستخدمين رقمًا مثل "4000" وتعيد كتابته على النحو التالي: "99+". إذا فعّلت الشارة بنفسك (على سبيل المثال، من خلال ضبطها على "99")، لن تظهر العلامة "+". بغض النظر عن الرقم الفعلي، ما عليك سوى الاتصال بـ setAppBadge(unreadCount) والسماح لوكيل المستخدم بالتعامل مع عرضه وفقًا لذلك.

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

ضبط الشارة وإزالتها في الخلفية من خلال عامل خدمة

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

المزامنة الدورية في الخلفية

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

ومع ذلك، فإنّ معدّل تكرار المزامنة ليس موثوقًا به تمامًا، ويُستخدَم حسب تقدير المتصفّح.

Web Push API

تسمح واجهة برمجة التطبيقات Push API للخوادم بإرسال رسائل إلى مشغّلي الخدمات، الذين يمكنهم تشغيل رمز JavaScript حتى في حال عدم تشغيل أي صفحة تعمل في المقدّمة. وبالتالي، يمكن أن يؤدي إرسال البيانات من الخادم إلى تعديل الشارة من خلال الاتصال بـ navigator.setAppBadge().

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

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

مزيج من الاثنين

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

ملاحظات

يريد فريق Chrome معرفة تجاربك مع واجهة برمجة التطبيقات App Badging API.

أخبِرنا عن تصميم واجهة برمجة التطبيقات.

هل هناك ما لا يعمل على النحو المتوقّع في واجهة برمجة التطبيقات؟ هل هناك طرق أو سمات مفقودة تحتاجها لتنفيذ فكرتك؟ هل لديك سؤال أو تعليق حول نموذج الأمان؟

الإبلاغ عن مشكلة في التنفيذ

هل رصدت خطأ في عملية تنفيذ Chrome؟ أم هل التنفيذ مختلف عن المواصفات؟

  • يُرجى إرسال بلاغ عن الخطأ على الرابط https://new.crbug.com. احرص على تضمين أكبر قدر ممكن من التفاصيل والتعليمات البسيطة لإعادة إنتاج الخطأ، واضبط المكوّنات على UI>Browser>WebAppInstalls. يُعد تطبيق Glitch مثاليًا لمشاركة إعادة إنتاج سريعة وسهلة.

إظهار الدعم لواجهة برمجة التطبيقات

هل تخطّط لاستخدام واجهة برمجة التطبيقات App Badging API على موقعك الإلكتروني؟ يساعد دعمك العلني فريق Chrome في تحديد أولويات الميزات، ويُظهر لموفّري المتصفّحات الآخرين مدى أهمية توفير الدعم لهم.

  • أرسِل تغريدة إلى ‎@ChromiumDev باستخدام الهاشتاغ #BadgingAPI وأطلِعنا على مكان استخدامك للميزة وطريقة استخدامك لها.

روابط مفيدة

صورة رئيسية من أعمال براتيك كاتيال على Unsplash