تسمح واجهة برمجة التطبيقات App Badging API لتطبيقات الويب المثبَّتة بوضع شارة على مستوى التطبيق على رمز التطبيق.
ما هي واجهة برمجة التطبيقات App Badging API؟
تسمح واجهة برمجة التطبيقات App Badging API لتطبيقات الويب المثبَّتة بضبط شارة على مستوى التطبيق، وعرضها في مكان خاص بنظام التشغيل مرتبط بالتطبيق (مثل الرف أو الشاشة الرئيسية).
تسهّل الشارات إشعار المستخدم بشكل غير مُلحّ بأنّ هناك نشاطًا جديدًا قد يتطلّب انتباهه، أو للإشارة إلى قدر صغير من المعلومات، مثل عدد الرسائل غير المقروءة.
تميل الشارات إلى أن تكون أكثر ملاءمةً للمستخدمين من الإشعارات، ويمكن تعديلها بمعدل أعلى بكثير، لأنّها لا تقاطع المستخدم. ولأنّها لا تقاطع تجربة المستخدم، لا تحتاج إلى إذنه.
حالات الاستخدام المحتمَلة
تشمل أمثلة التطبيقات التي قد تستخدم واجهة برمجة التطبيقات هذه ما يلي:
- تطبيقات الدردشة والبريد الإلكتروني ووسائل التواصل الاجتماعي للإشارة إلى وصول رسائل جديدة أو ل عرض عدد العناصر غير المقروءة
- تطبيقات الإنتاجية، للإشارة إلى اكتمال مهمة طويلة الأمد في الخلفية (مثل عرض صورة أو فيديو)
- الألعاب، للإشارة إلى أنّه على اللاعب اتّخاذ إجراء (مثلاً، في لعبة الشطرنج، عندما يكون الدور على اللاعب)
الدعم
تعمل واجهة برمجة التطبيقات App Badging API على نظامَي التشغيل Windows وmacOS، في الإصدار 81 من Chrome والإصدار 81 من Edge أو الإصدارات الأحدث. لا تزال ميزة "التبديل السريع" غير متاحة لنظام التشغيل ChromeOS، ولكنّها قيد التطوير وستتوفّر في إصدار قادم. لا تتوفّر واجهة برمجة التطبيقات Badging API على نظام التشغيل Android. بدلاً من ذلك، يعرض Android تلقائيًا شارة على رمز تطبيق الويب المثبَّت عند توفُّر إشعار لم تتم قراءته، تمامًا كما هو الحال مع تطبيقات Android.
تجربة الميزة
- افتح الإصدار التجريبي من App Badging API.
- انقر على تثبيت لتثبيت التطبيق عندما يُطلب منك ذلك، أو استخدِم ملف Chrome القائمة لتثبيته.
- افتح التطبيق كتطبيق ويب تقدّمي مثبّت. يُرجى العلم أنّه يجب تشغيل التطبيق كتطبيق مُثبَّت من التطبيقات المتوافقة مع الأجهزة الجوّالة (PWA) (في شريط التطبيقات أو شريط التطبيقات المضمّنة).
- انقر على الزر ضبط أو محو لضبط الشارة أو محوها من رمز التطبيق. يمكنك أيضًا تقديم رقم لـ قيمة الشارة.
كيفية استخدام واجهة برمجة التطبيقات 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.
أخبِرنا عن تصميم واجهة برمجة التطبيقات.
هل هناك مشكلة في واجهة برمجة التطبيقات لا تعمل على النحو المتوقّع؟ أم هل هناك methods أو properties مفقودة تحتاجها لتنفيذ فكرتك؟ هل لديك سؤال أو تعليق حول نموذج الأمان؟
- يمكنك الإبلاغ عن مشكلة في المواصفات على مستودع GitHub الخاص بواجهة برمجة التطبيقات Badging API، أو إضافة ملاحظاتك إلى مشكلة حالية.
الإبلاغ عن مشكلة في التنفيذ
هل رصدت خطأ في عملية تنفيذ Chrome؟ أم هل التنفيذ مختلف عن المواصفات؟
- يُرجى إرسال بلاغ عن الخطأ على الرابط https://new.crbug.com. احرص على تضمين أكبر قدر ممكن من التفاصيل، وتعليمات بسيطة لإعادة إنتاج الخطأ، واضبط المكوّنات على
UI>Browser>WebAppInstalls. إنّ تطبيق Glitch مثالي لمشاركة إعادة إنتاج سريعة وسهلة.
إظهار الدعم لواجهة برمجة التطبيقات
هل تخطّط لاستخدام واجهة برمجة التطبيقات App Badging API على موقعك الإلكتروني؟ يساعد دعمك العلني فريق Chrome في تحديد أولويات الميزات، ويُظهر لموفّري المتصفّحات الآخرين مدى أهمية دعمها.
- أرسِل تغريدة إلى @ChromiumDev باستخدام الهاشتاغ
#BadgingAPIوأطلِعنا على مكان استخدامك للميزة وطريقة استخدامك لها.
روابط مفيدة
- شرح موجز للجمهور العام
- مسودة المواصفات
- الإصدار التجريبي من Badging API | مصدر الإصدار التجريبي من Badging API
- خطأ في التتبّع
- إدخال ChromeStatus.com
- مكوّن Blink:
UI>Browser>WebAppInstalls
صورة رئيسية من أعمال براتيك كاتيال على Unsplash