Integrate Argus

接入 Argus 回放系统 SDK

本规则指导如何在业务项目中接入 Argus 会话回放录制 SDK。

前置条件

• projectKey: 必须到 Argus 平台申请，每个业务项目对应一个 projectKey，申请后写入环境变量 VITE_ARGUS_PROJECT_KEY

默认配置

• ingestPoint: 统一使用 https://aurora.openxlab.org.cn，SDK 会自动拼接 /v1/web/... 路径
• 环境隔离: 测试、预发、生产等环境通过不同的 projectKey 区分，不通过不同的 ingestPoint 区分

ingestPoint 配置

所有环境都使用同一个 ingestPoint：

const ingestPoint = 'https://aurora.openxlab.org.cn';

对应 .env 文件仅区分 projectKey：

# .env.staging
VITE_ARGUS_PROJECT_KEY=your-staging-project-key

# .env.production
VITE_ARGUS_PROJECT_KEY=your-production-project-key

安装

npm install @argus/tracker --registry=https://nexus.openxlab.org.cn/repository/npm-all/
# 或
pnpm add @argus/tracker --registry=https://nexus.openxlab.org.cn/repository/npm-all/

或在项目 .npmrc 中配置 registry 后直接安装：

# .npmrc
@argus:registry=https://nexus.openxlab.org.cn/repository/npm-all/

npm install @argus/tracker

基础接入

import Tracker from '@argus/tracker';

const tracker = new Tracker({
  projectKey: '<YOUR_PROJECT_KEY>', // 在 Argus 平台申请
  ingestPoint: 'https://aurora.openxlab.org.cn',
  network: {
    sessionTokenHeader: false,
    ignoreHeaders: ['Cookie', 'Set-Cookie', 'Authorization'],
    captureInIframes: true,
    capturePayload: true,
    failuresOnly: false,
  },
});

// 无需等待用户登录即可启动录制
tracker.start();

// 用户登录后，补充 userID 以关联用户身份
tracker.setUserID('<当前登录用户唯一标识>');

CDN 方式接入

<script src="https://static.openreplay.com/latest/openreplay.js"></script>
<script>
  const tracker = new OpenReplay.Tracker({
    projectKey: '<YOUR_PROJECT_KEY>',
    ingestPoint: 'https://aurora.openxlab.org.cn',
    __DISABLE_SECURE_MODE: location.hostname === 'localhost',
    network: {
      sessionTokenHeader: false,
      ignoreHeaders: ['Cookie', 'Set-Cookie', 'Authorization'],
      captureInIframes: true,
      capturePayload: true,
      failuresOnly: false,
    },
  });
  // 无需等待登录即可启动
  tracker.start();
  // 用户登录后补充身份
  if (userId) tracker.setUserID(userId);
</script>

环境隔离

• 仅当 VITE_ENABLE_TRACKER=true 时才启动录制
• 通过 __DISABLE_SECURE_MODE: true 可在 HTTP 环境下使用（仅限开发）

const shouldRecord = import.meta.env.VITE_ENABLE_TRACKER === 'true';

if (shouldRecord) {
  tracker.start();
}

// 用户登录后再关联身份（非必须，未登录也能正常录制）
if (currentUser?.id) {
  tracker.setUserID(currentUser.id);
}

自定义事件

当构建工具移除了 console（如 esbuild.drop: ['console']）时，使用 tracker.event() 记录关键业务节点：

tracker.event('checkout_start', { step: 1, orderId: '123' });
tracker.event('payment_success', { amount: 99.9, method: 'alipay' });

这些事件会出现在回放侧边栏「事件」标签中，标签为「自定义」。

敏感数据脱敏

HTML 属性方式

<!-- 遮蔽文本（显示为 ****） -->
<input type="text" name="phone" data-openreplay-obscured />
<span data-openreplay-obscured>敏感信息</span>

<!-- 完全隐藏 -->
<input type="password" name="token" data-openreplay-hidden />

domSanitizer 方式

import Tracker, { SanitizeLevel } from '@argus/tracker';

