ビーコン

概要

この仕様は、リソースの競合を最小限に抑えながら、他の時間クリティカルな操作と非同期かつ非ブロッキングでデータを送信できるインターフェイスをウェブ開発者が利用できるように定義しています。その一方で、これらのリクエストが目的地に正しく処理されて配信されることを保証します。

このセクションは規範的ではありません。

ウェブアプリケーションは、イベント、状態更新、および分析データを1つ以上のサーバーに報告するリクエストを発行する必要がある場合があります。これらのリクエストは通常、クライアント側でのレスポンス処理を必要とせず（例: 204または200 HTTPレスポンスコードと空のレスポンスボディ）、重要なリソースのフェッチ、入力への反応、アニメーションの実行などの高優先度操作とネットワークおよび計算リソースを競合させるべきではありません。しかし、このような一方向リクエスト（ビーコン）は、重要なアプリケーションや計測データの配信も担当しており、開発者はその配信を確保するために高コストな方法を使用せざるを得ません：

開発者は、ビーコンの配信率を改善するために、配信を統合して遅延させる代わりに、各ビーコンを即時配信することを選びます。配信を遅延させることで、ビーコンリクエストが成功裏に完了するのに十分な時間が確保できない可能性があり、重要なアプリケーションデータが失われる可能性があります。
開発者は、同期XMLHttpRequestを介してブロッキングリクエストを発行したり、無操作のビジーループを挿入したり、他の技術を使用してユーザーエージェントが時間クリティカルな操作（例: クリック、アンロード、その他のハンドラー）を実行するのを阻止し、ユーザーエクスペリエンスを損なうことを選びます。このブロッキング動作は、ページがアンロードされたり、システムによって中断または終了された場合でも、ユーザーエージェントやオペレーティングシステムがリクエストをキャンセルしないようにするためのものです。

上記の配信および処理要件の不一致により、ほとんどの開発者が難しい選択を迫られ、ユーザーエクスペリエンスを損なうブロッキング技術が広く採用されています。この仕様では、リソース競合を最小限に抑えつつ、データの非同期かつ非ブロッキング配信をスケジュールできるインターフェースをウェブ開発者が利用できるように定義しています。このインターフェースは、次のことを保証します：

ビーコンリクエストは、時間クリティカルな操作および高優先度のネットワークリクエストと競合しないように優先順位が付けられます。
ビーコンリクエストは、モバイルデバイスのエネルギー使用量を最適化するために、ユーザーエージェントによって効率的に統合される場合があります。
ビーコンリクエストは、ページがアンロードされる前に必ず開始され、ユーザーのインタラクティブなイベントの処理をブロックするリクエストやその他の技術を必要とせずに、完了するまで実行されることが保証されます。

以下の例は、sendBeacon()メソッドを使用して、イベント、クリック、および分析データを配信する方法を示しています：

例 1

<html>
<script>
  // クライアント側イベントを記録する非ブロッキングビーコンを送信
  function reportEvent(event) {
    var data = JSON.stringify({
      event: event,
      time: performance.now()
    });
    navigator.sendBeacon('/collector', data);
  }

  // ページがバックグラウンド状態に移行するときに（ページ可視性API）、
  // セッション分析データを含む非ブロッキングビーコンを送信
  document.addEventListener('visibilitychange', function() {
    if (document.visibilityState === 'hidden') {
      var sessionData = buildSessionReport();
      navigator.sendBeacon('/collector', sessionData);
    }
  });
</script>

<body>
 <a href='http://www.w3.org/' onclick='reportEvent(this)'>
 <button onclick="reportEvent('some event')">クリックしてください</button>
</body>
</html>

注記

上記の例では、visibilitychange イベント（[PAGE-VISIBILITY-2]で定義）を使用してセッションデータの配信をトリガーします。このイベントは、ページがバックグラウンド状態に移行するとき（例: ユーザーが別のアプリケーションに切り替える、ホーム画面に戻るなど）やアンロードされるときに、モバイルデバイスで発火することが保証されている唯一のイベントです。 unloadイベントに依存することを避けてください。なぜなら、ページがバックグラウンド状態の場合（例: visibilityState がhiddenと等しい）モバイルOSによってプロセスが終了される場合には発火しないからです。

sendBeacon()メソッドを介して開始されたリクエストは、時間クリティカルな作業と競合したりブロックしたりせず、ユーザーエージェントによってネットワーク効率を改善するために優先順位付けされる可能性があり、ビーコンデータの配信を保証するためにブロッキング操作を使用する必要を排除します。

以下は、sendBeacon()が行わないこと、および解決を意図していないことです：

