@faststats/web

FastStats 网络分析核心

[大 这个储存库处于早期开发阶段,并不打算用于生产.

基础 SDK 处理分析、 身份、 会话、 导航、 输出链接 点击,同意. 错误跟踪、 Web Vitals、 会话重放、 特征标记是独立的 扩展,所以应用程序只下载它们使用的产品.

import { init, track } from "@faststats/web";
import { errorTracking } from "@faststats/web/error";
import { sessionReplay } from "@faststats/web/replay";
import { webVitals } from "@faststats/web/web-vitals";

init({
    siteKey: "site_123",
    extensions: [
        errorTracking(),
        webVitals(),
        sessionReplay({ recordConsole: true }),
    ],
});

track("checkout_completed", { total: 42 });

init() 启动一个共享客户端并具有同位素,从而安全地从 应用程序拖带代码。 在初始化之前发出的呼吁被忽略了 而不是带有僵硬上下文的缓冲。 使用 shutdown() 初始化前使用新程序 选项.

对于多个站点,测试或框架集成,创建一个独立的站点 具有明确生命周期控制的客户端:

import { createClient } from "@faststats/web";

const analytics = createClient({ siteKey: "site_123" });
analytics.start();
analytics.track("checkout_completed", { total: 42 });
analytics.destroy();

当地客户同意:使用 "anonymous" 为无饼干收藏, "granted" 用于普通收藏,或 "denied" 让客户保持休眠.

身份和特征

identify() 链接访问者到您的用户ID,并设置配置字段和 特质. traits 覆盖现有值; traitsOnce 只填写特征 人还没有.

import { identify, setTraits, unsetTraits } from "@faststats/web";

await identify("user_123", "[email protected]", {
    traits: { plan: "free" },
    traitsOnce: { signupSource: "reddit" },
});

await setTraits({ plan: "pro" });
await setTraits({ firstFeature: "export" }, { mode: "setOnce" });
await unsetTraits(["legacyPlan"]);

成功过后 identify(),该用户ID存储在匿名地址旁边 访客身份证明,并作为 externalId 以每件事物、每一件事物、每一件事物、每一件事物、每一件事物、每一件事物, 所以收藏家知道谁是访客 使用不透明的ID而不是电子邮件 地址 电话. getExternalId() 返回,或 "" 在此之前 identify()输入 无饼干模式,同时拒绝同意. logout() 和拒绝同意 永远忘了它。 Cookieless客户从不存储或发送.

一个 identify() 与本次浏览器会话中上次发送的相同 相同的匿名访客, 没有队列特征变化, 解析 true 无 请求,所以调用它 每一个页面负荷是便宜的。 过 force: true 永远 发送.

setTraits() 财务报告和审定财务报表 unsetTraits() 更新身份识别的访客,不包含 一个完整的身份证明。 它们适用于最新的用户 identify() 打电话,甚至 当它的请求在逃时 在此之前 identify(),更改保留在内存中 对于当前页面,并按顺序在下次成功之后发送 identify()类似 identify()他们决定 false 再不送进去 无饼干模式.

访问时间

properties.time_on_page 打开 $page_ping 财务报告和审定财务报表 $page_leave 是累积的 以毫秒表示的页面可见,其文档有焦点。 当标签是时会暂停 隐藏,窗口失去焦点,或者页面进入后向缓存,以及 在导航、登出或会话旋转时重新发送。 单调的钟表 系统时钟的变化不会影响这一持续时间。 60后也暂停 秒没有指针、键盘或滚动输入,除非 <video> 或者说 <audio> 元素在页面上播放,并恢复下一个输入。 时间 用于睡眠或被冻结的标签不计算.

页面视图等待页面可见 。 已替换或关闭的页面 显示时不显示页面视图或页外事件.

SDK发送一个累积 $page_ping 当活动暂停和定期 活动时:15和45秒后,每60秒一次。 增加不的接力 时间被压制。 访问结束 一个 $page_leave在导航上,一个终端 pagehide,登录,同意 更改,或会话旋转。 浏览器在无通知的情况下丢弃的一页 发送一个,所以它的最后一个接力维持其持续时间。 页面视图,它的收音机 休假份额 properties.visit_id;消费者应使用最大 time_on_page 每一次访问 跨越两次事件, 永远不要将它们相加.

在0.13之前,这些小叮当被发送到 page_leave 每15秒钟。 那个收藏家 和仪表板读取两种形状;在释放出这个SDK之前部署.

内建事件名称

SDK发送自己的事件作为 $pageview, (中文(简体) ), $page_ping, (中文(简体) ), $page_leave, (中文(简体) ), $outbound_link,以及 $error名称 $ 预留用于 内建事件,所以 track() 无视他们,并警告每个名字一次 操纵台 其他名称,包括: pageview 或者说 error,是一个自定义事件.

每个有效载荷 protocol: 2。年长的 SDK 发送内建事件没有 前缀; 收藏家重命名这些事件, 因此旧版本继续工作.

默认上下文

每件事都带 timezone (IANA名称), language,以及 screen (单位:千美元)1920x1080, CSS 像素)在页面上下文旁,与其属性相分离. 自定义事件和外出链接也载有 visit_id 页面视图 发生期间.

