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