@ enter- pro/analystics- sdk

用于 Enter 生成网站的独立分析 SDK 。 提供自动仪器和手动跟踪出框,没有运行时间依赖性.

目录

• 快速启动
• 环境变量
• 自动仪器
• 手工跟踪
  • 强制性 API - trackEvent
  • 声明性API——事件定义
    • 触发类型
    • 财产约束
• 公共 API 参考
• 基础设施
• 已知差距
• 出版
• 正在进入另一回波
• 页:1

快速启动

import { bootstrapEnterAnalytics } from '@enter-pro/analytics-sdk';

bootstrapEnterAnalytics();

设定所需的环境变量并调用 bootstrapEnterAnalytics() 一次在应用条目。 其他的都是自动的.

环境变量

SDK读自 import.meta.env (声音)或 globalThis.__ENTER_ANALYTICS_ENV__ (非病毒环境).

端点路径映射 : sDK 职位到 <base>/code/api/v1/track后边 输入 API 网关, 此网关将重写到公众界面 /v1/track 路径文件 在分析 API 规格。 如果您是自动主机分析服务, 请配置 您要删除的反向代理 /code 前缀或设置 VITE_ENTER_ANALYTICS_ENDPOINT 到一个已经针对右主机的基址.

自动仪器

下面的一切都自动收集 bootstrapEnterAnalytics() 名为. 不需要额外的代码 .

页视图

• 发射 a page_view 初始负载时的事件 .
• 补丁 history.pushState 财务报告和审定财务报表 history.replaceState 以探测SPA导航.
• 监听 popstate 用于后向导航.
• 50ms的复制窗口可以防止快速通航的双发.

会话周期

• 第一个会话开始 page_view 火灾和发射a session_start 包含一个事件 session_reason 财产(first_visit | expired | continued) (中文(简体) ).
• 会议在30分钟后结束(通过 bootstrapEnterAnalytics({ inactivityTimeoutMs })) (中文(简体) ).
• A 类 session_end 当页面卸下时会释放出事件(beforeunload)或者当不活动计时器起火时.
• visibilitychange → hidden 已经 没有 结束会话——它只会触发同步冲出并暂停不活动计时器. 如果页面隐藏时间长于 inactivityTimeoutMs时,会话结束于下一个 visibilitychange → visible 与 ended_by: 'inactivity'。这避免了用户在移动上短暂切换分页时对会话进行充值.
• 会话状态持续在 sessionStorage 因此,它可以在同一个标签中刷新页面.

SDK 整合验证

靴子装好后,SDK发射一发子弹 enter_verify 交通事件,所以后端 GET /analytics/verify 端点可以确认SDK被正确接通. 过 disableVerifyPing: true 改为 bootstrapEnterAnalytics 跳过它.

JavaScript 错误捕获

• 监听 window.error 财务报告和审定财务报表 window.unhandledrejection。 。 。 .
• 发射一个 error 交通活动 error_message, (中文(简体) ), source, (中文(简体) ), lineno,以及 colno 属性.
• 过滤出第三方营销噪声(Facebook Pixel,Google Tag管理器,Twitter Analytics,DoubleClick)来减少无关出错的音量.

性能计量

每页装入一次 load 事件火灾.

用于 web-vitals,将它暴露为全球前 bootstrapEnterAnalytics() 称为:

import * as webVitals from 'web-vitals';
window.webVitals = webVitals;

bootstrapEnterAnalytics();

无 web-vitalsSDK回归原生性能API. LCP和CLS仍然是可观测的;FID在倒回路径中不可用.

访客身份

• 生成一个稳定 visitor_id 第一次访问时使用 crypto.randomUUID()。 。 。 .
• 将身份识别在两者中 localStorage 和一张饼干,用于交叉和相接的连续性.
• 记录 visitor_first_seen_at 新的访客检测.

每个事件的自动上下文

每个事件——无论是自动的还是人工的——在发作时都会被以下字段所丰富: 1