每次访问都保留其原始身份、会话和页面元数据。 届会 或者改变身份开始新的访问, 即使在同一条路线上。 两者都是持久性的 无饼干会议在30分钟后或24小时后失效.

session_duration 从会话开始到最后的时长 计算活动。 它包括相同两个活动期间之间的时间间隔 语句,因此它与页面上的活跃时间是分开的。 闲来客停了 延长会期,然后与任何其他会议一样在30分钟后结束.

交付是最佳努力:突然过程死亡或网络故障可能失去时间 自从上次送货以来 收藏家必须接受连续的事件 用于同一访客和URL; 部署删除其五秒钟的解禁 在释放SDK之前.

地物标志

featureFlags() 为访问者加载工程的旗帜、 客户端音轨和 与内存同步解决它们 :

import { init } from "@faststats/web";
import { featureFlags } from "@faststats/web/flags";

const flags = featureFlags();
init({ siteKey: "site_123", extensions: [flags] });

await flags.ready();
if (flags.isEnabled("new-checkout")) showNewCheckout();
const maxUploads = flags.get("max-uploads", 10);

一面旗子算作首次曝光的应用读取服务值 get(), (中文(简体) ), isEnabled() 或者说 details(),不是当它装入。 读者发送到 小批量和页面隐藏, 所以仪表板的曝光号显示 人们实际上看到了旗帜。 在装入或丢失时读取默认值 旗帜,不是暴露.

对匿名访客的标记进行评估,会议ID将每个标记联系起来 评估到分析. identify() 重新评价了他们的用户,所以 推出时跟踪用户跨设备,以及 logout() 回到一个新的 匿名访客 当用户在启动时被知道时,通过 userId 跳过 匿名负载。 没有饼干的访客没有永久的身份证 所以推出时间是 仅限届会。 同意时未加载旗帜 "denied",并撤销 同意减少尚未发出的接触.

get() 返回在加载旗帜时在呼叫站点通过的默认值,以及 当旗帜不存在时,存档,有不同的类型,或者服务 无法在 timeoutMs。 。 。 . details(key) 添加变体和理由 (单位:千美元)rule_match, (中文(简体) ), target_match, (中文(简体) ), fallthrough, (中文(简体) ), disabled, (中文(简体) ), prerequisite_failed) (中文(简体) ).

flags.subscribe(() => render(flags.status)); // "idle" | "loading" | "ready" | "error"
await flags.setContext({ attributes: { plan: "pro" } });
await flags.reload();

已打入标记

从项目的旗帜中生成类型 快报CLI数字 :

faststats flags typegen my-project

这个写着 faststats-flags.d.ts (进) src/ 当有一个人的时候 每一个活跃的旗帜 和它所能服务的价值。 键然后自动补全, 打字或 存档的旗帜无法编译, 数值按其变体键入 :

flags.get("theme", "system"); // "light" | "dark" | "system"
flags.isEnabled("theme"); // error: not a boolean flag

默认会加入结果类型, 因为它符合加载服务 。 运行 更改后再次命令,或添加 --check 在 CI 中,当 文件已过时。 没有文件,任何密钥都会被接受,结果就是 默认键入.

网络记录在会话重播

网络记录默认被禁用. 启用它 sessionReplay({ recordNetwork: true })此记录资源 URL 和时间 使用rrweb网络插件的数据。 标题和正文不默认记录. FastStats 收藏端点(包括自定义) baseUrl总是被排除在外 防止录制回放上传.

使用 networkOptions 以配置 rrweb 插件,包括过滤或编辑:

sessionReplay({
    recordNetwork: true,
    networkOptions: {
        initiatorTypes: ["fetch", "xmlhttprequest"],
        transformRequestFn: (request) => {
            const url = new URL(request.name);
            if (url.pathname.startsWith("/private/")) return;
            url.search = "";
            request.name = url.toString();
            return request;
        },
    },
});

recordHeaders, (中文(简体) ), recordBody,以及 recordInitialRequests 也可以设置在 networkOptions。在启用标题或机体之前编辑敏感数据. 仅网络选项无法录制 。 同样的回放选项是 通过 React 和 Nuxt 集成提供.

自定义扩展名

扩展只登记它所需要的生命周期钩. 虎克失败了 一个同步的设置在拆解时是安全的, 并收到清理 discard: true 取消同意时.

import type { AnalyticsExtension } from "@faststats/web";

export function diagnostics(): AnalyticsExtension {
    return {
        name: "diagnostics",
        setup(context) {
            const off = context.on("pageChange", ({ url }) => {
                console.debug("page changed", url);
            });

            return () => off();
        },
    };
}