1. 序論
~INFORMATIVE~web~appは、［ ~event ／ 状態の更新 ／ 解析 ］を~serverへ報告するために，~HTTP要請の発行を必要とすることが多い。 そのような要請には、結果の~HTTP応答を~client上で処理することは，概して要求されない（例： 応答は、その~HTTP応答~codeは［ `204$st ／ `200$st ］で，本体は空）。 また、［ ~network資源／計算-資源 ］を，［ 不可欠な資源の~fetching, 入力に対する反応, ~animationの稼働 ］などの他の高~優先度の演算と競合するべきでない。 しかしながら、そのような一方向の要請（ ~beacon ）はまた，不可欠な［ ~app／計測 ］~dataを送達する責を負うので、開発者は，送達を確保するために，高価な~methodの利用を強いられている： ◎ Web applications often need to issue requests that report events, state updates, and analytics to one or more servers. Such requests typically do not require response processing on the client (e.g. result in 204, or 200 HTTP response codes with an empty response body), and should not compete for network and compute resources with other high priority operations such as fetching critical resources, reacting to input, running animations, and so on. However, such one-way requests (beacons), are also responsible for delivering critical application and measurement data, forcing developers to use costly methods to ensure their delivery:
- 開発者は、送達~率を改善するため，それらの送達を集約-／延期する代わりに，各~beaconを即時に送達することを選んでいる。 送達を延期すると、~beacon要請を成功裡に完了するための時間が足りなくなり，重要な~app~dataを喪失するかもしれないので。 ◎ Developers opt for immediate delivery of each beacon, instead of coalescing and deferring their delivery because this provides improved delivery rates. Deferring delivery may mean that the beacon request may not have sufficient time to complete successfully, which leads to loss of important application data.
- 開発者が阻止ing要請の発行を選んでいる結果、利用者~体験が害されている。 例えば、同期的 `XMLHttpRequest^I，あるいは ~UAによる時間厳守の演算（例： `click^et, `unload^et, その他の~handler ） の実行を阻止するような技法（何もしない~loopを回すなど）を利用して。 阻止ing挙動は、~pageが~systemにより［ ~unload ／ ~suspend ／ ~kill ］されても， ~UA（または OS ）が要請を取消せないようにして、送達~率を改善するために利用されている。 ◎ Developers opt for issuing blocking requests via synchronous XMLHttpRequest's, inserting no-op busy loops, or using other techniques that block the user agent from executing time-critical operations (e.g. click, unload, and other handlers) and hurt the user experience. The blocking behavior is used to provide improved delivery rate, as it prevents the user agent and the operating system from cancelling the request if the page is unloaded, suspended, or killed by the system.
上述のように，送達~要件と処理~要件には不一致があるため、ほとんどの開発者たちは，［ 普及している，利用者~体験を害するような阻止ing技法 ］を渋々採用している。 この仕様は、~web開発者が［ そのような要請が処理され, 宛先へ送達される ］ことを確保しつつ［ 他の，時間厳守の演算との資源競合 ］も最小化するような，［ 非同期的かつ他を阻止しない，~dataの送達 ］を~scheduleするために利用できる~interfaceを定義する： ◎ The mismatch between above delivery and processing requirements leaves most developers with a tough choice and widespread adoption of blocking techniques that hurt the user experience. This specification defines an interface that web developers can use to schedule asynchronous and non-blocking delivery of data that minimizes resource contention with other time-critical operations, while ensuring that such requests are still processed and delivered to destination:
- ~beacon要請には、［ 時間厳守の演算 ／ 高~優先度の~network要請 ］と競合しないように優先度があてがわれる。 ◎ Beacon requests are prioritized to avoid competing with time-critical operations and higher priority network requests.
- 携帯~機器~上の電力~利用を最適化するために、~UAは，~beacon要請を効率的に集約することもできる。 ◎ Beacon requests may be efficiently coalesced by the user agent to optimize energy use on mobile devices.
- ~beacon要請は，~pageが~unloadされる前に起動されることが保証されるので、［ 阻止ing要請や，利用者~対話~eventの処理を阻止するような他の技法 ］を要求することなく，完遂できる。 ◎ Beacon requests are guaranteed to be initiated before page is unloaded and are allowed to run to completion without requiring blocking requests or other techniques that block processing of user interactive events.
`sendBeacon()$m ~methodを利用して，［ ~event ／ ~click ／ 解析 ］~dataを送達する例を示す： ◎ The following example shows use of the sendBeacon() method to deliver event, click, and analytics data:
<html> <script> /* ~client側の~eventを記録するために，（他を阻止しない）~beaconを発する ◎ emit non-blocking beacon to record client-side event */ function reportEvent(%event) { var %data = JSON.stringify({ event: %event, time: performance.now() }); navigator.sendBeacon('/collector', %data); } /* ~pageが~background状態に遷移する（ Page Visibility ~API）に伴い，~session解析を伴う（他を阻止しない）~beaconを発する ◎ emit non-blocking beacon with session analytics as the page transitions to background state (Page Visibility 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')">Click me</button> </body> </html>
上のどの~beaconも，他を阻止しない。
上の例は、~session~dataの送達を誘発するために， `visibilitychange$et ~event `PAGE-VISIBILITY-2$r を利用する。 この~eventは、~pageが~background状態に遷移するとき（例： 利用者が他の~appに切替えたとき, ~homescreenに戻ったとき, 等々），あるいは~unloadされているとき，携帯~機器~上で発火されることが保証される唯一の~eventである。 開発者は、 `unload^et ~eventに依拠するのは避けるべきである — それは、~pageが~background状態にあるとき（すなわち， `visibilityState$m は `hidden$l ）には発火されず，処理-は携帯 OS により終了されるので。 ◎ Above example uses visibilitychange event defined in [PAGE-VISIBILITY-2] to trigger delivery of session data. This event is the only event that is guaranteed to fire on mobile devices when the page transitions to background state (e.g. when user switches to a different application, goes to homescreen, etc), or is being unloaded. Developers should avoid relying on unload event because it will not fire whenever a page is in a background state (i.e. visibilityState equal to hidden) and the process is terminated by the mobile OS.
`sendBeacon()$m ~methodを介して起動される要請は、時間厳守の仕事を阻止したり, それらと競合しない — ~UAは，~network効率性を改善するように優先度をあてがえるので、阻止ing演算で~beacon~dataの送達を確保する必要はなくなる。 ◎ The requests initiated via the sendBeacon() method do not block or compete with time-critical work, may be prioritized by the user agent to improve network efficiency, and eliminate the need to use blocking operations to ensure delivery of beacon data.
`sendBeacon()$m は、次を意図するものではない： ◎ What sendBeacon() does not do and is not intended to solve:
- ~beacon要請は、~offline~storageや送達に対する特別な取扱いは供さない。 それは，他の要請と同様であり、~offline機能性を供するために必要とあれば， `SERVICE-WORKERS$r と組合わされてもよい。 ◎ The sendBeacon() method does not provide special handling for offline storage or delivery. A beacon request is like any other request and may be combined with [SERVICE-WORKERS] to provide offline functionality where necessary.
- ~beacon要請は、~background同期や, 転送~能力を供するために意図されたものではない。 ~beacon要請を素早くかつ適時に完了できることを確保するため、~UAは，受容する最大~payload~sizeを制約する。 ◎ The sendBeacon() method is not intended to provide background synchronization or transfer capabilities. The user agent restricts the maximum accepted payload size to ensure that beacon requests are able to complete quickly and in a timely manner.
- 要請~methodを~custom化したり，要請／応答における他の 処理~prop を変更する能は供さない。 そのような要請~用に既定のものでない設定群を要する~appは、 `FETCH$r ~APIを利用して， `~keepalive~flag$rqは ~ON にするべきである。 ◎ The sendBeacon() method does not provide ability to customize the request method, provide custom request headers, or change other processing properties of the request and response. Applications that require non-default settings for such requests should use the [FETCH] API with keep-alive flag set to true.
2. 適合性の要件
【 この節の他の内容は W3C 日本語訳 共通ページ に委譲 】
2.1. 依存関係
【 この節の内容は省略する。 他の仕様の用語への~~参照には、直接的に~linkをあてがうことにする。 】
3. ~beacon
3.1. `sendBeacon()^m ~method
partial interface `Navigator$I {
boolean `sendBeacon$(
`USVString$I %url,
optional `BodyInit$I? %data = null
);
};
`sendBeacon()@m ~methodは、次の規則に則って，［ `data@v 引数（ `BodyInit$I 型）に供された~data ］を［ `url@v 引数（ `USVString$I 型）に供された~URL ］へ向けて伝送する： ◎ The sendBeacon() method transmits data provided by the data parameter to the URL provided by the url parameter:
- ~UAは，~beacon要請が素早くかつ適時に完了することを確保するため、~fetchを起動する際には，要請の［ `~keepalive~flag$rq ~SET ~ON ］にして，要請が~queueできる `data$v 量を制約し~MUST。 この量は、`~HTTP~network-or-cache~fetch$にて定義される。 【具体的には、 64KiB】 ◎ The user agent must initiate a fetch with keepalive flag set, which restricts the amount of data that can be queued by such requests to ensure that beacon requests are able to complete quickly and in a timely manner.
- ~UAは、文書の `visibilityState$m `PAGE-VISIBILITY$r が `hidden^l に遷移するときには、すべての~beacon要請に対し，即時に伝送を~scheduleした上で、そのような要請すべてが他の［ 時間厳守の／高~優先度の ］仕事を阻止することなく，完遂できるようにし~MUST。 ◎ The user agent must schedule immediate transmission of all beacon requests when the document visibilityState ([PAGE-VISIBILITY]) transitions to hidden, and must allow all such requests to run to completion without blocking other time-critical and high-priority work.
- ~UAは、他の［ 時間厳守の／高~優先度の ］仕事との（ CPU ／ ~network の）資源競合を最小化するために，供された~dataの伝送を~scheduleする~SHOULDである。 ◎ The user agent should schedule transmission of provided data to minimize resource (CPU and network) contention with other time-critical and high priority work.
- ~UAは、［ ~network／電力 ］効率性を最適化するために，供された~dataの伝送を遅延して~MAY — 例えば、~network~interfaceが作動中ならば即時に送達し，そうでなければ作動中になるまで待機するなど。 しかしながら，~UAは、伝送を不定期に遅延する~SHOULDでない — 他の~network活動がないときでも，待機中の伝送が定期的に消化されることを確保する~SHOULDである。 ◎ The user agent may delay transmission of provided data to optimize network and energy efficiency - e.g. deliver immediately if the network is active, or wait until network interface is active. However, the user agent should not delay transmission indefinitely and ensure that pending transmissions are periodically flushed even if there is no other network activity.
注記： ~Beacon~APIは、要請~callbackは供さない。 ~serverには、そのような要請に対する応答の本体は，省略することが奨励される（例えば、 `204$st No Content で応答するなど）。 ◎ Beacon API does not provide a response callback. The server is encouraged to omit returning a response body for such requests (e.g. respond with 204 No Content).
`sendBeacon()$m ~methodは、［ 伝送ed~dataを~UAが成功裡に~queueできたならば ~T ／ ~ELSE_ ~F ］を返す。 ◎ Parameters ◎ url ◎ The url parameter indicates the URL where the data is to be transmitted. data ◎ The data parameter is the BodyInit data that is to be transmitted. ◎ The sendBeacon() method returns true if the user agent is able to successfully queue the data for transfer. Otherwise it returns false.
注記： ~UAは、この~APIを介して送信できる~data量に制限を課す： これは、そのような要請が成功裡に送達されつつ，利用者や~browserによる他の活動への~~影響は最小限に抑えることを確保し易くするためである。 ~queueされる~data量が`~UAによる制限$を超過することになる場合、この~methodは ~F を返す。 返り値 ~T は、~browserが転送~用に~dataを~queueしたことを意味する。 しかしながら、実際の~data転送は非同期的に行われる — この~methodは、~data転送が成功したかどうかについては，いかなる情報も供さない。 ◎ The user agent imposes limits on the amount of data that can be sent via this API: this helps ensure that such requests are delivered successfully and with minimal impact on other user and browser activity. If the amount of data to be queued exceeds the user agent limit (as defined in http-network-or-cache-fetch), this method returns false; a return value of true implies the browser has queued the data for transfer. However, since the actual data transfer happens asynchronously, this method does not provide any information whether the data transfer has succeeded or not.
3.2. 処理~model
【 この節に現れる各種~用語は `DOM$r `HTML$r `FETCH$r `URL$r `WebIDL$r にて定義される。 】
`sendBeacon$(%url, %data)
~methodの被呼出時には、次の手続きを走らせ~MUST：
◎
On calling the sendBeacon() method with url and optional data, the following steps must be run:
- %O ~LET `入口~設定群~obj$ ◎ ↓
- %基底~URL ~LET %O の `~API用~基底~URL$enV ◎ Set base to the entry settings object's API base URL.
- %生成元 ~LET %O の`生成元$ ◎ Set origin to the entry settings object's origin.
- %解析済~URL ~LET `~URL構文解析する$( %url , %基底~URL ) ◎ ↓
- ~IF［ %解析済~URL ~EQ `失敗^i ］~OR［ %解析済~URL の `~scheme$ ~NIN { `http^l, `https^l } ］ ⇒ ~THROW `TypeError^E ◎ Set parsedUrl to the result of the URL parser steps with url and base. If the algorithm returns an error, or if parsedUrl's scheme is not "http" or "https", throw a "TypeError" exception and terminate these steps.
- %~header~list ~LET 空の`~header~list$ ◎ Let headerList be an empty list.
- %~CORS~mode ~LET `no-cors^l ◎ Let corsMode be "no-cors".
- ( %伝送ed~data, %内容~型 ) ~LET ( ~NULL, ~NULL ) ◎ ↓
-
~IF［ %data ~NEQ ~NULL ］： ◎ If data is not null:
- ( %伝送ed~data, %内容~型 ) ~SET `本体と内容~型を抽出する$( %data ) ◎ Extract object's byte stream (transmittedData) and content type (contentType).
-
~IF［ %伝送ed~data の量は［［ `~keepalive~flag$rq が ~ON にされた要請 ］が送信-用に~queueできる~data量に対する，`~UAによる制限$ ］を超過している ］ ⇒ ~RET ~F ◎ If the amount of data that can be queued to be sent by keepalive enabled requests is exceeded by the size of transmittedData (as defined in http-network-or-cache-fetch), set the return value to false and terminate these steps.
注記： ~Beacon~APIを介して起動された要請に対しては、 `~keepalive~flag$rq は自動的に ~ON にされる。 開発者は、~Fetch~APIの利用-時にも同じ~flagを手動で設定できる。 この~flagが ~ON にされたすべての要請は、~Fetch~APIの中で施行される，同じ~in-flight~quota制約を共有する。 【すなわち、これらの処理待ち要請たちの総量にも一定の上限がある。】 ◎ Requests initiated via the Beacon API automatically set the keepalive flag, and developers can similarly set the same flag manually when using the Fetch API. All requests with this flag set share the same in-flight quota restrictions that is enforced within the Fetch API.
-
~IF［ %内容~型 ~NEQ ~NULL ］： ◎ If contentType is not null:
- ~IF［ %内容~型 は `Content-Type^h ~headerに対する`~CORS安全な要請~header$値でない ］ ⇒ %~CORS~mode ~SET `cors^l ◎ Set corsMode to "cors". ◎ If contentType value is a CORS-safelisted request-header value for the Content-Type header, set corsMode to "no-cors".
- を %~header~list に`~headerを付加する$( `Content-Type^h / %内容~型 ) ◎ Append a Content-Type header with value contentType to headerList.
- ~RET ~T — ただし、この手続きは並列的に継続する。 ◎ Set the return value to true, return the sendBeacon() call, and continue to run the following steps in parallel:
- %要請 ~LET 次の様に初期化された，新たな`要請$ ⇒＃ `~method$rq ~SET `POST^M, `~url$rq ~SET %解析済~URL, `~header~list$rq ~SET %~header~list, `生成元$rq ~SET %生成元, `~keepalive~flag$rq ~SET ~ON, `本体$rq ~SET %伝送ed~data, `~mode$rq ~SET %~CORS~mode, `資格証明情報~mode$rq ~SET `include^l ◎ Let req be a new request, initialized as follows: ◎ method • POST url • parsedUrl header list • headerList origin • origin keep-alive flag • true body • transmittedData mode • corsMode credentials mode • include
- %要請 を用いて`~fetch$する ◎ Fetch req.
4. ~privacyと保安
`sendBeacon()^m は、~data送達~用の非同期的かつ他を阻止しない仕組みを供する。 この~APIは、次に利用できる： ◎ The sendBeacon() interface provides an asynchronous and non-blocking mechanism for delivery of data. This API can be used to:
- ~client側の~eventを~serverに報告する。 送達は、他の対話的~仕事を阻止しない, かつ~system資源が効率的に利用されるように、~UAにより優先度があてがわれ，~scheduleされる。 ◎ Report client-side events to the server. The delivery is prioritized and scheduled by the user agent such that it does not block other interactive work and makes efficient use of system resources.
- ~pageが［ ~background状態に遷移する／~unloadされる ］ときに、~UAを阻止することなく，~session~dataを報告する。 ◎ Report session data when the page transitions to background state or is being unloaded, without blocking the user agent.
- 小さな~payloadの送達を要求するが，応答~callbackは期待しないような 他の利用~事例。 ◎ Other use cases that require delivery of small payloads and do not expect a response callback.
~serverへ送達される~dataは、敏感になり得る情報を包含し得る — 例えば，利用者の~web~page上での活動についての~dataなど。 これには，利用者にとって~privacy上の含意があり得るが、既存の代替 — 種々の高価な処理能と引き換えにしている，［ ~scriptによる~form-submit ／ 画像~beacon ／ XHR や~fetchによる要請 ］など — も似た能力を供する： 要請は、開発者が，~UAによる他の~event処理を阻止しない限り（例：同期的~要請を呼出したり，空~loopを回すなど），~UAにより中止され得る。 ~UAはまた、そのような要請に優先度をあてがったり, それらを集約して，~system資源の利用を最適化することができない。 ◎ The delivered data might contain potentially sensitive information, for example, data about a user's activity on a web page, to a server. While this can have privacy implications for the user, existing methods, such as scripted form-submit, image beacons, and XHR/fetch requests provide similar capabilities, but come with various and costly performance tradeoffs: the requests can be aborted by the user agent unless the developer blocks the user agent from processing other events (e.g. by invoking a synchronous request, or spinning in an empty loop), and the user agent is unable to prioritize and coalesce such requests to optimize use of system resources.
`sendBeacon()^m により起動される要請は、次に挙げる~propertyの対象0になる： ◎ A request initiated by sendBeacon() is subject to following properties:
- ［ 要請が~payloadを包含していない ／ 要請の `Content-Type^h は`~CORS安全な要請~header$である ］場合、要請の`~mode$rqは `no-cors^l になる — ［ ~scriptによる~form-post／ XHR や~fetchによる要請 ］と同じ様に。 ◎ If the request does not contain a payload, or the request Content-Type is a CORS-safelisted request-header, then the request mode is `no-cors`—similar to an image beacon or form-post respectively.
- 他の場合、`~CORS予行~要請$が~~発行される。 そのような要請に対しては、~serverは先ず，適切な一式の~CORS~header — `Access-Control-Allow-Credentials$h, `Access-Control-Allow-Origin$h, `Access-Control-Allow-Headers$h — を返すことで、それを許容する必要がある。 ◎ Otherwise, a CORS preflight is made and the server needs to first allow such requests by returning the appropriate set of CORS headers: Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers.
そのようなわけで、保安~上の観点からは、~Beacon~APIを対象0とする保安~用の施策は，開発者たちが利用中にある現在の手法に対するそれと同じになる。 同様に~privacyの観点からも、結果の要請は［ ~APIが~callされる／ ~pageの可視性が変化する ］と同時に即時に起動され、公開される情報（例： 利用者の IP ~address）を開発者から~access可能な既存の lifecycle ~eventに制約する。 しかしながら，~UAは、利用者に透明性を供するためとして，そのような要請を表面化させるための代替~手法を考慮するかもしれない。 ◎ As such, from the security perspective, the Beacon API is subject to same security policies as the current methods in use by developers. Similarly, from the privacy perspective, the resulting requests are initiated immediately when the API is called, or upon a page visibility change, which restricts the exposed information (e.g. user's IP address) to existing lifecycle events accessible to the developers. However, user agents might consider alternative methods to surface such requests to provide transparency to users.
`sendBeacon()^m ~APIには、上述の代替と比較して，二つの制約 — ~callback~methodは無いこと, および ~UAは~payload~sizeを制約できること — が適用される。 それ以上の制約は課されない。 ~UAは、 `sendBeacon()^m ~callの処理を間引くべきでない — それらは不可欠な［ ~app状態 ／ ~event ／ 解析~data ］を包含し得るので。 同様に，~UAは、 “私的閲覧中（ private browsing ）” に等価な~mode下にあるときは、［ ~appが壊される ／ 利用者がそのような~mode下にあることが漏洩される ］のを避けるため， `sendBeacon()^m を不能化するべき（ ought ）でない。 ◎ Compared to the alternatives, the sendBeacon() API does apply two restrictions: there is no callback method, and the payload size can be restricted by the user agent. Otherwise, the sendBeacon() API is not subject to any additional restrictions. The user agent ought not skip or throttle processing of sendBeacon() calls, as they can contain critical application state, events, and analytics data. Similarly, the user agent ought not disable sendBeacon() when in "private browsing" or equivalent mode, both to avoid breaking the application and to avoid leaking that the user is in such mode.