sendBeacon()メソッドは、オフラインストレージや配信の特別な処理を提供しません。ビーコンリクエストは他のリクエストと同様であり、必要に応じて[SERVICE-WORKERS]と組み合わせてオフライン機能を提供できます。
sendBeacon()メソッドは、バックグラウンド同期や転送機能を提供することを意図していません。ユーザーエージェントはビーコンリクエストが迅速かつタイムリーに完了できるよう、受け入れられるペイロードサイズを制限します。
sendBeacon()メソッドは、リクエストメソッドのカスタマイズ、カスタムリクエストヘッダーの提供、またはリクエストおよびレスポンスの処理プロパティの変更を提供しません。このようなリクエストに対してデフォルト設定以外が必要なアプリケーションは、[FETCH] APIをkeepaliveをtrueに設定して使用するべきです。

WebIDLpartial interface Navigator {
    boolean sendBeacon(USVString url, optional BodyInit? data = null);
};

sendBeacon()メソッドは、dataパラメーターで提供されるデータをurlパラメーターで指定されたURLに送信します：

ユーザーエージェントはkeepalive フラグを設定してフェッチを開始しなければなりません（MUST）。これにより、このようなリクエストでキューに入れられるデータ量が制限され、ビーコンリクエストが迅速かつタイムリーに完了できるようになります。
ドキュメントのvisibilityState がhidden に遷移した際に、すべてのビーコンリクエストを即座に送信するようスケジュールし、これらのリクエストが他の時間クリティカルな高優先度の作業をブロックすることなく完了できるようにしなければなりません（MUST）。
ユーザーエージェントは、提供されたデータの送信をスケジュールして、他の時間クリティカルで高優先度の作業とのリソース（CPUおよびネットワーク）競合を最小限に抑えるべきです（SHOULD）。
ユーザーエージェントは、ネットワークがアクティブな場合に即座に配信する、あるいはネットワークインターフェースがアクティブになるまで待機するなどして、ネットワークおよびエネルギー効率を最適化するために提供されたデータの送信を遅らせても良いです（MAY）。ただし、送信を無期限に遅らせるべきではありません（SHOULD NOT）。ネットワーク活動がない場合でも、保留中の送信は定期的にフラッシュされるべきです。

注記

Beacon APIはレスポンスコールバックを提供しません。このようなリクエストに対するレスポンスボディを省略すること（例：204 No Contentで応答する）が推奨されます。

urlパラメーターは、データを送信するURLを示します。

dataパラメーターは、送信されるBodyInitデータです。

sendBeacon()メソッドは、データを転送するために正常にキューに入れることができた場合はtrueを返します。それ以外の場合はfalseを返します。

注記

ユーザーエージェントは、このAPIを介して送信できるデータ量に制限を課します。これにより、このようなリクエストが他のユーザーやブラウザのアクティビティに最小限の影響を与えながら、正常に配信されることが保証されます。キューに入れられるdataの量がユーザーエージェントの制限を超えた場合（HTTP-network-or-cache fetchで定義されているように）、このメソッドはfalseを返します。trueの戻り値は、ブラウザがデータを転送のためにキューに入れたことを意味します。ただし、実際のデータ転送は非同期で行われるため、このメソッドはデータ転送が成功したかどうかについての情報を提供しません。

sendBeacon()メソッドをurlおよび必要に応じてdataと共に呼び出したとき、次の手順を実行します：

baseをthisの関連設定オブジェクトの API ベース URLに設定します。
originをthisの関連設定オブジェクトのオリジンに設定します。
parsedUrlをurlおよびbaseでURL パーサー手順を実行した結果に設定します。アルゴリズムがエラーを返す場合、またはparsedUrlのスキームが"http"または"https"でない場合は、"TypeError"例外をスローし、これらの手順を終了します。
headerListを空のリストに設定します。
corsModeを"no-cors"に設定します。
もしdataがnullでない場合：
1. transmittedDataおよびcontentTypeを、keepalive flagを設定してdataのバイトストリームを抽出した結果に設定します。
2. keepaliveが有効なリクエストで送信キューに入れることができるデータ量をtransmittedDataのサイズが超える場合（HTTP-network-or-cache fetchで定義されているように）、戻り値をfalseに設定し、これらの手順を終了します。
  
  注記
  
  Beacon APIによって開始されたリクエストは、自動的にkeepaliveフラグを設定します。同様に、開発者はFetch APIを使用する際に同じフラグを手動で設定することもできます。このフラグが設定されたすべてのリクエストは、Fetch API内で適用される同じ進行中のクオータ制限を共有します。
3. もしcontentTypeがnullでない場合：
  - corsModeを"cors"に設定します。
  - もしcontentTypeの値がContent-TypeヘッダーのCORS-safelisted request-header値である場合、corsModeを"no-cors"に設定します。
  - contentTypeの値を持つContent-TypeヘッダーをheaderListに追加します。
