Interfejs App Badging API umożliwia zainstalowanym aplikacjom internetowym ustawienie plakietki na ikonie aplikacji.
Czym jest interfejs App Badging API?
Interfejs App Badging API umożliwia zainstalowanym aplikacjom internetowym ustawienie plakietki dla całej aplikacji, która jest wyświetlana w miejscu powiązanym z aplikacją w danym systemie operacyjnym (np. na półce lub ekranie głównym).
Plakietki ułatwiają subtelne informowanie użytkownika o nowej aktywności, która może wymagać jego uwagi, lub o małej ilości informacji, np. o liczbie nieprzeczytanych wiadomości.
Plakietki są zazwyczaj bardziej przyjazne użytkownikowi niż powiadomienia i można je aktualizować znacznie częściej, ponieważ nie przerywają one pracy użytkownika. Ponieważ nie zakłócają one działania użytkownika, nie potrzebują jego zgody.
Możliwe zastosowania
Przykłady aplikacji, które mogą używać tego interfejsu API:
- do czatowania, do obsługi poczty e-mail i aplikacji społecznościowych, aby sygnalizować odebranie nowych wiadomości lub pokazywać liczbę nieprzeczytanych elementów.
- aplikacje zwiększające produktywność, które sygnalizują, że długo trwające zadanie w tle (takie jak renderowanie obrazu lub filmu) zostało zakończone.
- gry, aby zasygnalizować, że wymagane jest działanie gracza (np. w szachach, gdy nadszedł jego ruch);
Pomoc
Interfejs App Badging API działa w systemach Windows i macOS w Chrome 81 i Edge 81 lub nowszych. Pracujemy nad obsługą ChromeOS, która będzie dostępna w przyszłej wersji. Na Androidzie interfejs Badging API nie jest obsługiwany. Zamiast tego, gdy pojawi się nieprzeczytane powiadomienie, Android automatycznie wyświetla plakietkę na ikonie zainstalowanej aplikacji internetowej (tak jak w przypadku aplikacji na Androida).
Wypróbuj
- Otwórz demonstrację interfejsu App Badging API.
- Gdy pojawi się odpowiedni komunikat, kliknij Zainstaluj, aby zainstalować aplikację, lub użyj menu Chrome.
- Otwórz ją jako zainstalowaną aplikację PWA. Pamiętaj, że musi ona działać jako zainstalowana PWA (na pasku aplikacji lub na docku).
- Kliknij przycisk Ustaw lub Wyczyść, aby ustawić lub usunąć plakietkę z ikony aplikacji. Możesz też podać liczbę w polu Wartość plakietki.
Jak korzystać z interfejsu App Badging API
Aby móc korzystać z interfejsu App Badging API, aplikacja internetowa musi spełniać kryteria instalowalności w Chrome, a użytkownicy muszą dodać ją do ekranu głównego.
Interfejs Badge API składa się z 2 metod na navigator
:
setAppBadge(
number
)
: ustawia plakietkę aplikacji. Jeśli została podana, ustaw podaną wartość plakietki, w przeciwnym razie wyświetlaj białą kropkę (albo inną flagę odpowiednią do danej platformy). Ustawienie parametrunumber
na0
jest równoznaczne z wywołaniem funkcjiclearAppBadge()
.clearAppBadge()
: usuwa plakietkę aplikacji.
Obie zwracają puste obietnice, których możesz użyć do obsługi błędów.
Plakietkę można ustawić na bieżącej stronie lub w zarejestrowanym skrypcie service worker. Aby ustawić lub wyczyścić plakietkę (na stronie pierwszego planu lub w usługach workera), wywołaj:
// 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.
});
W niektórych przypadkach system operacyjny może nie zezwalać na dokładne wyświetlanie plakietki. W takich przypadkach przeglądarka będzie próbować wyświetlić najlepszą wersję dla danego urządzenia. Na przykład, ponieważ interfejs Badging API nie jest obsługiwany na Androidzie, Android wyświetla tylko kropkę zamiast wartości liczbowej.
Nie zakładaj niczego na temat sposobu wyświetlania plakietki przez klienta użytkownika.
Niektóre przeglądarki mogą zamienić liczbę, np. „4000”, na „99+”. Jeśli sam spróbujesz nasycić plakietkę (np. ustawiając ją na „99”), znak „+” nie będzie widoczny. Niezależnie od tego, jaki jest rzeczywisty numer, po prostu wywołaj funkcję setAppBadge(unreadCount)
, a agent użytkownika zajmie się wyświetleniem go.
Chociaż interfejs API do generowania plakietki aplikacji w Chrome wymaga zainstalowanej aplikacji, nie należy wywoływać interfejsu API do generowania plakietki w zależności od stanu instalacji. Wystarczy wywołać interfejs API, gdy już istnieje. Inne przeglądarki mogą wyświetlać plakietkę w innych miejscach. Jeśli działa, to znaczy, że działa. Jeśli nie, to po prostu nie.
Ustawianie i czyszczenie plakietki w tle z użyciem service workera
Możesz też ustawić plakietkę aplikacji w tle za pomocą skryptu service worker. Możesz to zrobić za pomocą okresowej synchronizacji w tle, interfejsu Push API lub ich kombinacji.
Okresowa synchronizacja w tle
Okresowa synchronizacja w tle umożliwia mechanizmowi service worker przeprowadzanie okresowych sondowania serwera w celu uzyskania zaktualizowanego stanu i wywołania funkcji navigator.setAppBadge()
.
Częstotliwość wywoływania synchronizacji nie jest jednak całkowicie niezawodna i zależy od przeglądarki.
Interfejs Web Push API
Push API umożliwia serwerom wysyłanie wiadomości do usług działających w tle, które mogą uruchamiać kod JavaScript nawet wtedy, gdy nie działa żadna strona w tle. W związku z tym aktualizacja plakietki może być wywoływana przez push z serwera, który wywołuje funkcję navigator.setAppBadge()
.
Jednak większość przeglądarek, w tym Chrome, wymaga wyświetlania powiadomienia za każdym razem, gdy otrzymasz powiadomienie push. Jest to odpowiednie w niektórych przypadkach użycia (np. wyświetlanie powiadomienia podczas aktualizowania plakietki), ale uniemożliwia drobną zmianę plakietki bez wyświetlania powiadomienia.
Dodatkowo użytkownicy muszą przyznać witrynie uprawnienia do powiadomień, aby otrzymywać wiadomości push.
kombinacja obu typów.
Chociaż nie jest to idealne rozwiązanie, korzystanie z interfejsu Push API i okresowej synchronizacji w tle stanowi dobre rozwiązanie. Informacje o wysokiej priorytecie są dostarczane za pomocą interfejsu API Push, wyświetlając powiadomienie i aktualizując plakietkę. Informacje o mniejszym priorytecie są dostarczane przez aktualizację plakietki, gdy strona jest otwarta, lub przez okresową synchronizację w tle.
Prześlij opinię
Zespół Chrome chce poznać Twoją opinię o interfejsie App Badging API.
Prześlij informacje o projektowaniu interfejsu API
Czy coś w interfejsie API nie działa zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, których potrzebujesz do wdrożenia swojego pomysłu? Masz pytania lub uwagi dotyczące modelu bezpieczeństwa?
- Zgłoś problem ze specyfikacją w repozytorium Badging API na GitHubie lub dodaj swoje uwagi do istniejącego problemu.
Zgłaszanie problemów z implementacją
Czy znalazłeś/znalazłaś błąd w implementacji Chrome? Czy implementacja różni się od specyfikacji?
- Zgłoś błąd na stronie https://new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtworzenia błędu i ustaw Składniki na
UI>Browser>WebAppInstalls
. Glitch świetnie sprawdza się do udostępniania szybkich i prostych reprodukcji.
Pokaż informacje o pomocy dotyczącej interfejsu API
Planujesz użyć w swojej witrynie interfejsu App Badging API? Twoje publiczne wsparcie pomaga zespołowi Chrome ustalać priorytety funkcji, a innym dostawcom przeglądarek pokazuje, jak ważne jest, aby wspierać te funkcje.
- Wyślij tweeta do @ChromiumDev, używając hashtaga
#BadgingAPI
, i podaj, gdzie i jak go używasz.
Przydatne linki
- Publiczne wyjaśnienie
- Specyfikacja w wersji roboczej
- Przykładowy kod interfejsu Badging API | źródło przykładowego kodu Badging API
- Śledzenie błędu
- Wpis na temat ChromeStatus.com
- Składnik Blink:
UI>Browser>WebAppInstalls
Zdjęcie bohatera: Prateek Katyal, Unsplash