バッジAPI

バッジは、インストール済みウェブアプリケーションがユーザーに新しい活動があり注意が必要であることを通知したり、未読数など少量の情報を示すための仕組みです。

バッジは、以下の値のいずれかを持つことができます：

特別な値 "nothing"：

現在バッジが設定されていないことを示します。

特別な値 "flag"：

バッジが設定されているが、特定の値は持たないことを示します。

数値値：

バッジが設定され、0より大きい数値が指定されていることを示します。

インストール済みウェブアプリケーションには、関連付けられたバッジがあり、初期状態は"nothing"です。

ユーザーエージェントは、（再）設定する際に、アプリケーションのバッジを"nothing"にする場合があります（例：システムの慣例に従う場合）。

アプリケーションのバッジが設定されている場合、ユーザーエージェントまたはオペレーティングシステムは、ユーザーのオペレーティングシステム上でアプリケーションの主要なアイコン表現の横にバッジを表示すべきです（例：デバイスのホーム画面上のアプリアイコンの上に小さなオーバーレイとして）。

ユーザーエージェントは、バッジの明示的な許可をユーザーから要求する場合があります。その場合、すべきです許可の付与を"notifications"権限に紐付けます。

バッジが設定され、その値が"flag"の場合、ユーザーエージェント またはオペレーティングシステムは、非特定のシンボル（例：色付きの円）でインジケーターを表示すべきです。

バッジの値が設定され、"nothing"の場合、ユーザーエージェントまたはオペレーティングシステムは消去を行い、表示を停止すべきです。

バッジが設定され、値が数値の場合、ユーザーエージェント またはオペレーティングシステムは：

• すべきですユーザーのフォントや書式設定の好みに従って数値を整形・表示します。例えば、デバイスのホーム画面上のアプリアイコンの上に円内の数値として表示されます。
• できますバッジの数値値を、バッジで数値を表現するプラットフォームの慣例に合わせて簡略化・省略することができます。例：'100'という値を'99+'として表示する場合があります。
• すべきですユーザーのロケールの好みに従って数値をローカライズします。例：値 '7'はロケール'en'（英語）では'7'、'ar'（アラビア語）では'٧'として表示されます。
• できますプラットフォームがバッジで数値を表示できない場合は、値を"flag"またはプラットフォームに最適な表現として扱うことができます。

WebIDL[SecureContext]
interface mixin NavigatorBadge {
  Promise<undefined> setAppBadge(
    optional [EnforceRange] unsigned long long contents
  );
  Promise<undefined> clearAppBadge();
};

Navigator includes NavigatorBadge;
WorkerNavigator includes NavigatorBadge;

アプリケーションバッジを一切表示しないユーザーエージェントは、含めるべきではありません include NavigatorBadge。

プラットフォームオブジェクトcontextのアプリケーションバッジを設定するには、オプションのunsigned long long contents値を使います：

1. globalをcontextの関連グローバルオブジェクトとする。
2. globalがWindow オブジェクトなら：
   1. documentをglobalの関連付けられた Documentとする。
   2. documentが完全にアクティブでなければ、却下されたpromiseを返し、エラーは"InvalidStateError"、DOMExceptionとします。
3. promiseを新しいpromiseとする。
4. 並列で：
   1. thisの関連設定オブジェクトのオリジンが、thisの関連設定オブジェクトの トップレベルオリジン と同一オリジンでない場合、グローバルタスクをキューし、promiseを"SecurityError"で却下して、このアルゴリズムを終了します。
   2. ユーザーエージェントが明示的な許可を必要とする場合、アプリケーションバッジの設定について：
      1. permissionStateを、"notifications"で現在の権限状態を取得した結果とする。
      2. permissionStateが"granted"でなければ、 グローバルタスクをキューし、ユーザー操作タスクソース でglobalに対してpromiseをrejectし、NotAllowedErrorでこのアルゴリズムを終了します。
   3. contentsについて分岐し、以下の場合：

      contentsが渡されていない場合：

      badgeを"flag"に設定します。

      contentsが0の場合：

      badgeを"nothing"に設定します。

      contents：

      badgeをcontentsに設定します。

   4. グローバルタスクをキューし、DOM操作タスクソース でglobalに対して、resolveし、promiseをundefinedで解決します。
5. promiseを返します。

このAPIは設計上、書き込み専用です。バッジの値をサイト側で読み取る方法は存在せず、これによりアプリケーションバッジがストレージやフィンガープリンティングの仕組みとして利用されることを防いでいます。

ユーザーエージェントやオペレーティングシステムは任意で、バッジを消去することができ、システムの慣例（例：システムリセット時）に従うこともあります。

規定ではないと明記されたセクションだけでなく、この仕様書中のすべての著者向けガイドライン、図、例、注釈は規定ではありません。それ以外の内容はすべて規定事項です。

この文書内のキーワード MAY、MUST、SHOULD、 SHOULD NOT は、 BCP 14 [RFC2119] [RFC8174] の記載通りに解釈されます（すべて大文字で記述された場合のみ）。