バッジ API

badgeは、インストール済みのWebアプリケーションが、ユーザーに注意を促す必要のある新しいアクティビティがあることを通知したり、未読数などの少量の情報を示すためのメカニズムとして意図されています。

badgeは、次のvaluesのいずれかを持つことができます。

特別な値 "nothing":

現在バッジが設定されていないことを示します。badgeがこの値を持つ場合、ユーザーに視覚的なインジケーターは表示されません。

特別な値 "flag":

バッジが設定されており、ユーザーに表示されるべきであることを示しますが、特定の数値は含まれません。これは"nothing"とは異なり、バッジの存在を示す視覚的インジケーターがユーザーに表示されます。

number値:

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

インストール済みのウェブアプリケーションには、関連付けられたbadgeがあり、初期値は"nothing"です。オペレーティングシステムがバッジ値を保存・管理し、ユーザーエージェントがOSへのバッジ変更通知の仲介役を担います。

ユーザーエージェントは任意で（再）アプリケーションのバッジを "nothing"に設定してもよい（例えば、システムの慣例に従う場合など）。

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

ユーザーエージェントは任意でユーザーから明示的な許可を得て バッジを設定することができます。ユーザーエージェントがそのような 許可を必要とする場合は、 推奨として "通知"の許可と関連付けるべきです。

バッジが"flag"に設定されている場合、ユーザーエージェントまたはオペレーティングシステムは推奨として 非特定のシンボル（例: 色付きの円）でインジケーターを表示するべきです。プラットフォームが"flag"バッジの表示に対応していない場合、ユーザーエージェントは推奨として バッジの存在を示す最も近い表現（例: 値 "1" など）で表示し、バッジを完全にクリアしないことが望ましいです。

バッジの値が"nothing"に設定された場合、 ユーザーエージェントまたはオペレーティングシステムは 推奨としてクリアし、バッジの表示をやめるべきです。

バッジが数値に設定された場合、number、ユーザーエージェントまたはオペレーティングシステムは以下を行うべきです:

• 推奨として、ユーザーのフォントと書式設定の好みに従って数値を整形・表示する。例: デバイスのホーム画面でアプリのアイコン上に円内の数字として表示するなど。
• 任意で、バッジの数値の値を プラットフォームのバッジ表示慣習に合わせて簡略化・変形してもよい。例: '100' という値を '99+' と表示する場合など。
• 推奨として、数値をユーザーのロケール設定に従ってローカライズする。例: ロケール 'en'（英語）では '7'、'ar'（アラビア語）では '٧' のように表示する。
• 任意で、数値の値を"flag"やプラットフォームに最適な表現として扱ってもよい。プラットフォームが数値バッジの表示に対応していない場合も同様です。また、プラットフォームが"flag"バッジに対応していない場合は、任意で、"flag"を数値やその他の適切な視覚的インジケーターで表現してもよいですが、必須として "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. document の 関連設定オブジェクト の オリジン が、this の 関連設定オブジェクト の トップレベルオリジンと 同一オリジンドメインでない場合、拒否された promise を "SecurityError" DOMException で返す。
3. promise を 新しい promiseとする。
4. 並列で:
   1. ユーザーエージェントが 明示的な許可を アプリケーションバッジの設定に必要とする場合:
      1. permissionState を "notifications" で 現在の権限状態を取得した結果とする。
      2. permissionState が "granted" でない場合、 グローバルタスクをキューし、 ユーザー操作タスクソース global で promiseを拒否し、 NotAllowedError でこのアルゴリズムを終了する。
   2. contents に応じて分岐する:

      contents が渡されなかった場合:

      バッジ を "flag" に設定する。

      contents が 0 の場合:

      バッジ を "nothing" に設定する。

      contents の場合:

      バッジ を contents に設定する。

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

このAPIは設計上書き込み専用です。サイトが以前に設定したバッジの値を読み戻す方法はなく、アプリケーションバッジがストレージやフィンガープリント手段として利用されるのを防ぎます。

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

ユーザーエージェントは、バッジの設定 やクリアをレート制限することができる（MAY）。これは、注意をそらすアニメーションを防ぎ、リソース使用量を低減するためです。しかし、ユーザーエージェントは一般的にレート制限をオペレーティングシステムに任せるべき（SHOULD）です。オペレーティングシステムの方が、システム負荷、ユーザー設定、アクセシビリティの観点から適切な制限を判断できるためです。

アプリケーションバッジは、ユーザーの注意を要するステータスを伝えます。 バッジはしばしばウェブコンテンツ領域外（たとえば、ドック内のアプリアイコン上など）で表示されるため、 ユーザーエージェントは、情報がプラットフォームのアクセシビリティ機能やユーザーの設定を通じて アクセス可能かつ制御可能な状態を保つ必要があります。

非規範と明記されているセクションだけでなく、この仕様書のすべての著作ガイドライン、図、例、および注記も非規範です。それ以外の内容はすべて規範的です。

この文書中のキーワード MAY、MUST、MUST NOT、SHOULD、SHOULD NOT は、すべて大文字で記載されている場合に限り BCP 14 [RFC2119] および [RFC8174] の定義に従って解釈されます。