@ taltertable/taltertable-js (中文(简体) )

JavaScript SDK用于捕获并发送分析事件到Altertable.

安装

npm install @altertable/altertable-js
# or
pnpm add @altertable/altertable-js
# or
yarn add @altertable/altertable-js
# or
bun add @altertable/altertable-js

快速启动

import { altertable } from '@altertable/altertable-js';

// Initialize with your API key
altertable.init('YOUR_API_KEY');

// Track an event
altertable.track('Step Completed', {
  step: 1,
});

// Identify a user
altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: '[email protected]',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
});

// Update user traits
altertable.updateTraits({
  onboarding_completed: true,
});

// Link a new ID to the current identity
altertable.alias('new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd');

特征

• 自动页面视图跟踪 - 自动抓取页面视图
• 会话管理 - 自动处理匿名和会话ID
• 离线交付 — 浏览器上线时, 恒定事件和重试
• 活动排队 - 等待同意的事件排队
• 遵守隐私 - 内部跟踪同意管理
• 多个存储选项 - 本地Storage、饼干或两者兼有
• 类型脚本支持 - 包含全部类型脚本定义
• 轻巧 - 无外部依赖的最小捆绑大小

API 参考

初始化

altertable.init(apiKey, config?)

以您的 API 密钥和可选配置初始化 .

参数:

示例

altertable.init('YOUR_API_KEY');

通话 init 替换配置和 丢弃 输出批量缓冲中的任何事件。 如果您需要先发送( 例如在切换 API 密钥之前) , await altertable.flush() 打电话前 init 再来一次.

事件跟踪

altertable.track(event, properties?)

跟踪带有可选属性的自定义事件.

参数:

示例

altertable.track('Purchase Completed', {
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
});

altertable.page(url)

跟踪页面视图事件.

何时 autoCapture 启用,当页面 URL 更改时,此方法会自动调用.

参数:

示例

altertable.page('https://example.com/products');

[注]

跟踪:默认情况下,Altertable自动抓取页面浏览. 仅使用 page() 当你被禁用自动捕捉.

为什么要使用自动抓取( 默认) ?

• 无需手工跟踪
• 处理浏览器导航事件( M)popstate, (中文(简体) ), hashchange(中文(简体) )
• 对所有页面更改进行一致跟踪

何时使用 page()数字 :

• 自定义不会触发浏览器事件的路由
• 不触发 URL 更改的虚拟页面视图( 模式, 步骤更改)
• 无法自动抓取的服务器端跟踪

现有分析适配器

重用现有的 PostHog 执行而不改变其跟踪呼叫 . 初始化 PostHog 之前的可变性 :

import posthog from 'posthog-js';
import { altertable } from '@altertable/altertable-js';

altertable.init('ALTERTABLE_KEY', {
  adapters: { posthog },
});

posthog.init('POSTHOG_KEY');

改变可移动 PostHog 事件并禁用自己的收藏 . track, (中文(简体) ), page, (中文(简体) ), identify, (中文(简体) ), alias,以及 updateTraits 电话被忽略 在配置适配器时,自动抓取不动.

转变事件

使用 transformEvent 以自定义在 SDK队列,坚持或发送. 变压器也自动运行 抓取的页面视图, 这样您就可以丰富它们而不会损坏 autoCapture 或者说 添加路由器特定跟踪码.

altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    if (event.event === '$pageview') {
      return {
        ...event,
        properties: {
          ...event.properties,
          title: document.title,
          content_group: 'documentation',
        },
      };
    }

    return event;
  },
});

呼叫收到完整 TrackPayload,包括: 事件名称、生成上下文、时间戳和默认属性。 它运行 同步创建的事件 track() 财务报告和审定财务报表 page();适配器,身份, 和别名有效载荷不改变.

返回时 null 丢弃事件 :

altertable.init('YOUR_API_KEY', {
  transformEvent(event) {
    if (event.properties.internal_traffic === true) {
      return null;
    }

    return event;
  },
});

如果变压器抛出, 变压表会丢弃事件而不是发送 原始载荷。 错误已被记录并传递到 onError 错误时 处理器已配置 。 您可以替换 transformEvent 运行时间 altertable.configure({ transformEvent })。 。 。 .

用户标识

altertable.identify(userId, traits?)

识别用户的ID和可选特征. 它标出身份为身份识别的用户.

参数:

示例

altertable.identify('u_01jza857w4f23s1hf2s61befmw', {
  email: '[email protected]',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
});

