SocialHub.AI
开发者中心 · 网络追踪

追踪您网站上的用户行为。

在任何营销或电商网站上部署一个第一方信标,其页面浏览量即可与电子邮件、会员门户和您的应用程序一起纳入同一会员行为时间线。无需密钥,无需依赖项——只需几行原生 JavaScript 代码即可向公共端点发送 POST 请求。Flash 在服务器端解析设备、地理位置和机器人检测信息。

01 — 工作原理

单行托管内容,或独立代码片段

添加托管跟踪器时,只需添加一个脚本标签;如果您不想依赖外部代码,也可以粘贴包含完整代码片段的脚本。无论哪种方式,它都会生成标识符,尊重隐私信号,并将页面浏览量POST追踪到特定端点:

POST https://flash.socialhub.ai/api/v1/tracking/pageview

您发送客户端位

URL、标题、引荐来源网址、id、屏幕、语言、时区、UTM — 仅此而已。

Flash 丰富服务端

从User-Agent解析出设备、操作系统和浏览器; IP 所在国家/地区;机器人被检测并标记。客户永远不必因为这些而受到信任。

始终返回 204

无论是机器人请求、GPC 请求、格式错误请求还是已接受请求,端点都会静默响应。跟踪功能绝不会在您的页面上抛出任何错误。

在您自己的域名上,用户行为是匿名的。您的网站上没有Flash会话cookie,因此页面浏览量与您生成的anonymous_id关联,而不是与已知的会员关联。会员归因发生在Flash您拥有的平台上(忠诚度门户和应用内会员中心),会话在此解析会员。使用一致的anonymous_id,以便访客的网站行为至少在其所有会话中保持一致。

02 — 安装

两种方式。设置YOUR_TEAM_ID即可上线。

推荐

选项 A · 托管 — 单行

在 </body> 之前删除一个脚本标记。它自动跟踪单页面应用程序路由更改并公开 window.flashTrack() — 无需连接其他任何内容。

index.html
<!-- SocialHub web tracking — one line, before </body> -->
<script src="https://flash.socialhub.ai/sdk/flash-tracker.js"
        data-team-id="YOUR_TEAM_ID" defer></script>
↓ 下载 flash-tracker.js查看源代码 ↗无依赖性 · 如果您愿意,可以从您自己的来源自行托管

选项 B · 内联 — 无外部脚本

想要零外部请求(严格的 CSP,或您自己的捆绑包内的代码)?请粘贴此独立的代码片段。它公开 window.shTrack() — 在单页应用程序中每次路由更改后调用它:

index.html
<!-- SocialHub web tracking — paste before </body> on every page -->
<script>
(function () {
  var TEAM_ID = "YOUR_TEAM_ID";                                  // Settings → API
  var ENDPOINT = "https://flash.socialhub.ai/api/v1/tracking/pageview";

  // Honor Global Privacy Control / Do Not Track — no signal sent.
  if (navigator.globalPrivacyControl === true || navigator.doNotTrack === "1") return;

  function uid() {
    return (window.crypto && crypto.randomUUID)
      ? crypto.randomUUID()
      : (Date.now() + "-" + Math.random().toString(16).slice(2));
  }
  function persist(store, key) {
    try { var v = store.getItem(key); if (!v) { v = uid(); store.setItem(key, v); } return v; }
    catch (e) { return uid(); }
  }
  function utm() {
    var p = new URLSearchParams(location.search), o = {};
    ["source", "medium", "campaign", "term", "content"].forEach(function (n) {
      var val = p.get("utm_" + n); if (val) o[n] = val;
    });
    return Object.keys(o).length ? o : undefined;
  }
  function track() {
    var body = JSON.stringify({
      v: 1,
      page_url: location.href,
      page_title: document.title,
      referrer: document.referrer || undefined,
      anonymous_id: persist(localStorage, "sh_anon"),       // stable per browser
      session_id: persist(sessionStorage, "sh_session"),    // resets per tab session
      team_id: TEAM_ID,
      utm: utm(),
      screen: screen.width + "x" + screen.height,
      language: navigator.language,
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
      timestamp: Date.now()
    });
    try {
      if (navigator.sendBeacon) navigator.sendBeacon(ENDPOINT, body);
      else fetch(ENDPOINT, { method: "POST", body: body, keepalive: true }).catch(function () {});
    } catch (e) { /* never break the page */ }
  }

  window.shTrack = track;   // for SPAs: call window.shTrack() after each route change
  track();                  // initial page view
})();
</script>
spa-router.js
// Single-page apps: after each client-side route change
router.afterEach(function () { window.shTrack && window.shTrack(); });
03 — 有效载荷合约

信标主体

发送application/json(或通过sendBeacon发送纯文本string)。任何超过 4 KB 或验证失败的文件都会被静默丢弃。

场地类型笔记
vnumber模式版本。始终为 1。
page_urlstring页面的完整 URL (≤ 2048)。必需的。
page_titlestring?文档标题(≤ 500 字)。
referrerstring?document.referrer (≤ 2048)。
anonymous_idstring您生成的稳定的每个浏览器 ID (≤ 36)。必需的。
session_idstring您生成的每个会话的 ID(≤ 36)。必填。
team_idstring您的 SocialHub 团队 ID (≤ 36) — 标识品牌。必需的。
utmobject?从查询 string 解析出 { 来源、媒介、活动、术语、内容 }。
screenstring?“1920x1080”。
languagestring?导航器语言。
timezonestring?IANA 时区,例如:America/Los_Angeles。
timestampnumber客户时代女士。必需的。
04 — 保护

旨在抵御欺诈流量

您的 team_id 位于页面源代码中——就像任何分析 ID 一样,它是公开的。因此,该端点会在服务器端静默地进行自我保护(它始终响应 204,因此攻击者无法获得任何可用于探测的反馈):

基准速率限制 · 始终开启

所有团队默认都受到保护,无需任何设置:端点限制了单个来源可以发送的信标数量,因此抓取的 team_id 不会造成数据泛滥或污染您的分析数据。它具有故障保持功能——即使出现短暂中断,也不会影响您的真实流量。

来源允许列表 · 可选

在“设置”→“跟踪保护”中,您可以将允许的信标限制在您自己的域内,并在强制执行前通过监控预览检查 false 是否为阳性。这将阻止其他网站在浏览器中使用您的 SDK。

诚实地对待限制

速率限制和允许列表提高了门槛并限制了损失,但任何无密钥客户端都无法完全阻止蓄意伪造请求的脚本。对于高敏感度的数据接收,请改用经过身份验证的 API 进行服务器间通信。

下游数据已清理

反滥用机制在任何数据存储之前运行,因此被过滤的流量永远不会到达您的会员时间线、细分或仪表板——“跟踪保护”页面会显示有多少流量被拦截。

05 — 隐私

尊重访客体验

GPC 和“请勿追踪”

此代码片段会检查 navigator.globalPrivacyControl 和 navigator.doNotTrack,如果其中任何一个被设置,则不发送任何内容。请保留此保护措施。

无原始 PII

仅发送标识符和页面上下文 - 绝不发送信标中的姓名、电子邮件或表单内容。会员身份在 Flash 表面上解析,而不是在您的站点上解析。

首先显示您的同意横幅

如果您的网站使用同意管理器,请控制同意后面的代码片段 - 仅在访问者接受分析后才调用跟踪器。

机器人过滤

服务器端机器人检测会标记非人类流量,因此不会污染您的会员时间线或统计数据。

记录购物旅程的后续阶段

网络是四大平台之一。了解电子邮件、会员门户和您的应用程序如何共同构建同一条会员时间线。