戻り値をtrueに設定し、sendBeacon()呼び出しを返し、以下の手順を並行して実行します：
1. reqを次のように初期化された新しいリクエストに設定します：
  
  メソッド
  
  POST
  
  クライアント
  
  thisの関連設定オブジェクト
  
  url
  
  parsedUrl
  
  ヘッダーリスト
  
  headerList
  
  オリジン
  
  origin
  
  keepalive
  
  true
  
  ボディ
  
  transmittedData
  
  モード
  
  corsMode
  
  資格情報モード
  
  include
  
  発信者タイプ
  
  "beacon"
2. Fetch req。

sendBeacon()インターフェースは、データを非同期かつ非ブロッキングで配信するメカニズムを提供します。このAPIを使用して以下を実現できます：

クライアント側イベントをサーバーに報告します。配信はユーザーエージェントによって優先順位付けされ、スケジュールされるため、他のインタラクティブな作業を妨げず、システムリソースを効率よく利用します。
ページがバックグラウンド状態に移行する際やアンロードされる際にセッションデータを報告しますが、ユーザーエージェントをブロックすることはありません。
小さなペイロードの配信が必要で、レスポンスコールバックを期待しないその他のユースケース。

配信されるデータには、例えば、ウェブページでのユーザーのアクティビティに関するデータなど、潜在的に機密性の高い情報が含まれる可能性があります。これはユーザーのプライバシーに影響を与える可能性がありますが、既存の方法（スクリプトによるフォーム送信、画像ビーコン、XHR/Fetchリクエストなど）も同様の機能を提供します。ただし、これらの方法にはさまざまな高コストなパフォーマンスのトレードオフがあります。リクエストはユーザーエージェントによって中断される可能性があり、開発者が同期リクエストを呼び出したり、空ループでスピンしたりすることでユーザーエージェントが他のイベントを処理するのを妨げない限り、リクエストは中断される可能性があります。また、ユーザーエージェントはこれらのリクエストを優先順位付けや統合してシステムリソースの使用を最適化することができません。

sendBeacon()によって開始されたリクエストは以下の特性に従います：

リクエストにペイロードが含まれていない場合、またはリクエストのContent-TypeがCORS-safelisted request-headerである場合、そのリクエストモードはno-corsとなります。これはそれぞれ画像ビーコンやフォーム投稿に似ています。
それ以外の場合、CORSプリフライトが実行され、サーバーは適切なCORSヘッダーセットを返すことでそのようなリクエストを許可する必要があります： Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers。

そのため、セキュリティの観点から見ると、Beacon APIは開発者が現在使用している方法と同じセキュリティポリシーに従います。同様に、プライバシーの観点から見ても、結果として得られるリクエストは、APIが呼び出された時点またはページの可視性が変化した時点で即座に開始されるため、開発者がアクセス可能な既存のライフサイクルイベントに限定して情報（例：ユーザーのIPアドレス）が公開されます。ただし、ユーザーエージェントはそのようなリクエストをユーザーに透明性を持って提示するための代替方法を検討する場合があります。

代替手段と比較して、sendBeacon() APIには2つの制約が適用されます：コールバックメソッドが存在しないこと、およびペイロードサイズがユーザーエージェントによって制限される可能性があることです。それ以外の場合、sendBeacon() APIには追加の制限はありません。ユーザーエージェントはsendBeacon()呼び出しの処理をスキップしたり、スロットリングしたりすべきではありません。これらは重要なアプリケーションの状態、イベント、および分析データを含む可能性があるためです。同様に、ユーザーエージェントは「プライベートブラウジング」または同等のモードでsendBeacon()を無効にすべきではありません。これは、アプリケーションを破壊することを避け、ユーザーがそのようなモードにいることを漏らさないようにするためです。

ビーコン

概要

この文書の位置付け

1. イントロダクション

2. 適合性

3. ビーコン

3.1 `sendBeacon()` メソッド

パラメーター

`url`

`data`

戻り値

3.2 処理モデル

4. プライバシーとセキュリティ

A. 謝辞

B. 参考文献

B.1 規範的参考文献

B.2 参考情報文献

ビーコン

概要

この文書の位置付け

1. イントロダクション

2. 適合性

3. ビーコン

3.1 sendBeacon() メソッド

パラメーター

url

data

戻り値

3.2 処理モデル

4. プライバシーとセキュリティ

A. 謝辞

B. 参考文献

B.1 規範的参考文献

B.2 参考情報文献

3.1 `sendBeacon()` メソッド

`url`

`data`