---
title: "Mixpanel 连接器"
description: "完整的 Mixpanel 集成指南，通过 Tajo 将产品分析事件、用户档案和群组与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/mixpanel/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/mixpanel.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Mixpanel 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

通过 Tajo 将 Mixpanel 连接到 Brevo，将产品分析与营销自动化相结合。同步用户档案、行为事件和群组，基于真实产品使用情况创建数据驱动的活动。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Mixpanel |
| **类别** | 分析（自定义） |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 事件、档案、群组、分组 |
| **可用技能** | 7 |

## 功能

- **事件摄取** - 通过 Mixpanel 的摄取 API 将追踪事件导入 Brevo 工作流
- **用户档案同步** - 将 Mixpanel 用户档案属性映射到 Brevo 联系人属性
- **群组导出** - 将 Mixpanel 群组同步到 Brevo 联系人列表，用于精准活动
- **群体分析** - 同步群体级数据，用于 B2B 基于账户的营销
- **身份管理** - 利用 Mixpanel 的身份合并实现统一客户档案
- **JQL 查询** - 运行自定义 JQL 查询，为 Brevo 提取特定数据集
- **查找表** - 从 Mixpanel 查找表同步富化数据

## 前提条件

开始之前，请确保您已具备：

1. 已创建项目的 Mixpanel 账户
2. 用于客户端追踪的 Mixpanel 项目令牌
3. 具有适当权限的服务账户，用于服务器端 API 访问
4. 具有 API 访问权限的 Brevo 账户
5. 具有 API 凭据的 Tajo 账户

## 认证

### 服务账户（推荐）

Mixpanel 推荐使用服务账户进行 API 认证。服务账户使用 HTTP Basic Auth，以服务账户用户名和密码（服务账户密钥）进行认证。

```bash
# Service Account authentication
curl https://mixpanel.com/api/app/me \
  -u "SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET"
```

### 项目令牌

项目令牌用于客户端事件追踪，可安全地包含在客户端代码中：

```javascript
// Client-side initialization
mixpanel.init("YOUR_PROJECT_TOKEN");
```

### OAuth（合作伙伴集成）

对于访问多个项目的应用集成：

```bash
curl https://mixpanel.com/api/2.0/engage \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"
```

## 配置

### 基础设置

```yaml
connectors:
  mixpanel:
    enabled: true
    project_token: "your-project-token"
    service_account:
      username: "your-service-account-username"
      secret: "your-service-account-secret"
    project_id: "12345"
    data_residency: "US"  # or "EU"

    # Data sync options
    sync:
      events: true
      profiles: true
      cohorts: true
      groups: false

    # Brevo list assignment
    lists:
      all_users: 15
      engaged_users: 16
      at_risk: 17
```

### 事件映射

将 Mixpanel 事件映射到 Brevo 事件类型：

```yaml
event_mapping:
  # Mixpanel event -> Brevo event
  "Purchase": "order_completed"
  "Sign Up": "customer_created"
  "Add to Cart": "cart_updated"
  "Page View": "page_viewed"
  "$experiment_started": "experiment_started"

  # Custom events
  "Feature Activated": "feature_used"
  "Subscription Renewed": "subscription_renewed"
```

### 档案属性映射

将 Mixpanel 用户属性映射到 Brevo 联系人属性：

```yaml
property_mapping:
  $email: email
  $first_name: FIRSTNAME
  $last_name: LASTNAME
  $phone: SMS
  $city: CITY
  $region: REGION
  $country_code: COUNTRY
  plan: PLAN_TYPE
  company: COMPANY
  signup_date: SIGNUP_DATE
  total_revenue: LTV
```

## API 端点

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `POST` | `/import` | 导入事件（摄取 API） |
| `POST` | `/track` | 追踪事件（客户端） |
| `POST` | `/engage#$set` | 设置用户档案属性 |
| `POST` | `/engage#$set_once` | 仅在未设置时设置属性 |
| `POST` | `/engage#$delete` | 删除用户档案 |
| `POST` | `/engage#$union` | 合并到列表属性 |
| `POST` | `/groups` | 设置群组档案属性 |
| `GET` | `/export` | 导出原始事件数据 |
| `POST` | `/cohorts/list` | 列出已保存的群组 |
| `POST` | `/engage/query` | 查询用户档案 |
| `POST` | `/jql` | 运行自定义 JQL 查询 |
| `GET` | `/segmentation` | 查询细分报告 |
| `GET` | `/retention` | 查询留存报告 |
| `GET` | `/funnels` | 查询漏斗报告 |

## 代码示例

