# @deriv-com/analytics 中文文档

规范地址：https://npmcn.com/package/%40deriv-com/analytics/

版本：1\.44\.0
npm 元数据更新时间：2026-10-13T06:30:23.900Z
中文译文更新时间：2026-11-12T00:40:11.822Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deriv-com/analytics
原文对照：https://npmcn.com/package/%40deriv-com/analytics/?lang=original
项目主页：https://github.com/deriv-com/deriv-analytics
源码仓库：https://github.com/deriv-com/deriv-analytics

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.9 MB，52 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.13\.0
- 运行依赖：3 个
- 首次发布：2024-01-15T06:16:01.211Z
- 最新版本发布：2026-10-13T06:30:23.639Z
- 近 30 天下载量：8770（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：121（近 12 个月 41 个）

## 中文简介

Deriv应用的综合分析包. 通过RuderStack,PostHog和GrowthBook集成,提供统一的事件跟踪,A/B测试,以及用户分析,内置缓存和离线支持.

## 安装

```sh
npm install @deriv-com/analytics
```

也可以使用：`pnpm add @deriv-com/analytics`、`yarn add @deriv-com/analytics`、`bun add @deriv-com/analytics`

## README

# @deriv-com/分析

一个现代的可树摇动分析库,用于跟随RuderStack和PostHog追踪用户事件. 以高级缓存、分批和离线支持为最佳性能设计.

## 特征

-   📊 **多服务支持**: 用于事件跟踪的 RanderStack 用于分析的 PostHog 记录( S)
-   🎄 **可树动**: 只有捆绑您使用的东西 - 每个提供者可以独立导入
-   📡 **离线第一**: 离线时自动事件缓存, 重新连接时重放
-   ⚡ **业绩优化**: Batching, 分解, 和 SendBeacon API 用于快速跟踪
-   🔄 **后向兼容**: 支持更古老的React,Node.js等遗产包版本
-   💾 **高级缓存**: 当地集散地和内藏地,以提供强有力的活动
-   🎥 **会话录音**: 内建 PostHog 会话录入自定义的设置

> **说明**:GrowthBook支持被贬值,将在未来的主要版本被去掉. 对于A/B测试和特征旗,我们建议使用PostHog的内置特征旗能力.

## 目录