设备上下文( E)device_type, (中文(简体) ), browser, (中文(简体) ), os, (中文(简体) ), language)被检测出并在事件内部筑巢 context 对象。 此匹配后端 /v1/track schema,它只接受一个固定的顶级字段列表并放下任何额外的根级密钥. screen_resolution 也在里面筑巢着 context,并且故意只附在 page_view 财务报告和审定财务报表 session_start 事件(匹配分析设计谱)使有效载荷保持小. 用户提供 TrackEventOptions.context 被合并到自动收集设备字段的顶端,所以如果需要,呼叫者可以覆盖任意字段(例如通过) context: { browser: 'CustomBrowser' }) (中文(简体) ). Hash-routter 应用程序必须选择使用 bootstrapEnterAnalytics({ hashRouting: true }) 若为 page_path 自动 page_view 检测应包括 location.hash 例如 /#templates。 。 。 .

手工跟踪

强制性 API - trackEvent

打电话 trackEvent 用于发布自定义事件的应用程序代码中的任意位置.

import { trackEvent } from '@enter-pro/analytics-sdk';

trackEvent('button_clicked', {
  eventType: 'custom',       // 'custom' (default) | 'conversion'
  properties: {
    button_id: 'signup',
    variant: 'primary',
  },
  context: {
    page_section: 'hero',
  },
});

trackEvent 如果 bootstrapEnterAnalytics() 没有被调用或SDK已禁用.

参数:

声明性API——事件定义

事件定义允许您将跟踪规则描述为数据结构并附加到DOM元素上,而不写入每个组件的事件处理器代码. SDK在捕捉相中监听文档,在匹配元素时会自动起火事件.

登记册定义

import { registerEventDefinition, registerEventDefinitions } from '@enter-pro/analytics-sdk';

// Register a single definition
registerEventDefinition({
  event_name: 'signup_click',
  event_type: 'conversion',
  trigger: { kind: 'click', selector: '#signup-btn' },
  property_bindings: {
    plan: { type: 'attribute', attribute: 'data-plan' },
    label: { type: 'textContent' },
  },
  definition_version: '1',
});

// Register multiple definitions at once
registerEventDefinitions([...]);

// Replace all definitions (e.g. after fetching from a remote config)
replaceEventDefinitions([...]);

从远程配置中装入定义

要给"用户通过 Enter Agent → SDK 自动收集它们来定义事件"环线,将 SDK 指向返回当前工程事件定义的远程端点. 获取的列表将替换当前注册的列表 .

// Option 1: declaratively at bootstrap time
bootstrapEnterAnalytics({
  eventDefinitionsUrl: 'https://api.enter.pro/v1/projects/proj_abc/event-definitions',
  // Optional: provide a fetcher with auth headers if the endpoint is private.
  eventDefinitionsFetcher: (url, init) =>
    fetch(url, { ...init, headers: { Authorization: 'Bearer <token>' } }),
});

// Option 2: imperatively at any time after bootstrap
import { loadEventDefinitionsFromUrl } from '@enter-pro/analytics-sdk';
await loadEventDefinitionsFromUrl(
  'https://api.enter.pro/v1/projects/proj_abc/event-definitions'
);

接受响应形状 :

// Raw array
[ { "event_name": "...", ... } ]

// Or wrapped in an envelope
{ "data": { "definitions": [ { "event_name": "...", ... } ] } }
{ "definitions": [ { "event_name": "...", ... } ] }

触发类型

财产约束

属性绑定定义在事件起火时如何从 DOM 中提取值 。 解析值成为事件 properties。 。 。 .

对于带有可选内容的绑定 selector,SDK将元素相对于触发元素进行解析. 若为 selector 中省略,则使用触发元素本身.

实例:

// Read a data attribute from the clicked element
{ type: 'attribute', attribute: 'data-product-id' }

// Read a data attribute from the nearest ancestor matching a selector
{ type: 'closestAttribute', selector: '[data-experiment]', attribute: 'data-experiment' }

// Collect specific form fields on submit
{ type: 'formFields', fields: ['email', 'plan'] }

// Collect all form fields on submit
{ type: 'formFields', includeAll: true }

手动触发

对于 trigger.kind: 'manual' 定义,或在方案上触发任何定义:

