نشان برای نمادهای برنامه

App Badging API به برنامه‌های وب نصب‌شده اجازه می‌دهد تا نشانی در سطح برنامه را روی نماد برنامه تنظیم کنند.

پیت لی پیج

App Badging API چیست؟

نمونه ای از توییتر با هشت اعلان و برنامه دیگری که نشان نوع پرچم را نشان می دهد.
نمونه ای از توییتر با هشت اعلان و برنامه دیگری که نشان نوع پرچم را نشان می دهد.

App Badging API به برنامه‌های وب نصب‌شده اجازه می‌دهد تا نشانی را در سطح برنامه تنظیم کنند، که در یک مکان خاص سیستم عامل مرتبط با برنامه (مانند قفسه یا صفحه اصلی) نشان داده می‌شود.

نشان دادن نشان دادن به کاربر را آسان می کند که فعالیت جدیدی وجود دارد که ممکن است به توجه او نیاز داشته باشد، یا نشان دادن مقدار کمی از اطلاعات، مانند تعداد خوانده نشده، آسان است.

نشان‌ها نسبت به اعلان‌ها کاربرپسندتر هستند و می‌توانند با فرکانس بسیار بالاتری به‌روزرسانی شوند، زیرا باعث ایجاد وقفه در کاربر نمی‌شوند. و چون کاربر را قطع نمی کنند، نیازی به اجازه کاربر ندارند.

موارد استفاده احتمالی

نمونه هایی از برنامه هایی که ممکن است از این API استفاده کنند عبارتند از:

  • برنامه‌های چت، ایمیل و اجتماعی برای نشان دادن دریافت پیام‌های جدید یا نشان دادن تعداد موارد خوانده نشده.
  • برنامه های بهره وری، برای نشان دادن اینکه یک کار پس زمینه طولانی مدت (مانند رندر کردن یک تصویر یا ویدیو) تکمیل شده است.
  • بازی‌ها، برای نشان دادن این که یک عمل بازیکن مورد نیاز است (به عنوان مثال، در شطرنج، زمانی که نوبت بازیکن است).

حمایت کردن

App Badging API روی Windows و macOS در Chrome 81 و Edge 81 یا جدیدتر کار می‌کند. پشتیبانی از ChromeOS در حال توسعه است و در نسخه بعدی در دسترس خواهد بود. در اندروید، Badging API پشتیبانی نمی‌شود. در عوض، آندروید به طور خودکار نشانی را روی نماد برنامه برای برنامه وب نصب‌شده نشان می‌دهد، همانطور که برای برنامه‌های اندرویدی اعلان خوانده‌نشده وجود دارد.

آن را امتحان کنید

  1. نسخه نمایشی App Badging API را باز کنید.
  2. هنگامی که از شما خواسته شد، برای نصب برنامه روی Install کلیک کنید یا از منوی Chrome برای نصب آن استفاده کنید.
  3. آن را به عنوان یک PWA نصب شده باز کنید. توجه داشته باشید، باید به عنوان یک PWA نصب شده (در نوار وظیفه یا داک شما) اجرا شود.
  4. برای تنظیم یا پاک کردن نشان از نماد برنامه، روی دکمه تنظیم یا پاک کردن کلیک کنید. همچنین می توانید یک عدد برای مقدار Badge ارائه کنید.

نحوه استفاده از 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 در اندروید پشتیبانی نمی‌شود، اندروید فقط یک نقطه را به جای مقدار عددی نشان می‌دهد.

در مورد نحوه نمایش نشان توسط نماینده کاربر هیچ چیز را فرض نکنید. برخی از عوامل کاربر ممکن است عددی مانند "4000" را بگیرند و آن را به عنوان "99+" بازنویسی کنند. اگر نشان را خودتان اشباع کنید (مثلاً با تنظیم آن روی "99")، "+" ظاهر نمی شود. مهم نیست که شماره واقعی باشد، فقط با setAppBadge(unreadCount) تماس بگیرید و به نماینده کاربر اجازه دهید مطابق با آن نمایش داده شود.

