Navigator: sendBeacon() 方法

navigator.sendBeacon() 方法 异步 发送包含少量数据的 HTTP POST 请求到 Web 服务器。

它旨在用于将分析数据发送到 Web 服务器，并避免了一些发送分析的传统技术问题，例如使用 XMLHttpRequest。

注意：对于需要使用除 POST 以外的方法发送请求、更改任何请求属性或需要访问服务器响应的用例，请改用 fetch() 方法，并将 keepalive 设置为 true。

语法

js
sendBeacon(url)
sendBeacon(url, data)

参数

url

将接收 data 的 URL。可以是相对的或绝对的。

data 可选

一个 ArrayBuffer、一个 TypedArray、一个 DataView、一个 Blob、一个字符串字面量或对象、一个 FormData 或一个 URLSearchParams 对象，其中包含要发送的数据。

返回值

如果 用户代理 成功将 data 排队以进行传输，则 sendBeacon() 方法返回 true。否则，它返回 false。

描述

此方法旨在用于分析和诊断代码以将数据发送到服务器。

发送分析的一个问题是，网站通常希望在用户完成页面操作时发送分析：例如，当用户导航到另一个页面时。在这种情况下，浏览器可能即将卸载页面，并且在这种情况下，浏览器可能选择不发送异步 XMLHttpRequest 请求。

在过去，网页尝试延迟页面卸载足够长的时间来发送数据。为此，他们使用了以下变通方法：

  • 使用阻塞同步 XMLHttpRequest 调用提交数据。
  • 创建 <img> 元素并设置其 src。大多数用户代理会延迟卸载以加载图像。
  • 创建持续几秒钟的无操作循环。

所有这些方法都会阻塞卸载文档，从而减慢导航到下一页的速度。下一页无法避免这种情况，因此新页面看起来很慢，即使是上一个页面的问题。

使用 sendBeacon() 方法，数据将在用户代理有机会时异步传输，而不会延迟卸载或下一个导航。这意味着

  • 数据会可靠地发送
  • 它会异步发送
  • 它不会影响下一页的加载

数据作为 HTTP POST 请求发送。

在会话结束时发送分析

网站通常希望在用户完成页面操作时将分析或诊断信息发送到服务器。最可靠的方法是在 visibilitychange 事件上发送数据

js
document.addEventListener("visibilitychange", function logData() {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
});

避免卸载和 beforeunload

在过去，许多网站使用 unload 或 beforeunload 事件在会话结束时发送分析。但是，这非常不可靠。在许多情况下，尤其是在移动设备上，浏览器不会触发 unload、beforeunload 或 pagehide 事件。例如，在以下情况下，这些事件不会触发

  1. 用户加载页面并与之交互。
  2. 完成操作后，他们切换到不同的应用程序，而不是关闭标签页。
  3. 稍后，他们使用手机的应用程序管理器关闭浏览器应用程序。

此外，unload 事件与现代浏览器中实现的回退/前进缓存 (bfcache) 不兼容。某些浏览器（如 Firefox）通过在包含卸载处理程序的页面中将其从 bfcache 中排除来处理这种不兼容性，从而降低了性能。其他浏览器（如 Safari 和 Android 上的 Chrome）通过在用户在同一标签页中导航到另一个页面时不触发 unload 事件来处理这种情况。

Firefox 还会在包含 beforeunload 处理程序的页面中将其从 bfcache 中排除。

使用 pagehide 作为后备

为了支持不实现 visibilitychange 的浏览器，请使用 pagehide 事件。与 beforeunload 和 unload 一样，此事件不会可靠地触发，尤其是在移动设备上。但是，它与 bfcache 兼容。

示例

以下示例指定了 visibilitychange 事件的处理程序。处理程序调用 sendBeacon() 来发送分析数据。

js
document.addEventListener("visibilitychange", function logData() {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
});

规范

规范
Beacon
# sendbeacon-method

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