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

تسمح واجهة برمجة التطبيقات 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 أو الاثنين معًا.

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

تسمح المزامنة الدورية في الخلفية لعامل الخدمة بإجراء استطلاعات للاتصال بالخادم بشكل دوري، ويمكن استخدامها للحصول على حالة محدّثة، وتشغيل 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