در حالی که App Badging API در Chrome به یک برنامه نصب شده نیاز دارد، شما نباید با Badging API وابسته به وضعیت نصب تماس بگیرید. فقط کافی است در صورت وجود API تماس بگیرید، زیرا مرورگرهای دیگر ممکن است نشان را در مکان های دیگر نشان دهند. اگر کار کند، کار می کند. اگر نه، به سادگی اینطور نیست.

تنظیم و پاک کردن نشان در پس‌زمینه از یک کارگر خدمات

همچنین می‌توانید با استفاده از سرویس‌کار، نشان برنامه را در پس‌زمینه تنظیم کنید. این کار را از طریق همگام سازی دوره ای پس زمینه، Push API یا ترکیبی از هر دو انجام دهید.

همگام سازی دوره ای پس زمینه

همگام‌سازی دوره‌ای پس‌زمینه به یک سرویس‌گر اجازه می‌دهد تا به طور دوره‌ای از سرور نظرسنجی کند، که می‌تواند برای دریافت وضعیت به‌روز شده استفاده شود و navigator.setAppBadge() را فراخوانی کند.

با این حال، فرکانس فراخوانی همگام‌سازی کاملاً قابل اعتماد نیست و بنا به صلاحدید مرورگر نامیده می‌شود.

Web Push API

Push API به سرورها اجازه می‌دهد تا پیام‌هایی را به کارکنان سرویس ارسال کنند، که می‌توانند کد جاوا اسکریپت را حتی زمانی که هیچ صفحه پیش‌زمینه اجرا نمی‌شود، اجرا کنند. بنابراین، یک فشار سرور می‌تواند با فراخوانی navigator.setAppBadge() نشان را به‌روزرسانی کند.

با این حال، اکثر مرورگرها، از جمله کروم، نیاز دارند که هر زمان که پیام فشاری دریافت می‌شود، یک اعلان نمایش داده شود. این برای برخی موارد استفاده خوب است (مثلاً نشان دادن اعلان هنگام به‌روزرسانی نشان) اما به‌روزرسانی نامحسوس نشان را بدون نمایش اعلان غیرممکن می‌کند.

علاوه بر این، کاربران برای دریافت پیام های فشاری باید مجوز اطلاع رسانی سایت شما را بدهند.

ترکیبی از هر دو

در حالی که کامل نیست، استفاده از Push API و همگام سازی دوره ای پس زمینه با هم راه حل خوبی را ارائه می دهد. اطلاعات با اولویت بالا از طریق Push API ارائه می‌شود و یک اعلان را نشان می‌دهد و نشان را به‌روزرسانی می‌کند. و اطلاعات با اولویت پایین‌تر با به‌روزرسانی نشان، یا زمانی که صفحه باز است، یا از طریق همگام‌سازی دوره‌ای پس‌زمینه، ارائه می‌شود.

بازخورد

تیم Chrome می‌خواهد درباره تجربیات شما با App Badging API بشنود.

در مورد طراحی API به ما بگویید

آیا چیزی در API وجود دارد که آنطور که انتظار داشتید کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟ آیا در مورد مدل امنیتی سوال یا نظری دارید؟

  • یک مشکل مشخصات را در مخزن Badging API GitHub ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در اجرا

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

  • یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا آنجا که می توانید جزئیات، دستورالعمل های ساده برای بازتولید، و Components را روی UI>Browser>WebAppInstalls قرار دهید. Glitch برای به اشتراک گذاری بازتولیدهای سریع و آسان عالی عمل می کند.

پشتیبانی از API را نشان دهید

آیا قصد دارید از App Badging API در سایت خود استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کند، و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

  • با استفاده از هشتگ #BadgingAPI یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

عکس قهرمان توسط Prateek Katyal در Unsplash

،

App Badging API به برنامه‌های وب نصب‌شده اجازه می‌دهد تا نشانی در سطح برنامه را روی نماد برنامه تنظیم کنند.