import { emitDefinedEvent } from '@enter-pro/analytics-sdk';

// Without a DOM target
emitDefinedEvent('signup_click');

// With a DOM element as the binding resolution context
emitDefinedEvent('signup_click', document.querySelector('#signup-btn'));

公共 API 参考

BootstrapOptions

interface BootstrapOptions {
  /** Inactivity timeout before a session expires. Default: 30 minutes. */
  inactivityTimeoutMs?: number;
  /** Skip the one-shot enter_verify ping fired right after bootstrap. */
  disableVerifyPing?: boolean;
  /** Include `location.hash` in `page_path` and automatic `page_view` route detection. */
  hashRouting?: boolean;
  /**
   * If provided, the SDK will GET this URL after bootstrap and call
   * replaceEventDefinitions() with the response. Accepts either a raw array
   * or a `{ data: { definitions: [...] } }` envelope.
   */
  eventDefinitionsUrl?: string;
  /** Optional fetch implementation override (useful for SSR / proxy / auth). */
  eventDefinitionsFetcher?: typeof fetch;
}

对于散列程序,请打电话 bootstrapEnterAnalytics({ hashRouting: true }) 在应用程序条目。 这个工作空间目前不包括被跟踪的生成站点消费者,因此外部模板/bootstrap集成需要明确启用旗帜.

AnalyticsHealth

interface AnalyticsHealth {
  initialized: boolean;
  enabled: boolean;
  visitorId?: string;
  sessionId?: string;
  outboxSize: number;
  endpoint?: string;
  lastFlushAt?: number;
  lastError?: string;
}

基础设施

收发箱和交付

• 事件排入内存 + localStorage- 交货前有备份.
• 发件箱幸存的页面刷新:在前一个会话中排队的事件会在下个负载上重试.
• Flush运行间隔为5秒,分20批发送事件.
• 页面关闭( O)pagehide, (中文(简体) ), visibilitychangeSDK又回到一个认证的 fetch(..., { keepalive: true })。 。 。 .
• Page-exit slushs将记录保存在发件箱中,直到服务器承认它们为止,所以一个失败的卸载请求可以在下一页负载上重试.

重试和后退

• 失败请求会以指数回放和随机焦虑的方式重审 .
• 默认碱性延迟: 2 秒. 最大重试次数: 7.
• 超过72小时的事件自动放弃.
• 长期失败(INVALID_SCHEMA, (中文(简体) ), UNAUTHORIZED, (中文(简体) ), FORBIDDEN, (中文(简体) ), BAD_REQUEST,或服务器侧拒绝有永久原因)不重审.

数据保密

• 排序前, SDK 将匹配的属性密钥( 大小写不敏感子字符串) : password, (中文(简体) ), token, (中文(简体) ), cookie, (中文(简体) ), authorization, (中文(简体) ), auth, (中文(简体) ), email, (中文(简体) ), phone。 。 。 .
• 字符串属性值被缩短为256个字符.

已知差距

在代码库中确定了以下能力,但尚未完成:

出版

# Dry run to verify package contents
npm pack --dry-run
npm publish --dry-run

# Publish to npm
npm publish

该软件包发布到 https://registry.npmjs.org/ 与 access: public 下划线 @enter-pro 范围.

正在进入另一回波

添加数据 @enter-pro 范围至 .npmrc数字 :

@enter-pro:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=<NPM_TOKEN>
always-auth=true

安装 :

pnpm add @enter-pro/analytics-sdk

要在发布前进行测试,请从本地的焦油球上安装:

npm pack   # run in packages/analytics-sdk
pnpm add /absolute/path/to/enter-pro-analytics-sdk-0.0.6.tgz

页:1

• 此软件包是完全独立的, 不得导入运行时代码 packages/analytics。 。 。 .
• 发电机侧项目设置应复制 skills/enter-analytics-auto.md 输入 .enter/skills/ 这样 Enter 代码就可以自动执行新工程.
• SDK只采用无害环境管理("type": "module"消费者必须使用捆绑机(Vite, esbuilt, Rollup等).