-   [安装](https://npmcn.com/package/%40deriv-com/analytics/#readme-installation)
    -   [国家预防机制/也门](https://npmcn.com/package/%40deriv-com/analytics/#readme-npmyarn)
    -   [浏览器( CDN)](https://npmcn.com/package/%40deriv-com/analytics/#readme-browser-cdn)
-   [快速启动](https://npmcn.com/package/%40deriv-com/analytics/#readme-quick-start)
-   [框架整合](https://npmcn.com/package/%40deriv-com/analytics/#readme-framework-integration)
    -   [反应](https://npmcn.com/package/%40deriv-com/analytics/#readme-react-integration)
    -   [下一个.js](https://npmcn.com/package/%40deriv-com/analytics/#readme-nextjs-integration)
    -   [Vue.js (英语)](https://npmcn.com/package/%40deriv-com/analytics/#readme-vuejs-integration)
    -   [香草 Java 脚本](https://npmcn.com/package/%40deriv-com/analytics/#readme-vanilla-javascript)
-   [配置](https://npmcn.com/package/%40deriv-com/analytics/#readme-configuration)
    -   [舵手链](https://npmcn.com/package/%40deriv-com/analytics/#readme-rudderstack-configuration)
    -   [邮箱](https://npmcn.com/package/%40deriv-com/analytics/#readme-posthog-configuration)
        -   [强制设置](https://npmcn.com/package/%40deriv-com/analytics/#readme-enforced-settings)
        -   [无法逾越的默认](https://npmcn.com/package/%40deriv-com/analytics/#readme-overridable-defaults)
        -   [不手工抓取$page视图](https://npmcn.com/package/%40deriv-com/analytics/#readme--do-not-capture-pageview-manually)
        -   [域允许列表](https://npmcn.com/package/%40deriv-com/analytics/#readme-domain-allowlist)
-   [核心 API](https://npmcn.com/package/%40deriv-com/analytics/#readme-core-api)
    -   [初始化](https://npmcn.com/package/%40deriv-com/analytics/#readme-initialization)
    -   [事件跟踪](https://npmcn.com/package/%40deriv-com/analytics/#readme-event-tracking)
    -   [用户标识](https://npmcn.com/package/%40deriv-com/analytics/#readme-user-identification)
    -   [页视图](https://npmcn.com/package/%40deriv-com/analytics/#readme-page-views)
    -   [用户属性](https://npmcn.com/package/%40deriv-com/analytics/#readme-user-attributes)
-   [缓存离线支持( O)](https://npmcn.com/package/%40deriv-com/analytics/#readme-caching--offline-support)
-   [调试模式](https://npmcn.com/package/%40deriv-com/analytics/#readme-debug-mode)
-   [高级使用](https://npmcn.com/package/%40deriv-com/analytics/#readme-advanced-usage)
-   [后霍格特性旗](https://npmcn.com/package/%40deriv-com/analytics/#readme-posthog-feature-flags)
-   [PostHog 整合检查列表](https://npmcn.com/package/%40deriv-com/analytics/#readme-posthog-integration-checklist)
-   [API 参考](https://npmcn.com/package/%40deriv-com/analytics/#readme-api-reference)
-   [业绩](https://npmcn.com/package/%40deriv-com/analytics/#readme-performance)
-   [解决问题](https://npmcn.com/package/%40deriv-com/analytics/#readme-troubleshooting)
-   [移徙指南](https://npmcn.com/package/%40deriv-com/analytics/#readme-migration-guide)

## 安装

### 国家预防机制/也门

```bash
# Using npm
npm install @deriv-com/analytics

# Using yarn
yarn add @deriv-com/analytics

# Using pnpm
pnpm add @deriv-com/analytics
```

**核心依赖关系** (单位:千美元)`@rudderstack/analytics-js`, (中文(简体) ), `js-cookie`,以及 `posthog-js`自动安装.

### 浏览器( CDN)

在没有构建工具的浏览器中直接使用:

```html
<!-- Load from jsdelivr CDN -->
<script src="https://cdn.jsdelivr.net/npm/@deriv-com/analytics@latest/dist/browser/analytics.bundle.global.js"></script>

<script>
    const { Analytics } = window.DerivAnalytics

    Analytics.initialise({
        rudderstackKey: 'YOUR_RUDDERSTACK_KEY',
        posthogOptions: {
            apiKey: 'YOUR_POSTHOG_KEY',
            config: {
                autocapture: true,
            },
        },
    }).then(() => {
        Analytics.trackEvent('page_view', { page: 'home' })
    })
</script>
```

**套装大小**: ~380 KB 已修改 /~125 KB gziped (包括RanderStack + PostHog + 所有依赖性)

## 快速启动

### 基本使用量( 仅RudderStack)

```typescript
import { Analytics } from '@deriv-com/analytics'

// Initialize with RudderStack
await Analytics.initialise({
    rudderstackKey: 'YOUR_RUDDERSTACK_KEY',
})

// Track events
Analytics.trackEvent('ce_virtual_signup_form', {
    action: 'signup_done',
    signup_provider: 'email',
})

// Track page views
Analytics.pageView('/dashboard', 'Deriv App')

// Identify users
Analytics.identifyEvent('CR123456')
```

### 使用 RanderStack 和 PostHog 两种语言

```typescript
import { Analytics } from '@deriv-com/analytics'

await Analytics.initialise({
    // RudderStack for event tracking (required)
    rudderstackKey: 'YOUR_RUDDERSTACK_KEY',

    // PostHog for analytics and session recording (optional)
    posthogOptions: {
        apiKey: 'phc_YOUR_POSTHOG_KEY',
        config: {
            session_recording: {
                recordCrossOriginIframes: true,
                minimumDurationMilliseconds: 30000,
            },
            autocapture: true,
        },
    },
})

// Events are automatically sent to both providers
Analytics.trackEvent('ce_login_form', {
    action: 'login_cta',
    login_provider: 'google',
})

// User identification syncs with both providers
// When using PostHog, pass email via provider-specific traits (see User Identification section)
Analytics.identifyEvent('CR123456', {
    rudderstack: { language: 'en', country_of_residence: 'US' },
    posthog: { email: 'user@example.com', language: 'en', country_of_residence: 'US' },
})
```

## 框架整合

### 反应集成

建议的模式是单一的 `useAnalytics` 处理初始化并曝光所有跟踪方法的钩:

```typescript
// hooks/useAnalytics.ts
import { useEffect } from 'react'
import { Analytics } from '@deriv-com/analytics'

let isInitialized = false

export function useAnalytics() {
    useEffect(() => {
        if (isInitialized) return
        isInitialized = true

        const rudderstackKey = process.env.REACT_APP_RUDDERSTACK_KEY // ← replace with your env var
        const posthogKey = process.env.REACT_APP_POSTHOG_KEY // ← replace with your env var

        if (!rudderstackKey && !posthogKey) return

        Analytics.initialise({
            ...(rudderstackKey && { rudderstackKey }),
            ...(posthogKey && {
                posthogOptions: {
                    apiKey: posthogKey,
                    api_host: process.env.REACT_APP_POSTHOG_HOST,
                },
            }),
            debug: process.env.NODE_ENV === 'development',
        })
    }, [])

    return {
        trackEvent: Analytics.trackEvent,
        identifyEvent: Analytics.identifyEvent,
        pageView: Analytics.pageView,
        loadEvent: Analytics.loadEvent,
        setAttributes: Analytics.setAttributes,
        reset: Analytics.reset,
    }
}
```

在你的应用程序的顶端给钩子打电话:

```tsx
// App.tsx
import { useAnalytics } from './hooks/useAnalytics'

function App() {
    const { trackEvent } = useAnalytics()

    return <button onClick={() => trackEvent('ce_signup_button', { action: 'click' })}>Sign Up</button>
}
```

### Next.js 一体化

#### App 路由器 (Next.js 13+)

用同样的 `useAnalytics` 钩子( 有 `NEXT_PUBLIC_` env var 前缀)在专用客户端提供者内:

```typescript
// hooks/useAnalytics.ts
'use client'

import { useEffect } from 'react'
import { Analytics } from '@deriv-com/analytics'

let isInitialized = false

export function useAnalytics() {
    useEffect(() => {
        if (isInitialized) return
        isInitialized = true

        const rudderstackKey = process.env.NEXT_PUBLIC_RUDDERSTACK_KEY // ← replace with your env var
        const posthogKey = process.env.NEXT_PUBLIC_POSTHOG_KEY // ← replace with your env var

        if (!rudderstackKey && !posthogKey) return

        Analytics.initialise({
            ...(rudderstackKey && { rudderstackKey }),
            ...(posthogKey && {
                posthogOptions: {
                    apiKey: posthogKey,
                    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
                },
            }),
            debug: process.env.NODE_ENV === 'development',
        })
    }, [])

    return {
        trackEvent: Analytics.trackEvent,
        identifyEvent: Analytics.identifyEvent,
        pageView: Analytics.pageView,
        loadEvent: Analytics.loadEvent,
        setAttributes: Analytics.setAttributes,
        reset: Analytics.reset,
    }
}
```

```tsx
// app/analytics-provider.tsx
'use client'

import { useAnalytics } from '@/hooks/useAnalytics'

export function AnalyticsProvider({ children }: { children: React.ReactNode }) {
    useAnalytics()
    return <>{children}</>
}

// app/layout.tsx
import { AnalyticsProvider } from './analytics-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html>
            <body>
                <AnalyticsProvider>{children}</AnalyticsProvider>
            </body>
        </html>
    )
}
```

#### Pages 路由器(以下简称:Next.js 12)

```typescript
// pages/_app.tsx
import { useAnalytics } from '../hooks/useAnalytics'
import type { AppProps } from 'next/app'

export default function App({ Component, pageProps }: AppProps) {
    useAnalytics()
    return <Component {...pageProps} />
}
```

### Vue.js 一体化

```typescript
// main.ts or main.js
import { createApp } from 'vue'
import { Analytics } from '@deriv-com/analytics'
import App from './App.vue'

// Initialize analytics
Analytics.initialise({
    rudderstackKey: import.meta.env.VITE_RUDDERSTACK_KEY,
    posthogOptions: {
        apiKey: import.meta.env.VITE_POSTHOG_KEY,
    },
})

// Make Analytics available globally
const app = createApp(App)
app.config.globalProperties.$analytics = Analytics
app.mount('#app')

// Usage in components
export default {
    methods: {
        handleClick() {
            this.$analytics.trackEvent('button_clicked', { button_name: 'submit' })
        },
    },
}
```

### 香草 Java 脚本

```html
<!doctype html>
<html>
    <head>
        <script src="https://cdn.jsdelivr.net/npm/@deriv-com/analytics@latest/dist/browser/analytics.bundle.global.js"></script>
    </head>
    <body>
        <button id="signup-btn">Sign Up</button>

        <script>
            const { Analytics } = window.DerivAnalytics

            // Initialize
            Analytics.initialise({
                rudderstackKey: 'YOUR_KEY',
                posthogOptions: {
                    apiKey: 'YOUR_POSTHOG_KEY',
                },
            })

            // Track button clicks
            document.getElementById('signup-btn').addEventListener('click', () => {
                Analytics.trackEvent('ce_signup_button', {
                    action: 'click',
                    location: 'header',
                })
            })
        </script>
    </body>
</html>
```

## 配置

### 舵手Stack 配置

RanderStack用于事件跟踪,包括性能优化:

```typescript
await Analytics.initialise({
    rudderstackKey: 'YOUR_RUDDERSTACK_KEY',
})
```

**内建性能特征 :**

-   **事件夹击**: 10个事件或10秒后浮起
-   **发送 Beacon API**: 用途 `navigator.sendBeacon` 页面卸载中更好的性能
-   **自动重试**: 请求被自动重审
-   **Cookie 管理器**: 自动匿名ID生成和持久性(6个月饼干寿命)
-   **离线支持**: 离线时缓存事件, 恢复连接时重放

### PostHog 配置

PostHog提供分析,会话录音,以及特色旗帜.

#### 初始化

`getPosthogInstance` (和 `Analytics.initialise`)使用单通——用相同的密钥不止一次地调用它们,在不重运行SDK init的情况下返回已存在的实例. 在应用程序启动时拨打一次电话, 不在内部生成循环 .

```typescript
await Analytics.initialise({
    rudderstackKey: 'YOUR_RUDDERSTACK_KEY',
    posthogOptions: {
        apiKey: 'phc_YOUR_KEY',

        // Optional: override the auto-resolved API host (see table below)
        api_host: 'https://ph.deriv.com',

        // Optional: overridable settings (see "Overridable defaults" table below)
        config: {
            autocapture: false, // disable autocapture entirely (also disables $rageclick)
            disable_session_recording: true, // opt out of session recording
            session_recording: {
                sessionRecordingSampleRate: 0.5, // record 50% of sessions
            },
            before_send: event => {
                // your function runs after the built-in domain + timestamp filter
                if (event?.properties?.sensitive_field) return null
                return event
            },
        },
    },
})
```

`api_host` 自动解析自 `window.location.hostname` 如果省略:

| 域图案 | 已确定主机 |
| --- | --- |
| `*.deriv.me` | `https://ph.deriv.me` |
| `*.deriv.be` | `https://ph.deriv.be` |
| `*.deriv.ae` | `https://ph.deriv.ae` |
| 所有其他(包括安全部门改革) | `https://ph.deriv.com` |

#### 强制设置

适用这些规定 **之后** 任何消费者 `config` 展开。 送他们进来 `config` 无效 :

| 设置 | 数值 | 原因 |
| --- | --- | --- |
| `person_profiles` | `'identified_only'` | 防止匿名剖析bloat |
| `capture_pageview` | `'history_change'` | SPA -- -- 安全 -- -- 每起火灾 `pushState` 编号 : `replaceState` |
| `capture_pageleave` | `true` | 标准会话完整性 |
| `session_recording.recordCrossOriginIframes` | `true` | 抓取嵌入式工具 |
| `session_recording.minimumDurationMilliseconds` | `30000` | 过滤子- 30秒噪声会话 |
| `session_recording.maskAllInputs` | `true` | 隐私——消费者不能降低 |

里面的消费键 `session_recording` 正在展开 **在此之前** 这些强制值,所以额外的像 `sessionRecordingSampleRate` 在不发生冲突的情况下生效.

#### 无法逾越的默认

| 设置 | 默认 | 当.. |
| --- | --- | --- |
| `autocapture` | `{ dom_event_allowlist: ['click'], element_allowlist: ['button', 'a'] }` | 您需要更多的事件类型或元素 。 避免 `false` ——它也会禁用 `$rageclick` |
| `rageclick` | `true` | 你想停止捕捉愤怒点击 |
| `capture_dead_clicks` | `true` | 您想要停止捕捉已死点击 |
| `rate_limiting.events_per_second` | `10` | 合法用户流量击中了爆炸限制器 |
| `rate_limiting.events_burst_limit` | `100` | 合法用户流量击中了爆炸限制器 |

#### QQ 不抓取 `$pageview` 手动

`capture_pageview: 'history_change'` 并自动向每个客户端导航开火。 添加手册 `posthog.capture('$pageview')` **将页面视图数增加一倍** 并作出贡献 `$client_ingestion_warning` 费率限制点击.

**反应路由器 :**

```typescript
// ❌ Remove this
useEffect(() => {
    posthog.capture('$pageview')
}, [location.pathname])

// ✅ Nothing needed — capture_pageview: 'history_change' handles it
```

**Vue 路由器 :**

```typescript
// ❌ Remove this
router.afterEach(() => {
    posthog.capture('$pageview')
})

// ✅ Nothing needed — capture_pageview: 'history_change' handles it
```

#### 域允许列表

事件被无声地封锁在 `before_send` 除非主机名符合 :

-   `deriv.com`, (中文(简体) ), `deriv.be`, (中文(简体) ), `deriv.me`, (中文(简体) ), `deriv.team`, (中文(简体) ), `deriv.ae`
-   `localhost` 财务报告和审定财务报表 `127.0.0.1` 总是允许

此列表为硬码而不可配置 .

#### Stale cookie 清理

在每一处,剩下的 `ph_*_posthog` 前一个或旋转的 API 密钥中的 cookie 会被自动删除 。 无需采取行动.

## 核心 API

### 初始化

在跟踪事件之前初始化分析实例 :

```typescript
await Analytics.initialise({
    rudderstackKey: 'YOUR_RUDDERSTACK_KEY',
    posthogOptions: {
        apiKey: 'phc_YOUR_POSTHOG_KEY',
        config: {
            autocapture: true,
        },
    },
    debug: false, // Enable to log all analytics calls to the console
})
```

### 事件跟踪

跟踪带有任何有效载荷的自定义事件——不存在强制属性类型. 发送您的活动需要的 :

```typescript
Analytics.trackEvent('ce_login_form', {
    action: 'login_cta',
    login_provider: 'email',
    form_name: 'main_login',
})

Analytics.trackEvent('ce_signup_form', {
    action: 'signup_done',
    signup_provider: 'google',
    cta_information: {
        cta_name: 'get_started',
        section_name: 'hero',
    },
})
```

### 用户标识

确定分析提供者的用户和同步特征:

#### 简单识别

```typescript
// Identify user with ID only
Analytics.identifyEvent('CR123456')
```

#### 与自定义特征的识别

```typescript
// Send same traits to both RudderStack and PostHog (no PostHog-specific fields)
Analytics.identifyEvent('CR123456', {
    language: 'en',
    country_of_residence: 'US',
    account_type: 'real',
})

// Send provider-specific traits (recommended when using PostHog)
// PostHog requires `email` to automatically compute the `is_internal` flag
Analytics.identifyEvent('CR123456', {
    rudderstack: {
        language: 'en',
        custom_field: 'value',
    },
    posthog: {
        email: 'user@example.com', // Required for PostHog — used to set is_internal flag
        language: 'en',
        country_of_residence: 'US',
    },
})
```

**如何运作:**

-   如果通过一个简单的对象(例如, `{ language: 'en' }`),同样的特征被发送给两个供应商
-   如果您通过对象 `rudderstack` 或者说 `posthog` 键, 使用提供者特有的特性
-   如果提供者尚未初始化, 队列识别呼叫
-   PostHog 自动处理匿名用户和识别用户之间的异名
-   何时 `email` 以后霍格特征提供 `is_internal` 旗帜自动计算并设定为个人财产—— `email` 本身是 **没有** 转发到 PostHog

#### 猪后身份生命周期

| 假设 | 打电话 |
| --- | --- |
| 用户日志在 | `identifyEvent(user_id, { posthog: { email, language, country_of_residence } })` |
| 用户日志退出 | `reset()` |
| 上一个会话中已经识别的用户, 可能缺少个人属性 | `backfillPersonProperties({ user_id, email, language, country_of_residence })` |

**`identifyEvent`** 链接匿名 PostHog 会话到用户并强制 `client_id`。如果当前不同的ID已经相同,则跳过它 `user_id` ——库自动进行此检查.

**`reset`** 清除关闭的 PostHog 会话。 未来的事情是匿名的 `identifyEvent`。 。 。 .

**`backfillPersonProperties`** 填入返回用户配置文件中可能缺失的属性(如. `client_id`, (中文(简体) ), `is_internal`) (中文(简体) ). 它在写作前检查每个属性,如果所有东西都已经存在,它就是一个不开放的. 在用户ID可用后, 随同或代替使用一次 `identifyEvent` 用于返回用户.

> **账户开关守卫**: 两者 `identifyEvent` 财务报告和审定财务报表 `backfillPersonProperties` 当 PostHog 存储的单独ID 属于 _不同_ 已识别用户( 不是匿名的 UUID) 和呼叫 `posthog.reset()` 在识别新用户之前自动。 这样做可以防止各账户的合并.

### 页视图

音轨页面导航 :

```typescript
// Basic page view
Analytics.pageView('/dashboard')

// With custom platform name
Analytics.pageView('/dashboard', 'Deriv Trader')

// With additional properties
Analytics.pageView('/trade', 'Deriv App', {
    section: 'multipliers',
    instrument: 'forex',
})
```

**说明**: PostHog 页面视图通过执行自动获取 `capture_pageview: 'history_change'` 设置。 不要打电话 `posthog.capture('$pageview')` 手动——见 [QQ 不抓取 `$pageview` 手动](https://npmcn.com/package/%40deriv-com/analytics/#readme--do-not-capture-pageview-manually) 节。 人工页面视图跟踪 `Analytics.pageView()` 主要为陆克文Stack服务.

### 用户属性

设置自动包含在以后所有事件的用户和上下文属性. 传出任何密钥值配对——没有执行固定方案:

```typescript
Analytics.setAttributes({
    country: 'US',
    user_language: 'en',
    account_type: 'real',
    device_type: 'mobile',
    account_currency: 'USD',
    account_mode: 'demo',
    residence_country: 'US',
    loggedIn: true,
    // any additional fields your app needs
})
```

### 重置用户会话

清除所有提供者的用户会话( 如在登录时) :

```typescript
Analytics.reset()
```

## 缓存离线支持( O)

软件包包括自动缓存以确保不丢失事件——不需要额外配置.

### 本地缓存( SDK 尚未装入)

当你打电话 `trackEvent` 或者说 `pageView` 在此之前 `initialise()` 完整,事件存储于 `localStorage` 并在SDK加载后自动重放 :

```typescript
// Safe to call before initialise() — automatically replayed on load
Analytics.trackEvent('button_clicked', { button: 'submit' })
Analytics.pageView('/dashboard')
```

### 内存卡(离线)

当用户下线但SDK已经初始化时,事件会在内存中进行并冲入下一个在线 `trackEvent` 电话 :

```typescript
// While offline — queued in memory, sent automatically when back online
Analytics.trackEvent('offline_event', { data: 'cached' })
```

### 基于路线的事件

仅在特定页面上使用 `loadEvent`数字 :

```typescript
Analytics.loadEvent([
    {
        pages: ['dashboard', 'profile'],
        event: { name: 'ce_page_load', properties: { page_type: 'authenticated' } },
    },
    {
        excludedPages: ['login'],
        event: { name: 'ce_authenticated_view', properties: {} },
    },
])
```

## 调试模式

启用动词记录以追踪浏览器控制台中每次分析呼叫:

```typescript
await Analytics.initialise({
    rudderstackKey: 'YOUR_KEY',
    posthogOptions: { apiKey: 'phc_YOUR_KEY' },
    debug: true,
})
```

所有日志前缀为 `[ANALYTIC]` (例如, `[ANALYTIC][RudderStack] trackEvent | ...`) (中文(简体) ). 开发期间和QA用于验证事件的实用性是在不打开网络标签的情况下正确发射.

## 高级使用

### 独立软件包使用

每个供应商可独立使用,以达到最大灵活性:

#### 仅限后霍格

```typescript
import { Posthog } from '@deriv-com/analytics/posthog'

const posthog = Posthog.getPosthogInstance({
    apiKey: 'phc_YOUR_KEY',
    config: {
        autocapture: true,
        session_recording: {
            recordCrossOriginIframes: true,
        },
    },
})

// Track events
posthog.capture('button_clicked', { button_name: 'signup' })

// Identify users — email is required and used to compute is_internal
posthog.identifyEvent('CR123', { email: 'user@example.com', language: 'en' })

// Check feature flags
const isEnabled = posthog.isFeatureEnabled('new-feature')
const variant = posthog.getFeatureFlag('button-color')
```

#### 仅限舵板

```typescript
import { RudderStack } from '@deriv-com/analytics/rudderstack'

const rudderstack = RudderStack.getRudderStackInstance('YOUR_KEY', () => {
    console.log('RudderStack loaded')
})

// Track events
rudderstack.track('button_clicked', { button: 'signup' })

// Identify users
rudderstack.identifyEvent('CR123', { language: 'en' })

// Track page views
rudderstack.pageView('/dashboard', 'Deriv App', 'CR123')
```

### 访问提供者实例

高级使用情况下访问原始提供者实例:

```typescript
const { tracking, posthog } = Analytics.getInstances()

// Access PostHog directly
if (posthog?.has_initialized) {
    posthog.capture('custom_event', { property: 'value' })

    // Access PostHog feature flags
    const isEnabled = posthog.isFeatureEnabled('new-feature')
}

// Access RudderStack directly
if (tracking?.has_initialized) {
    const userId = tracking.getUserId()
    const anonId = tracking.getAnonymousId()
}
```

## 后霍格特性旗

通过 `posthog` 实例:

```typescript
const { posthog } = Analytics.getInstances()

// Boolean flag — returns true, false, or undefined (not ready)
const isEnabled = posthog?.isFeatureEnabled('my-flag')

// Multivariate flag — returns a string variant, boolean, or undefined
const variant = posthog?.getFeatureFlag('button-color') // e.g. 'red' | 'blue' | true | undefined

// Structured payload attached to a flag
const config = posthog?.getFeatureFlagPayload('pricing-config') // e.g. { price: 9.99 }

// All active flags as a map
const allFlags = posthog?.getAllFlags() // { 'flag-a': true, 'flag-b': 'variant-x' }

// Subscribe to flag changes (fires immediately + on every reload)
const unsubscribe = posthog?.onFeatureFlags((flags, variants) => {
    console.log('active flags:', flags)
    console.log('variants:', variants)
})
// Call unsubscribe() to stop listening

// Force a reload from the server (e.g. after login or attribute change)
posthog?.reloadFeatureFlags()
```

直接使用 PostHog 时( 无 `Analytics` 包装 :

```typescript
import { Posthog } from '@deriv-com/analytics/posthog'

const posthog = Posthog.getPosthogInstance({ apiKey: 'phc_YOUR_KEY' })
const isEnabled = posthog.isFeatureEnabled('my-flag')
```

## PostHog 整合检查列表

在装运前,核实:

-   [ ] `Analytics.initialise` (或 `getPosthogInstance`)称为 **一次** 应用程序启动时——不是每次渲染或路由更改时
-   [ ] 没有 `posthog.capture('$pageview')` 电话保留——搜索密码库并删除
-   [ ] `identifyEvent` 在登录时调用 `email` 后霍格特征(用于 `is_internal` 旗帜)
-   [ ] `reset()` 正在调用登录
-   [ ] `backfillPersonProperties` 当用户ID可用时,需要返回用户
-   [ ] 您的域名在许可列表中—— 如果在非..`deriv.*` 域外的 `localhost`,事件被无声地封锁
-   [ ] `debug: true` 被清除或后方守卫 `process.env.NODE_ENV === 'development'`

## API 参考

### `initialise(options: Options): Promise<void>`

初始化分析实例 .

**参数:**

```typescript
interface Options {
    rudderstackKey?: string
    posthogOptions?: {
        apiKey: string
        /**
         * Optional PostHog API host. If omitted, resolved automatically based on window.location.hostname:
         *   *.deriv.me  → https://ph.deriv.me
         *   *.deriv.be  → https://ph.deriv.be
         *   *.deriv.ae  → https://ph.deriv.ae
         *   all others  → https://ph.deriv.com (default; also used server-side)
         */
        api_host?: string
        config?: PostHogConfig
    }
    /** Enable verbose debug logging — all analytics calls are logged prefixed with [ANALYTIC] */
    debug?: boolean
}
```

### `trackEvent(event: string, payload: Record<string, any>): void`

追踪一个事件。 没有执行有效载荷计划——发送任何键值对.

### `pageView(url: string, platform?: string, properties?: Record<string, unknown>): void`

音轨页面导航.

### `identifyEvent(userId?: string, traits?: Record<string, any>): void`

将匿名会话链接到具有可选特性的用户ID. 当 PostHog 活动时, 特性包括 `email` 字段(通过特定提供者) `posthog` 键), `is_internal` 自动计算并设定为个人财产——电子邮件本身不存储在PostHog中.

### `backfillPersonProperties({ user_id, email?, country_of_residence? }): void`

后填充 PostHog 前几会中识别的用户的人物属性 。 设定 `client_id` 财务报告和审定财务报表 `is_internal` 如果他们还没有出现。 如果 PostHog 没有初始化或 `user_id` 为空.

```typescript
// Call after PostHog has loaded and user ID is available
Analytics.backfillPersonProperties({ user_id: 'CR123456', email: 'user@example.com', country_of_residence: 'US' })
```

### `setAttributes(attributes: Record<string, any>): void`

更新流向所有提供者的用户属性 。 没有执行任何计划.

### `loadEvent(items: PageLoadEventConfig[]): void`

以当前页面路径名为条件的火灾事件 .

```typescript
type PageLoadEventConfig = {
    pages?: string[] // fire only on these pages
    excludedPages?: string[] // fire on all pages except these
    event: { name: string; properties: Record<string, any> }
    callback?: () => { name: string; properties: Record<string, any> }
}
```

### `reset(): void`

清除所有提供者的用户会话 .

### `getId(): string`

获取当前用户身份 .

### `getAnonymousId(): string`

获取匿名用户身份.

### `getInstances(): { tracking, posthog }`

访问原始提供者实例.

## 业绩

### 基准

-   **事件跟踪**: < 5ms(平均)
-   **页面视图跟踪**: < 3ms(平均)
-   **初始化**: ~200ms(同时提供两种)
-   **离线缓存重放**: <50ms,用于10个活动

### 优化

-   **树摇**: 未使用供应商从捆绑中完全删除
-   **懒惰装入**: PostHog 仅在配置时才动态加载
-   **事件夹击**: RanderStack分批事件(10起事件或10秒)
-   **发送 Beacon**: 用途 `navigator.sendBeacon` 在卸页时可靠事件交付
-   **复制**: 防止重复事件被发送

### 套装大小

估计大小( 小于 + gziped) :

-   **核心( RudderStack + Post Hog)**: ~32 KB 键
-   **仅限舵板**:~18 KB 键
-   **仅限后霍格**: ~20 KB 键
-   **浏览器 Bundle( 全部包含)**: ~125 KB 击出

## 解决问题

### 未在 RanderStack 中出现的事件

1.  **校验 API 密钥**检查 `rudderstackKey` 正确的
2.  **检查网络请求**: 打开 DevTools = 网络标签 = 查找对 RanderStack 数据平面的请求
3.  **验证初始化**运行 `Analytics.getInstances().tracking.has_initialized` 在控制台中
4.  **检查批次**: 事件进行分批 - 等待~10秒或发送10个事件

### 无法接收事件

1.  **校验 API 密钥**: 检查 PostHog API 密钥是否正确( 启动于 `phc_`(中文(简体) )
2.  **检查域允许列表**: 校验您的域名 `allowedDomains` 列表
3.  **检查初始化**运行 `Analytics.getInstances().posthog?.has_initialized` 在控制台中
4.  **验证网络请求**: 检查 DevTools 请求到 `ph.deriv.com` 或您的 PostHog 主机
5.  **检查浏览器控制台**: 查找 PostHog 错误或警告

### 会话记录不工作

1.  **校验配置**: 确保 `disable_session_recording: false` (或省略之说
2.  **检查最小持续时间**: 会话短于 `minimumDurationMilliseconds` 未保存
3.  **校验域**: 检查 PostHog 已初始化并允许域
4.  **检查 PostHog 仪表板**:录制可能需要几分钟的时间才能出现

### 缓存但未发送的事件

1.  **检查在线状态**运行 `navigator.onLine` 在控制台中
2.  **验证已装入的 SDK**运行 `Analytics.getInstances().tracking.has_initialized`
3.  **检查存储**: 打开 DevTools —— 应用程序 —— 本地存储 —— 寻找 `cached_analytics_events` 财务报告和审定财务报表 `cached_analytics_page_views` 键。 这个 `rudder_anonymous_id` 仍作为饼干保存.
4.  **手动清除缓存**: 清除本地密钥或运行 `Analytics.reset()`

## 移徙指南

### 从v1.x到v2.x

#### 中断更改

1.  **识别事件签名已更改**数字 :

```typescript
// Old (v1.x) - hardcoded traits
Analytics.identifyEvent('CR123')

// New (v2.x) - custom traits
Analytics.identifyEvent('CR123', {
    language: 'en',
    country_of_residence: 'US',
})

// Or provider-specific
Analytics.identifyEvent('CR123', {
    rudderstack: { language: 'en' },
    posthog: { language: 'en', country_of_residence: 'US' },
})
```

2.  **增长减值**: 迁移到 PostHog 特性旗

```typescript
// Old (GrowthBook)
const isEnabled = Analytics.isFeatureOn('new-feature')

// New (PostHog)
const { posthog } = Analytics.getInstances()
const isEnabled = posthog?.isFeatureEnabled('new-feature')
```

## 捐款

欢迎捐款! 请遵照这些准则:

1.  叉子存储器
2.  创建特性分支
3.  为您的更改撰写测试
4.  运行 `npm test` 财务报告和审定财务报表 `npm run build`
5.  提交拉动请求

## 许可证

麻省理工学院

## 支助

关于议题和问题清单:

-   **GitHub 问题**数字 : [https://github.com/binary-com/deriv-analytics/ issues (中文(中国大陆) )](https://github.com/binary-com/deriv-analytics/issues)
-   **文档**数字 : [https://github.com/binary-com/deriv-analysis. \[永久失效連結\] (中文(简体) )](https://github.com/binary-com/deriv-analytics)

## 常见问题

### @deriv-com/analytics 是什么？

Deriv应用的综合分析包\. 通过RuderStack,PostHog和GrowthBook集成,提供统一的事件跟踪,A/B测试,以及用户分析,内置缓存和离线支持\.

### 如何安装 @deriv-com/analytics？

在项目目录运行 npm install @deriv-com/analytics，或使用 pnpm add / yarn add / bun add。

### @deriv-com/analytics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deriv-com/analytics 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deriv-com/analytics 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deriv-com/analytics 可以商用吗？

@deriv-com/analytics 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deriv-com/analytics 的下载量有多少？

根据 npm 官方下载统计，@deriv-com/analytics 在 2026/10/12 – 2026/11/10 这 30 天内被下载 8,770 次，日均约 292 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deriv-com/analytics 还在维护吗？

最新版本 1\.44\.0 发布于 2026/10/13（29 天前）；至今共发布 121 个版本，其中过去 12 个月发布了 41 个；首次发布于 2024/01/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。