信标

摘要

本规范定义了一个接口，Web开发者可以使用它来安排异步且非阻塞的数据传递，从而最大程度减少与其他关键操作的资源竞争，同时确保这些请求仍能被处理并送达目标。

本节为非规范性内容。

Web 应用通常需要向一个或多个服务器发起请求，用于上报事件、状态更新和分析。这些请求通常不需要客户端处理响应（例如返回 204 或 200 HTTP 响应码且响应体为空），并且不应与其他高优先级操作（如抓取关键资源、响应输入、运行动画等）争夺网络和计算资源。然而，这种单向请求（信标）也负责传递关键的应用和度量数据，导致开发者不得不用高成本的方法来确保其成功送达：

开发者选择立即发送每个信标，而不是合并并延迟发送，因为这样能提高送达率。延迟发送可能导致信标请求没有足够时间成功完成，进而丢失重要应用数据。
开发者选择通过同步 XMLHttpRequest 发起阻塞请求，插入空操作忙等待循环，或采用其他阻塞用户代理执行关键操作（如点击、卸载等事件处理器）的技术，破坏用户体验。阻塞行为用于提高送达率，因为这样可防止用户代理和操作系统在页面被卸载、挂起或系统杀死时取消请求。

上述送达与处理需求的不匹配，让大多数开发者面临艰难选择，并普遍采用损害用户体验的阻塞技术。本规范定义了一个接口，Web 开发者可以用其安排异步且非阻塞的数据传递，最大限度减少与其他关键操作的资源竞争，同时确保这些请求仍能被处理并送达目标：

信标请求优先级较低，避免与关键操作和高优先级网络请求竞争。
用户代理可以高效地合并信标请求，以优化移动设备的能耗。
信标请求保证在页面卸载前发起，并允许其完成，无需阻塞请求或阻塞用户交互事件处理的其他技术。

以下示例展示了如何使用 sendBeacon() 方法来发送事件、点击和分析数据：

示例 1

<html>
<script>
  // 发送非阻塞信标以记录客户端事件
  function reportEvent(event) {
    var data = JSON.stringify({
      event: event,
      time: performance.now()
    });
    navigator.sendBeacon('/collector', data);
  }

  // 页面进入后台状态时，发送会话分析信标（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')">点击我</button>
</body>
</html>

注意

上述示例使用了 visibilitychange 事件（定义见 [PAGE-VISIBILITY-2]）来触发会话数据的发送。该事件是页面进入后台状态（如用户切换应用、返回主屏幕等）或页面被卸载时在移动设备上唯一保证触发的事件。开发者应避免依赖 unload 事件，因为当页面处于后台状态（即 visibilityState 等于 hidden 且进程被移动操作系统终止时， unload 事件不会触发。

通过 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 标志启动一次抓取，该标志会限制此类请求可排队数据的量，以确保信标请求能快速及时完成。
当文档的 visibilityState 状态转换为 hidden 时，用户代理必须立即调度所有信标请求的发送，并允许这些请求运行至完成，不阻塞其他关键和高优先级工作。
用户代理应该调度数据发送，以最大程度减少与其他关键和高优先级工作的资源（CPU和网络）竞争。
用户代理可以延迟数据发送，以优化网络和能耗效率——例如网络活跃时立即发送，或等待网络接口激活时发送。但用户代理不应无限期延迟传输，需确保待发送数据即使无其他网络活动也会定期刷新。

注意

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 的 scheme 不是 "http" 或 "https"，则抛出 "TypeError" 异常并终止这些步骤。
令 headerList 为一个空列表。
令 corsMode 为 "no-cors"。
如果 data 不为 null：
1. 将 transmittedData 和 contentType 设为提取 data 字节流的结果，且 keepalive flag 设为已启用。
2. 如果 keepalive 启用请求可排队发送的数据量被 transmittedData 的大小超过（见 HTTP-network-or-cache fetch），则返回值设为 false，并终止这些步骤。
  
  注意
  
  通过 Beacon API 发起的请求会自动设置 keepalive 标志，开发者也可在使用 Fetch API 时手动设置。所有设置了此标志的请求会共享 Fetch API 内部强制执行的在途配额限制。
3. 如果 contentType 不为 null：
  - 将 corsMode 设为 "cors"。
  - 如果 contentType 的值是 CORS 安全列表请求头的 Content-Type 值，则将 corsMode 设为 "no-cors"。
  - 向 headerList 添加一个值为 contentType 的 Content-Type 头。
将返回值设为 true，返回 sendBeacon() 调用，并继续并行执行以下步骤：
1. 令 req 为新建的请求，初始化如下：
  
  方法
  
  POST
  
  client
  
  this 的相关设置对象
  
  url
  
  parsedUrl
  
  请求头列表
  
  headerList
  
  origin
  
  origin
  
  keepalive
  
  true
  
  请求体
  
  transmittedData
  
  mode
  
  corsMode
  
  凭据模式
  
  include
  
  发起者类型
  
  "beacon"
2. 抓取 req。

sendBeacon() 接口提供了异步且非阻塞的数据传递机制。此API可以用于：

向服务器上报客户端事件。用户代理会对其进行优先级调度，确保不会阻塞其他交互工作，并高效利用系统资源。
当页面进入后台或被卸载时，上报会话数据，且不会阻塞用户代理。
其他需传递小型负载且无需响应回调的场景。

传递的数据可能包含敏感信息，例如用户在网页上的活动数据，发送到服务器。虽然这可能带来用户隐私风险，现有方法（如脚本表单提交、图片信标和XHR/fetch请求）也具备类似能力，但存在各种性能折衷：这些请求可能被用户代理中止，除非开发者阻止用户代理处理其他事件（例如发起同步请求或使用空循环等待），且用户代理无法对这些请求进行优先级调度和合并，以优化系统资源使用。

由 sendBeacon() 发起的请求具有以下属性：

如果请求不包含负载，或请求的 Content-Type 是 CORS安全列表请求头，则请求模式为 no-cors ——分别类似于图片信标或表单提交。
否则，会发起CORS预检，服务器需通过返回相应的CORS头允许此类请求： Access-Control-Allow-Credentials, Access-Control-Allow-Origin, Access-Control-Allow-Headers.

因此，从安全角度看，Beacon API 遵循开发者当前所用方法的安全策略。同样，从隐私角度看，最终请求会在API调用时或页面可见性变化时立即发起，这限制了暴露的信息（如用户IP地址）仅限于开发者可访问的现有生命周期事件。不过，用户代理可能考虑采用其他方法将此类请求展示给用户，以提高透明度。

相比其他方案，sendBeacon() API有两点限制：不提供回调方法，负载大小可由用户代理限制。除此之外，sendBeacon() API不受额外限制。用户代理不应跳过或限制对sendBeacon()的处理，因为它可能包含关键应用状态、事件和分析数据。同样，用户代理在“隐私浏览”或类似模式下也不应禁用sendBeacon()，既可避免破坏应用，又可防止暴露用户处于此模式。

信标

摘要

本文档状态

1. 简介

2. 一致性

3. 信标

3.1 `sendBeacon()` 方法

参数

`url`

`data`

返回值

3.2 处理模型

4. 隐私与安全

A. 致谢

B. 参考文献

B.1 规范性引用

B.2 参考性引用

信标

摘要