altertable.updateTraits(traits)

更新当前用户的用户特性.

参数:

示例

altertable.updateTraits({
  onboarding_completed: true,
});

altertable.alias(newUserId)

链接到当前身份的新ID.

参数:

示例

altertable.alias('new_user_id-019aca6a-1e42-71af-81a0-1e14bbe2ccbd');

会话管理

altertable.reset(options?)

重新设置当前身份背景, 因此未来事件与前一个用户无关 .

参数:

示例

// Reset everything except device ID
altertable.reset();

// Reset all IDs
altertable.reset({
  resetDeviceId: true,
});

配置

altertable.configure(updates)

初始化后更新配置。 A 类 baseUrl 更改适用于新的 请求; 已经在飞行中的批次保留其原目的地的回转. 如果启用自动抓取失败订阅, 请拨打 configure({ autoCapture: true }) 重新进行注册.

参数:

示例

altertable.configure({
  trackingConsent: 'granted',
});

隐私和同意

altertable.getTrackingConsent()

返回当前跟踪同意状态.

回返情况: TrackingConsentType

示例

const consent = altertable.getTrackingConsent();
if (consent === 'granted') {
  // Tracking is allowed
}

类型

AltertableConfig

变相 SDK 的配置选项 .

观众计量

使用受众模式来收集总体使用统计,而不会持续 客户端标识符 :

altertable.init('YOUR_API_KEY', { mode: 'audience' });
altertable.track('Install Copied', { package: 'react' });

页面视图和自定义事件会自动使用观众处理. 在这个模式下, 这个SDK:

• Omits 用户,匿名,会话,以及事件的设备ID.
• 在记忆中保持身份、同意和未发生事件,压倒一切的持久性 选项。 保存的数据不恢复,在重新装入时丢失了未发送的事件.
• 忽略 identify(), (中文(简体) ), alias(),以及 updateTraits() 打电话.
• 删除 URL 证书、 查询参数、 碎片、 裁判路径以及 视图数据. 无效、 相对和非 HTTP URL 变为 null。 。 。 .
• Omits 浏览器请求所有发送的证书和 HTTP 推荐人 .

事件名称,自定义属性,和URL路径可以包含个人数据. 使用 transformEvent 在传输前删除它。 SDK应用观众 改造后的限制。 适应器前进源身份和 属性,不支持受众模式.

trackingConsent 控制交付:等待或解除事件等待内存, 和否认的事件被抛弃。 提供每份同意书 init()。 。 。 .

要更改模式, 请调用 init()。 。 。 . configure() 无法更改 mode。 。 。 . 重新初始化丢弃缓冲事件; 调用 flush() 首先,如果你想的话 派他们来.

搜索测量

观众模式条列搜索查询参数,例如 q 从自动页面 追踪。 跟踪搜索,明确用来测量使用情况和结果计数:

altertable.track('Search Performed', {
  category: 'documentation',
  result_count: results.length,
});

搜索术语可以包含个人数据. 如果你需要收集,明确 添加一个 search_term 属性,然后审查哪些值可以安全发送.

离线交付

变相器可以坚持未发生事件的有效载荷,这样它们就可以活下来再装入并当浏览器回到网上时发送. 默认情况下,事件有效载荷使用的存储策略与 persistence,但饼干支持的战略将事件有效载荷存储在 localStorage 只有这个.

如果您不希望将事件有效载荷写入持久浏览器存储, 设置 eventPersistence: false。事件会作为当前页面会话的内存进行分批处理,但不会在重载中幸存.

altertable.init('YOUR_API_KEY', {
  eventPersistence: false,
});

AltertableConfigUpdates

接受的选项 configure()。包括 AltertableConfig 除外 mode,通过 init()。 。 。 .

EventProperties

自定义事件属性 .

type EventProperties = Record<string, unknown>;

示例

{
  product_id: 'p_01jza8fr5efvgbxxdd1bwkd0m5',
  amount: 29.99,
  currency: 'USD',
  category: 'electronics',
  user_type: 'premium'
}

TrackPayload

整个有效载荷传到 transformEvent 在两种跟踪模式中。 产品 模式发送已转换 TrackPayload; 观众模式应用其限制 发送 AudienceTrackPayload 没有身份.

type TrackPayload = {
  event: string;
  properties: EventProperties;
  timestamp: string;
  device_id: `device-${string}`;
  distinct_id: string;
  anonymous_id: `anonymous-${string}` | null;
  session_id: `session-${string}`;
};