const tracker = new Tracker({
  projectKey: '<YOUR_PROJECT_KEY>',
  ingestPoint: 'https://aurora.openxlab.org.cn',
  domSanitizer: (node: Element) => {
    if (node.classList.contains('sensitive')) return SanitizeLevel.Obscured;
    if (node.id === 'credit-card') return SanitizeLevel.Hidden;
    return SanitizeLevel.Plain;
  },
});

注意：父节点被遮蔽后，子节点一并遮蔽。只对最小粒度节点标记。

CSP 配置

SDK 通过 blob: URL 创建 Web Worker 辅助录制。若站点有 CSP 策略：

方式一（推荐）： 在 CSP 响应头增加：

worker-src 'self' blob:;

方式二： 关闭辅助录制 Worker（无需改 CSP）：

const tracker = new Tracker({
  projectKey: '<YOUR_PROJECT_KEY>',
  ingestPoint: 'https://aurora.openxlab.org.cn',
  assistRecordWorker: false,
});

常见集成模式

React 项目

// src/tracker.ts
import Tracker from '@argus/tracker';

let tracker: Tracker | null = null;

export function initTracker() {
  if (tracker) return tracker;
  if (import.meta.env.VITE_ENABLE_TRACKER !== 'true') return null;

  tracker = new Tracker({
    projectKey: import.meta.env.VITE_ARGUS_PROJECT_KEY,
    ingestPoint: 'https://aurora.openxlab.org.cn',
    network: {
      sessionTokenHeader: false,
      ignoreHeaders: ['Cookie', 'Set-Cookie', 'Authorization'],
      capturePayload: true,
    },
  });

  tracker.start();
  return tracker;
}

// 用户登录后调用，关联用户身份
export function identifyUser(userId: string) {
  tracker?.setUserID(userId);
}

export function getTracker() {
  return tracker;
}

// src/main.tsx — 应用启动时即可调用
import { initTracker, identifyUser } from './tracker';

initTracker();

// 用户登录成功后关联身份（非必须）
identifyUser(user.ssouid);

Vue 项目

// src/plugins/tracker.ts
import Tracker from '@argus/tracker';

export default {
  install(app, options: { projectKey: string }) {
    const tracker = new Tracker({
      projectKey: options.projectKey,
      ingestPoint: 'https://aurora.openxlab.org.cn',
      network: {
        sessionTokenHeader: false,
        ignoreHeaders: ['Cookie', 'Set-Cookie', 'Authorization'],
        capturePayload: true,
      },
    });

    app.config.globalProperties.$tracker = tracker;
    app.provide('tracker', tracker);
  },
};

环境变量

按环境配置不同的 projectKey，ingestPoint 固定为 https://aurora.openxlab.org.cn：

# .env.staging
VITE_ARGUS_PROJECT_KEY=your-staging-project-key  # 在 Argus 平台申请
VITE_ENABLE_TRACKER=true

# .env.production
VITE_ARGUS_PROJECT_KEY=your-production-project-key  # 在 Argus 平台申请
VITE_ENABLE_TRACKER=true

验证接入

1. 启动应用，打开浏览器 DevTools Network 面板
2. 过滤 /v1/web/ 请求，应能看到 start 和 batch 请求
3. 在 Argus 平台（https://aurora.openxlab.org.cn/argus/sessions）「会话列表」中确认新会话出现
4. 点击会话进入回放，确认 DOM 录制正常

注意事项

• tracker.start() 不依赖用户登录，应用启动即可调用；用户登录后通过 tracker.setUserID() 补充身份
• projectKey 必须在 Argus 平台申请，与项目和环境一一对应，不通过 API 动态获取
• ingestPoint 统一使用 https://aurora.openxlab.org.cn，不要带 /v1/web 后缀，SDK 会自动拼接
• userID 建议使用业务系统的 SSO UID，方便在 Argus 平台按用户检索
• 网络请求中 Authorization 等敏感 header 默认被 ignoreHeaders 过滤
• 若录制文件过大导致上传失败，可通过 network.capturePayload: false 减少体积