### 初始化 Mixpanel 连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Mixpanel project
await tajo.connectors.connect('mixpanel', {
  projectToken: process.env.MIXPANEL_TOKEN,
  serviceAccountUser: process.env.MIXPANEL_SA_USER,
  serviceAccountSecret: process.env.MIXPANEL_SA_SECRET,
  projectId: process.env.MIXPANEL_PROJECT_ID
});
```

### 通过摄取 API 导入事件

```javascript
// Import events to Mixpanel (automatically forwarded to Brevo)
const response = await fetch('https://api.mixpanel.com/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa(
      `${process.env.MIXPANEL_SA_USER}:${process.env.MIXPANEL_SA_SECRET}`
    )
  },
  body: JSON.stringify([
    {
      event: "Purchase",
      properties: {
        distinct_id: "user_123",
        $insert_id: "evt_abc123",
        time: Math.floor(Date.now() / 1000),
        revenue: 89.99,
        product_id: "SKU-001",
        product_name: "Widget Pro"
      }
    }
  ])
});

// Expected response: { "code": 200, "status": "OK", "num_records_imported": 1 }
```

### 将群组同步到 Brevo

```javascript
// Export a Mixpanel cohort and sync to a Brevo list
const cohort = await tajo.connectors.syncCohort('mixpanel', {
  cohortId: 12345,
  targetList: 16,
  syncMode: 'mirror'
});

console.log(cohort);
// {
//   cohortName: "Engaged Users (Last 7 Days)",
//   membersCount: 3200,
//   syncedToBrevo: 3200,
//   listId: 16
// }
```

### 设置用户档案属性

```javascript
// Set user properties via the Engage API
const response = await fetch('https://api.mixpanel.com/engage#$set', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify([{
    $token: process.env.MIXPANEL_TOKEN,
    $distinct_id: "user_123",
    $set: {
      $email: "jane@example.com",
      $first_name: "Jane",
      $last_name: "Kim",
      plan: "premium",
      total_orders: 12,
      lifetime_value: 1250.00
    }
  }])
});
```

## 速率限制

| API | 限制 | 详情 |
| --- | --- | --- |
| **摄取 API** | 2 GB/分钟 | 每项目 |
| **追踪 API** | 无硬限制 | 尽力投递 |
| **Engage API** | 每批 2,000 次更新 | 每项目最多 2 GB/分钟 |
| **查询 API** | 60 请求/小时 | 每项目（服务账户） |
| **导出 API** | 60 请求/小时 | 每次查询最多 100 天 |
| **JQL API** | 60 请求/小时 | 每项目 |
| **群组导出** | 60 请求/小时 | 每项目 |

事件去重

Mixpanel 使用 `$insert_id` 属性对事件进行去重。重试失败的导入时，始终包含唯一的 `$insert_id` 以防止重复事件。

## 故障排除

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 事件未出现 | 项目令牌错误 | 验证令牌与目标项目匹配 |
| 档案属性缺失 | 使用了错误的 API | 档案属性使用 `/engage#$set`，不要用 `/track` |
| 群组导出失败 | 权限不足 | 确保服务账户具有管理员或分析师角色 |
| 重复事件 | 缺少 `$insert_id` | 每个事件都包含唯一的 `$insert_id` |
| 402 Payment Required | 超出数据限制 | 检查 Mixpanel 计划限制并按需升级 |
| 欧盟数据未路由 | 数据驻留地设置错误 | 欧盟项目使用 `api-eu.mixpanel.com` |
| 身份合并问题 | distinct\_id 不正确 | 遵循 Mixpanel 的身份管理最佳实践 |

## 最佳实践

1. **使用服务账户** - 优先使用服务账户而非项目密钥进行服务器端认证
2. **包含 `$insert_id`** - 始终设置唯一的插入 ID 以进行事件去重
3. **批量档案更新** - 每次请求发送最多 2,000 个档案更新以提高效率
4. **使用欧盟端点** - 对于欧盟数据驻留，所有 API 调用使用 `api-eu.mixpanel.com`
5. **按计划同步群组** - 设置每日或每周的群组同步，而非持续轮询
6. **映射保留属性** - 使用 Mixpanel 的保留属性（`$email`、`$first_name`）存储档案数据
7. **监控摄取** - 使用 Mixpanel 的事件页面验证事件是否正确接收

## 安全

- **仅 HTTPS** - 所有 API 通信需要 TLS 加密
- **服务账户隔离** - 每个项目基于角色的权限范围访问
- **事件去重** - 通过 `$insert_id` 内置去重防止数据完整性问题
- **SOC 2 Type II** - Mixpanel 通过 SOC 2 Type II 认证
- **GDPR/CCPA** - 通过 GDPR API 支持用户数据删除
- **欧盟数据驻留** - 提供欧盟数据中心用于欧洲合规

## 相关资源

- [Twilio Segment 连接器](https://tajo.io/zh-cn/docs/connectors/custom/segment)
- [Amplitude 连接器](https://tajo.io/zh-cn/docs/connectors/custom/amplitude)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 事件 API](https://tajo.io/zh-cn/docs/events-engagement/create-event)