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

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

Pete LePage

ما هي App Badging API؟

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

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

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

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

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

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

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

الدعم

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

تجربة الإيماءة

  1. افتح العرض التوضيحي لواجهة برمجة التطبيقات Badging API.
  2. انقر على تثبيت لتثبيت التطبيق أو استخدِم قائمة Chrome لتثبيته عندما يُطلب منك ذلك.
  3. افتح تطبيق الويب التقدّمي (PWA) مثبَّتًا. ملاحظة: يجب أن يعمل التطبيق كتطبيق ويب تقدّمي (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) والسماح لوكيل المستخدم بالتعامل معه وفقًا لذلك.

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

وضع الشارة ومحوها في الخلفية من عامل خدمات

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

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

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

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

واجهة برمجة تطبيقات Web Push

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

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

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

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

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

إضافة ملاحظات

يرغب فريق Chrome في معرفة رأيك بتجاربك في استخدام App Badging API.

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

هل هناك شيء في واجهة برمجة التطبيقات لا يعمل كما توقعت؟ أو هل هناك طرق أو خصائص مفقودة تحتاج إلى تنفيذ فكرتك؟ هل لديك سؤال أو تعليق على نموذج الأمان؟

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

هل واجهت خطأً في تنفيذ Chrome؟ أم أن التنفيذ مختلف عن المواصفات؟

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

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

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

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

روابط مفيدة

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