پیت لی پیج

App Badging API چیست؟

نمونه ای از توییتر با هشت اعلان و برنامه دیگری که نشان نوع پرچم را نشان می دهد.
نمونه ای از توییتر با هشت اعلان و برنامه دیگری که نشان نوع پرچم را نشان می دهد.

App Badging API به برنامه‌های وب نصب‌شده اجازه می‌دهد تا نشانی را در سطح برنامه تنظیم کنند، که در یک مکان خاص سیستم عامل مرتبط با برنامه (مانند قفسه یا صفحه اصلی) نشان داده می‌شود.

نشان دادن نشان دادن به کاربر را آسان می کند که فعالیت جدیدی وجود دارد که ممکن است به توجه او نیاز داشته باشد، یا نشان دادن مقدار کمی از اطلاعات، مانند تعداد خوانده نشده، آسان است.

نشان‌ها نسبت به اعلان‌ها کاربرپسندتر هستند و می‌توانند با فرکانس بسیار بالاتری به‌روزرسانی شوند، زیرا باعث ایجاد وقفه در کاربر نمی‌شوند. و چون کاربر را قطع نمی کنند، نیازی به اجازه کاربر ندارند.

موارد استفاده احتمالی

نمونه هایی از برنامه هایی که ممکن است از این API استفاده کنند عبارتند از:

  • برنامه‌های چت، ایمیل و اجتماعی برای نشان دادن دریافت پیام‌های جدید یا نشان دادن تعداد موارد خوانده نشده.
  • برنامه های بهره وری، برای نشان دادن اینکه یک کار پس زمینه طولانی مدت (مانند رندر کردن یک تصویر یا ویدیو) تکمیل شده است.
  • بازی‌ها، برای نشان دادن این که یک عمل بازیکن مورد نیاز است (به عنوان مثال، در شطرنج، زمانی که نوبت بازیکن است).

حمایت کردن

App Badging API روی Windows و macOS در Chrome 81 و Edge 81 یا جدیدتر کار می‌کند. پشتیبانی از ChromeOS در حال توسعه است و در نسخه بعدی در دسترس خواهد بود. در اندروید، Badging API پشتیبانی نمی‌شود. در عوض، آندروید به طور خودکار نشانی را روی نماد برنامه برای برنامه وب نصب‌شده نشان می‌دهد، همانطور که برای برنامه‌های اندرویدی اعلان خوانده‌نشده وجود دارد.

آن را امتحان کنید

  1. نسخه نمایشی App Badging API را باز کنید.
  2. هنگامی که از شما خواسته شد، برای نصب برنامه روی Install کلیک کنید یا از منوی Chrome برای نصب آن استفاده کنید.
  3. آن را به عنوان یک PWA نصب شده باز کنید. توجه داشته باشید، باید به عنوان یک PWA نصب شده (در نوار وظیفه یا داک شما) اجرا شود.
  4. برای تنظیم یا پاک کردن نشان از نماد برنامه، روی دکمه تنظیم یا پاک کردن کلیک کنید. همچنین می توانید یک عدد برای مقدار Badge ارائه کنید.

نحوه استفاده از 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 در اندروید پشتیبانی نمی‌شود، اندروید فقط یک نقطه را به جای مقدار عددی نشان می‌دهد.

در مورد نحوه نمایش نشان توسط نماینده کاربر هیچ چیز را فرض نکنید. برخی از عوامل کاربر ممکن است عددی مانند "4000" را بگیرند و آن را به عنوان "99+" بازنویسی کنند. اگر نشان را خودتان اشباع کنید (مثلاً با تنظیم آن روی "99")، "+" ظاهر نمی شود. مهم نیست که شماره واقعی باشد، فقط با setAppBadge(unreadCount) تماس بگیرید و به نماینده کاربر اجازه دهید مطابق با آن نمایش داده شود.