AudienceTrackPayload

观众有效载荷发送到轨道API之后 transformEvent数字 :

type AudienceTrackPayload = {
  mode: 'audience';
  event: string;
  properties: EventProperties;
  timestamp: string;
};

TransformEvent

type TransformEvent = (event: TrackPayload) => TrackPayload | null;

EventProperties, (中文(简体) ), TrackPayload, (中文(简体) ), AudienceTrackPayload,以及 TransformEvent 从 @altertable/altertable-js 用于应用代码.

UserTraits

用户属性用于识别.

type UserTraits = Record<string, unknown>;

示例

{
  email: '[email protected]',
  name: 'John Doe',
  company: 'Acme Corp',
  role: 'Software Engineer',
  plan: 'premium',
  signup_date: '2024-01-15'
}

StorageType

persistence 财务报告和审定财务报表 eventPersistence 也接受自定义同步存储 适配器. 它必须执行 getItem(key): string | null, (中文(简体) ), setItem(key, value): boolean,以及 removeItem(key): void返回时 false 从 setItem 当写作失败时。 Async 后端必须在水合之前完成 初始化并提供同步的相模适配器; 不通过相模 直接存储 API.

丢弃自定义写和删除出错 onError。失败事件写出请假 存储错误不会重排已确认的事件。 读取 错误传播到 init() 或者说 configure();在迁移失败后读取,请修正 后端并重试相同的配置.

使用导出 getStorageKeys(apiKey) 以解析 API 密钥瞄准镜 session 财务报告和审定财务报表 events 水合前键. 对于自定义运行时间, 提供 a 平台 给建筑师. 内容 isOnline() 方法读取连接; 返回 false 保留缓冲 事件直到稍后冲出.

这个 Altertable 为需要单独的应用程序导出构造器 客户实例。 调用返回的清理函数 init() 处理时 一个实例.

可用存储策略.

TrackingMode

TrackingConsentType

现有追踪同意状态.

运行时平台

new Altertable() 用途 browserPlatform 默认。 供应a Platform 页:1 在另一个运行时间托管核心SDK时的构造器 。 月台已经修好了 客户寿终正寝,且可在 init(),所以队列事件保留 记录它们时的上下文.

import { Altertable, type Platform } from '@altertable/altertable-js';

const platform: Platform = {
  getContext: () => ({ properties: { runtime: 'worker' } }),
};

const client = new Altertable(platform);
client.track('Started');
const cleanup = client.init('YOUR_API_KEY', { persistence: 'memory' });
await client.flush();
cleanup();

仅 getContext() 需要时间。 订阅缺失使这些整合无法进行; sDK 不替代浏览器执行 平台。 储存仍然是通过 persistence 财务报告和审定财务报表 eventPersistence,接受 StorageAdapter。 。 。 .

正常交付尊重跟踪同意和连接。 用于平台 同步交付准备、相重叠的自动请求合在一起; 新阈值事件触发后续快照, 而失败的请求等待 为后起触发. 重叠生命周期或间隔请求共享当前 快照; 阈值以下的事件仍然分批进行到下一个触发. 快照在准备开始前选择活动;后来抵达者需要他们 自己准备的快照。 明确 flush() 继续排水,准备每一次新的 示意图. flush({ drain: false }) 共享这些自动传送任务 平台。 准备失败 onError 自动尝试和拒绝 明显的冲出.

清理停止了平台订阅,定时器,并进一步交付. 订阅 在清理运行前取消所有者名, 因此队列了回调和回调 被失败的清理保留会被忽略 。 已退役的批发器无法修改存储 当旧的要求完成。 清理、重置和拒绝同意取消HTTP重试; 清理和重新初始化也防止了有待准备的工作开始停滞 交货。 在继续使用清理客户端之前重新初始化 .

要扩展浏览器行为, 直接构成导出的执行 :

import { Altertable, browserPlatform } from '@altertable/altertable-js';

const client = new Altertable({
  ...browserPlatform,
  getContext() {
    return {
      ...browserPlatform.getContext(),
      properties: { application: 'dashboard' },
    };
  },
});

React 本地软件包提供本地环境, App State 生命周期处理, 可选连接,并通过此同步存储准备 合同。 分析提供者订阅独立于浏览器检测; 配置的供应商必须履行自己的适配器合同.

许可证

麻省理工学院