跳到主要内容前端埋点实现方式与原理详解 | 极客日志JavaScriptSaaS大前端
前端埋点实现方式与原理详解
前端埋点通过向服务器发送 HTTP 请求记录用户行为。常见方法包括 Image Beacon（利用图片请求兼容性）、Navigator.sendBeacon（现代浏览器专用）、Fetch API keepalive 及官方 SDK。Image Beacon 将数据编码在 URL 参数中，不阻塞页面。sendBeacon 适合页面卸载场景。生产环境推荐使用官方 SDK 以处理兼容性与批量上报。对比了各方案优缺点并提供了代码示例。
PentesterX10 浏览 前端添加埋点方式和原理
前端埋点，就是把用户在产品里的关键行为（点击、曝光、停留、错误等）记录下来，回传到服务器或第三方平台，为产品决策、运营分析、问题排查提供数据依据。
核心实现思路：埋点本质上就是向埋点平台的数据接收 URL 发送一个 HTTP 请求，请求中携带了格式化的数据（通常是 URL 参数或 JSON）。
方法一：使用 Image Beacon（最经典、最可靠的方法）
这是最传统且兼容性最好的方式，利用图片请求没有跨域限制的特性。
function formatParams(params) {
return Object.keys(params).map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(params[key])}`).join("&");
}
document.getElementById("ImageBeacon").addEventListener("click", () => {
const saUrl = "https://...";
const project = "fosun_test1";
const event = "ButtonClick";
const distinctId = "user_123";
const properties = {
$url: window.location.href,
:
};
finalUrl = ;
beacon = (, );
beacon. = finalUrl;
beacon. = () { .(); };
beacon. = () { .(); };
});
微信扫一扫，关注极客日志
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
button_name
"提交按钮"
const
`${saUrl}?project=${project}&event=${event}&distinct_id=${distinctId}&${formatParams(properties)}`
const
new
Image
1
1
src
onerror
function
console
error
"Sensors beacon request failed."
onload
function
console
log
"Sensors beacon request successful."
方法二：使用 Navigator.sendBeacon（现代浏览器推荐）
这是 HTML5 专门为日志上报设计的新 API，非常适合埋点场景。
document.getElementById("sendBeacon").addEventListener("click", () => {
const data = {
project: "fosun_test1",
event: "ButtonClick",
distinct_id: "user_123",
properties: {
$url: window.location.href,
button_name: "提交按钮"
}
};
const blob = new Blob([JSON.stringify(data)], { type: "application/x-www-form-urlencoded" });
const success = navigator.sendBeacon("https://...", blob);
if (success) {
console.log("Beacon enqueued successfully!");
} else {
console.error("Beacon failed to queue.");
}
});
- 专为日志设计：即使页面卸载也会保证发送。
- 低优先级：不会阻塞页面卸载过程或与关键操作竞争网络资源。
方法三：使用 Fetch API with keepalive（不推荐）
Fetch API 提供了 keepalive 选项，用于在页面卸载后继续发送请求。这在需要确保数据上报的场景下非常有用。
document.getElementById("keepalive").addEventListener("click", () => {
const data = new URLSearchParams();
data.append("project", "your_project_name");
data.append("event", "ButtonClick");
data.append("distinct_id", "user_123");
data.append("properties", JSON.stringify({
$url: window.location.href,
button_name: "提交按钮"
}));
fetch("https://...", {
method: "POST",
body: data,
keepalive: true,
headers: { "Content-Type": "application/x-www-form-urlencoded" }
}).catch((error) => {
console.error("Fetch beacon failed:", error);
});
});
方法四：直接使用官方 SDK（推荐）
实际上，您不需要手动实现这些。官方提供了非常完善的 SDK，只需简单初始化即可。
<script>
var sensors = window["sensorsDataAnalytic201505"];
sensors.init({
server_url: "https://your-sensors-data-server.com/sa",
heatmap: {
clickmap: "default",
scroll_notice_map: "default"
}
});
sensors.login("user_123");
sensors.track("ButtonClick", {
button_name: "提交按钮"
});
</script>
npm install sa-sdk-javascript
这是推荐的方式，因为官方 SDK 处理了所有的兼容性、批量上报、重试机制等复杂问题。
请求参数详解
无论用哪种方法，最终发送给服务器的 URL 通常包含以下核心参数：
| 参数 | 含义 | 示例 |
|---|
project | 项目名称 | production |
event | 事件名称 | $pageview (页面浏览) |
distinct_id | 匿名/用户 ID | 123456 |
properties | 事件属性 | { "$url": "https://example.com" } |
time | 事件时间戳（可选） | 1631234567890 |
总结与选择
| 方法 | 适用场景 | 优点 | 缺点 |
|---|
| Image Beacon | 需要极致兼容性（如旧版 IE） | 兼容性最好，无跨域问题 | 无法发送大量数据 |
| sendBeacon | 现代浏览器，页面卸载时上报 | 专为日志设计，不阻塞卸载 | 兼容性稍差（IE 不支持） |
| fetch keepalive | 现代浏览器，需要更多控制 | 功能强大，可控制请求细节 | 兼容性比 sendBeacon 差 |
| 官方 SDK | 所有生产环境 | 功能完整，稳定可靠，省心 | 需要引入 SDK |
最终建议：对于生产环境，强烈推荐直接使用官方 SDK。它封装了所有最佳实践，您只需要关心业务逻辑（触发什么事件），而不需要关心网络传输的实现细节。只有在一些非常特殊的场景下，才需要考虑自己实现埋点请求。
常见问题：Image Beacon 是怎么获取用户数据的？
像这种发送一个图片给后端，他们是怎么通过图片分析数据的？
并不是真的去'分析'图片本身的内容（比如图片里的像素、颜色等），而是巧妙地利用浏览器请求图片的行为来传递数据。
可以这样理解：图片的 URL（地址）不是指向一张真实的图片，而实际上是一个精心编排的、包含了你所有埋点数据的'代码字符串'。
核心原理：URL 即消息
埋点系统会动态生成一个 1x1 像素的透明 GIF 图片的 URL，但这个 URL 的路径和参数部分被用来编码数据。
举个例子： 一个真实的埋点图片请求 URL 可能长这样：
https://data-sensors.com/sa.gif?project=my_web&event=pageview&user_id=123&page_url=https%3A%2F%2Fexample.com&button_name=checkout&time=1631234567890
| URL 部分 | 作用 | 说明 |
|---|
https://data-sensors.com/sa.gif | 接收端点 | 服务器地址，路径叫 sa.gif 只是为了伪装成图片。 |
?project=my_web | 查询参数（数据载体） | 从问号 ? 开始的部分才是关键！这些参数就是埋点数据。 |
&event=pageview | 事件名称 | 告诉服务器用户进行了'页面浏览'这个行为。 |
&user_id=123 | 用户标识 | 告诉服务器是哪个用户做的。 |
&page_url=... | 事件属性 | 告诉用户是在哪个页面做的。 |
&time=... | 时间戳 | 告诉服务器事件发生的确切时间。 |
- 浏览器：认为这是一个普通的图片资源，向
https://data-sensors.com/sa.gif 发起一个 HTTP GET 请求。
- 服务器：
- 接收到这个请求，完全忽略请求的是
.gif 这个事实。
- 服务器端的程序会解析 URL 中的查询参数（即
? 后面的部分）。
- 将这些参数解析成结构化的 JSON 数据。
- 将这些数据存入数据库或大数据平台，用于后续的分析和计算。
- 最后，服务器返回一个极其微小的 1x1 像素的透明 GIF 图片作为响应内容。
- 浏览器：接收到这个微小的图片数据，并渲染它（当然，在页面上你什么都看不到）。
为什么选择用图片（Image Beacon）？
这种技术被称为 'Image Beacon'（图片信标），它被广泛采用是因为有诸多优点：
| 优点 | 解释 |
|---|
| 没有跨域问题 | 图片资源不受同源策略的限制，可以从任何域名下加载。这是最大的优势。 |
| 兼容性极好 | 所有浏览器，包括非常古老的版本，都支持图片加载。 |
| 简单可靠 | 实现起来非常简单，只需要创建一个 Image 对象并设置 src 属性即可。 |
| 不阻塞页面 | 图片加载是异步的，不会阻塞页面的渲染或卸载过程。 |
| 开销极小 | 请求的图片只有 1x1 像素，几乎是所有网络请求中数据量最小的，对性能影响微乎其微。 |
🆚 与现代方法的对比
虽然 Image Beacon 非常经典，但现在也有更现代的技术：
| 技术 | 工作原理 | 优点 | 缺点 |
|---|
| Image Beacon | 伪装成图片的 GET 请求，数据在 URL 中 | 兼容性最好，无跨域问题 | URL 长度有限制，不适合传输大量数据 |
| navigator.sendBeacon() | HTML5 新 API，专门用于发送少量数据 | 即使页面关闭也会保证发送，不阻塞 | 兼容性稍差（IE 完全不支持） |
| Fetch API | 使用 JavaScript 发起异步请求 | 功能强大，可控制性强 | 可能受跨域策略限制 |
总结
- 羊头（请求头）：
Content-Type: image/gif -> 让浏览器以为这是个图片。
- 狗肉（请求体和目的）：
?event=xxx&user_id=xxx -> 在 URL 参数中携带数据，服务器解析后存入数据库。
最终，您在海量数据中看到的用户行为分析报表、转化漏斗、留存分析等，全都是基于解析这些 URL 参数后存入数据库的数据计算出来的，与那张微小的透明图片本身没有任何关系。
案例代码
<!DOCTYPE html>
<html>
<head>
<title>Markdown Renderer</title>
<style>
button {
display: block;
margin: 20px;
font-size: 16px;
}
</style>
</head>
<body>
<div id="result"></div>
<button id="ImageBeacon">ImageBeacon 添加埋点</button>
<button id="sendBeacon">Navigator.sendBeacon 添加埋点</button>
<button id="keepalive">fetchKeepalive 添加埋点</button>
<script>
function formatParams(params) {
return Object.keys(params).map((key) => `${encodeURIComponent(key)}=${encodeURIComponent(params[key])}`).join("&");
}
document.getElementById("ImageBeacon").addEventListener("click", () => {
const saUrl = "https://...";
const project = "fosun_test1";
const event = "ButtonClick";
const distinctId = "user_123";
const properties = {
$url: window.location.href,
button_name: "提交按钮"
};
const finalUrl = `${saUrl}?project=${project}&event=${event}&distinct_id=${distinctId}&${formatParams(properties)}`;
const beacon = new Image(1, 1);
beacon.src = finalUrl;
beacon.onerror = function () { console.error("Sensors beacon request failed."); };
beacon.onload = function () { console.log("Sensors beacon request successful."); };
});
document.getElementById("sendBeacon").addEventListener("click", () => {
const data = {
project: "fosun_test1",
event: "ButtonClick",
distinct_id: "user_123",
properties: {
$url: window.location.href,
button_name: "提交按钮"
}
};
const blob = new Blob([JSON.stringify(data)], { type: "application/x-www-form-urlencoded" });
const success = navigator.sendBeacon("https://...", blob);
if (success) {
console.log("Beacon enqueued successfully!");
} else {
console.error("Beacon failed to queue.");
}
});
document.getElementById("keepalive").addEventListener("click", () => {
const data = new URLSearchParams();
data.append("project", "your_project_name");
data.append("event", "ButtonClick");
data.append("distinct_id", "user_123");
data.append("properties", JSON.stringify({
$url: window.location.href,
button_name: "提交按钮"
}));
fetch("https://...", {
method: "POST",
body: data,
keepalive: true,
headers: { "Content-Type": "application/x-www-form-urlencoded" }
}).catch((error) => {
console.error("Fetch beacon failed:", error);
});
});
</script>
</body>
</html>