در حالی که App Badging API در Chrome به یک برنامه نصب شده نیاز دارد، شما نباید با Badging API وابسته به وضعیت نصب تماس بگیرید. فقط کافی است در صورت وجود API تماس بگیرید، زیرا مرورگرهای دیگر ممکن است نشان را در مکان های دیگر نشان دهند. اگر کار کند، کار می کند. اگر نه، به سادگی اینطور نیست.

تنظیم و پاک کردن نشان در پس‌زمینه از یک کارگر خدمات

همچنین می‌توانید با استفاده از سرویس‌کار، نشان برنامه را در پس‌زمینه تنظیم کنید. این کار را از طریق همگام سازی دوره ای پس زمینه، Push API یا ترکیبی از هر دو انجام دهید.

همگام سازی دوره ای پس زمینه

همگام‌سازی دوره‌ای پس‌زمینه به یک سرویس‌گر اجازه می‌دهد تا به طور دوره‌ای از سرور نظرسنجی کند، که می‌تواند برای دریافت وضعیت به‌روز شده استفاده شود و navigator.setAppBadge() را فراخوانی کند.

با این حال، فرکانس فراخوانی همگام‌سازی کاملاً قابل اعتماد نیست و بنا به صلاحدید مرورگر نامیده می‌شود.

Web Push API

Push API به سرورها اجازه می‌دهد تا پیام‌هایی را به کارکنان سرویس ارسال کنند، که می‌توانند کد جاوا اسکریپت را حتی زمانی که هیچ صفحه پیش‌زمینه اجرا نمی‌شود، اجرا کنند. بنابراین، یک فشار سرور می‌تواند با فراخوانی navigator.setAppBadge() نشان را به‌روزرسانی کند.

با این حال، اکثر مرورگرها، از جمله کروم، نیاز دارند که هر زمان که پیام فشاری دریافت می‌شود، یک اعلان نمایش داده شود. این برای برخی موارد استفاده خوب است (مثلاً نشان دادن اعلان هنگام به‌روزرسانی نشان) اما به‌روزرسانی نامحسوس نشان را بدون نمایش اعلان غیرممکن می‌کند.

علاوه بر این، کاربران برای دریافت پیام های فشاری باید مجوز اطلاع رسانی سایت شما را بدهند.

ترکیبی از هر دو

در حالی که کامل نیست، استفاده از Push API و همگام سازی دوره ای پس زمینه با هم راه حل خوبی را ارائه می دهد. اطلاعات با اولویت بالا از طریق Push API ارائه می‌شود و یک اعلان را نشان می‌دهد و نشان را به‌روزرسانی می‌کند. و اطلاعات با اولویت پایین‌تر با به‌روزرسانی نشان، یا زمانی که صفحه باز است، یا از طریق همگام‌سازی دوره‌ای پس‌زمینه، ارائه می‌شود.

بازخورد

تیم Chrome می‌خواهد درباره تجربیات شما با App Badging API بشنود.

در مورد طراحی API به ما بگویید

آیا چیزی در API وجود دارد که آنطور که انتظار داشتید کار نمی کند؟ یا آیا روش ها یا ویژگی هایی وجود دارد که برای اجرای ایده خود به آنها نیاز دارید؟ آیا در مورد مدل امنیتی سوال یا نظری دارید؟

  • یک مشکل مشخصات را در مخزن Badging API GitHub ثبت کنید یا افکار خود را به یک مشکل موجود اضافه کنید.

گزارش مشکل در اجرا

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

  • یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا آنجا که می توانید جزئیات، دستورالعمل های ساده برای بازتولید، و Components را روی UI>Browser>WebAppInstalls قرار دهید. Glitch برای به اشتراک گذاری بازتولیدهای سریع و آسان عالی عمل می کند.

پشتیبانی از API را نشان دهید

آیا قصد دارید از App Badging API در سایت خود استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کند، و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

  • با استفاده از هشتگ #BadgingAPI یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

عکس قهرمان توسط Prateek Katyal در Unsplash