# Integrate Argus

> 支持在测试环境和正式环境接入 Argus 回放系统 SDK（@argus/tracker），用于在业务项目中接入用户会话录制能力

- Skill: `migoxlab/integrate-argus` (Agent Skill)
- Install (CLI): `npx skillmds@latest add migoxlab/integrate-argus`
- Raw SKILL.md: https://api.skillmd.com/api/skills/migoxlab/integrate-argus/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: migoxlab (https://skillmd.com/u/migoxlab)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/migoxlab/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：

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

对应 `.env` 文件仅区分 `projectKey`：

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

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

## 安装

```bash
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 后直接安装：

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

```bash
npm install @argus/tracker
```

## 基础接入

```typescript
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 方式接入

```html
<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 环境下使用（仅限开发）

```typescript
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()` 记录关键业务节点：

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

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

## 敏感数据脱敏

### HTML 属性方式

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

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

### domSanitizer 方式

```typescript
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）：

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

## 常见集成模式

### React 项目

```typescript
// 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;
}
```

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

initTracker();

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

### Vue 项目

```typescript
// 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
# .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` 减少体积