---
title: "PostHog 连接器"
description: "完整的 PostHog 集成指南，通过 Tajo 将产品分析、功能标志和用户行为数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/custom/posthog/
markdown: https://tajo.io/zh-cn/docs/connectors/custom/posthog.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# PostHog 连接器

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

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

通过 Tajo 将 PostHog 连接到 Brevo，同步产品分析数据、用户行为事件和群组成员资格，打造数据驱动的营销活动和个性化客户互动。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | PostHog |
| **类别** | 产品分析（自定义） |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 事件、用户、功能标志、群组 |
| **认证方式** | 个人 API 密钥 / 项目令牌 |

## 功能

- **事件同步** - 将 PostHog 分析事件转发到 Brevo 进行行为定向
- **用户档案同步** - 将 PostHog 用户属性同步到 Brevo 联系人属性
- **基于群组的细分** - 将 PostHog 群组映射到 Brevo 联系人列表
- **功能标志同步** - 按已启用的功能标志细分联系人
- **漏斗数据** - 使用转化漏斗数据进行精准重新参与
- **会话回放元数据** - 用会话参与度指标丰富联系人信息

## 前提条件

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

1. PostHog 账户（云端或自托管）
2. 来自 [PostHog 设置](https://app.posthog.com/settings/user-api-keys) 的个人 API 密钥
3. 来自[项目设置](https://app.posthog.com/project/settings) 的项目 API 密钥（令牌）
4. 具有 API 访问权限的 Brevo 账户
5. 具有连接器权限的 Tajo 账户

## 认证

### 个人 API 密钥（私有端点）

```bash
# Generate at https://app.posthog.com/settings/user-api-keys
export POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key
export POSTHOG_PROJECT_TOKEN=phc_your_project_token
export POSTHOG_HOST=https://us.posthog.com  # or https://eu.posthog.com
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
```

```javascript
// Private API endpoints use Bearer authentication
const headers = {
  'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
  'Content-Type': 'application/json'
};

// Public endpoints use the project token
const publicHeaders = {
  'Content-Type': 'application/json'
};
// Token is passed in the request body for public endpoints
```

API 密钥安全

个人 API 密钥提供完整账户访问权限。切勿在客户端代码中暴露。公共端点（如事件捕获和功能标志评估）使用项目 API 密钥（令牌）。

## 配置

### 基础设置

```yaml
connectors:
  posthog:
    enabled: true
    host: "${POSTHOG_HOST}"
    personal_api_key: "${POSTHOG_PERSONAL_API_KEY}"
    project_token: "${POSTHOG_PROJECT_TOKEN}"
    project_id: "12345"

    sync:
      persons: true
      events: true
      cohorts: true
      feature_flags: true
      schedule: "0 */3 * * *"  # Every 3 hours

    event_filters:
      - "$pageview"
      - "purchase_completed"
      - "signup_completed"
      - "feature_used"

    lists:
      all_users: 25
      active_users: 26
      power_users: 27
```

### 字段映射

```yaml
field_mapping:
  email: email
  $name: FIRSTNAME
  $browser: BROWSER
  $os: OS
  $initial_referrer: REFERRAL_SOURCE
  total_events: EVENT_COUNT
  last_seen: LAST_ACTIVE_DATE
  signup_date: SIGNUP_DATE
  plan: SUBSCRIPTION_PLAN
  company: COMPANY
  cohort_names: POSTHOG_COHORTS
```

## API 端点

| 端点 | 方法 | 描述 |
| --- | --- | --- |
| `{host}/api/projects/{id}/persons/` | GET | 列出用户 |
| `{host}/api/projects/{id}/events/` | GET | 列出事件 |
| `{host}/api/projects/{id}/cohorts/` | GET | 列出群组 |
| `{host}/api/projects/{id}/feature_flags/` | GET | 列出功能标志 |
| `{host}/api/projects/{id}/feature_flags/evaluation/` | POST | 评估标志 |
| `{host}/api/projects/{id}/insights/` | GET | 列出已保存的洞察 |
| `{host}/api/projects/{id}/query/` | POST | 运行 HogQL 查询 |
| `{host}/i/v0/e` | POST | 捕获事件（公共） |
| `{host}/decide/?v=3` | POST | 功能标志决策（公共） |

## 代码示例

### 初始化连接器

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

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

await tajo.connectors.connect('posthog', {
  host: process.env.POSTHOG_HOST,
  personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
  projectToken: process.env.POSTHOG_PROJECT_TOKEN,
  projectId: '12345'
});
```

### 将用户同步到 Brevo

```javascript
// Paginate through PostHog persons
let nextUrl = `${posthogHost}/api/projects/${projectId}/persons/?` +
  new URLSearchParams({ limit: '100' });

while (nextUrl) {
  const response = await fetch(nextUrl, {
    headers: {
      'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`
    }
  });

  const data = await response.json();

  for (const person of data.results) {
    const email = person.properties.$email || person.properties.email;
    if (!email) continue;

    await tajo.contacts.sync({
      email,
      attributes: {
        FIRSTNAME: person.properties.$name || person.properties.name,
        LAST_ACTIVE_DATE: person.properties.$last_seen,
        SIGNUP_DATE: person.created_at,
        EVENT_COUNT: person.properties.$event_count,
        BROWSER: person.properties.$browser,
        OS: person.properties.$os,
        REFERRAL_SOURCE: person.properties.$initial_referrer
      },
      listIds: [25]
    });
  }

  nextUrl = data.next;
}
```

### 将群组同步为 Brevo 列表

```javascript
// Get PostHog cohorts and sync members to Brevo lists
const cohortsResponse = await fetch(
  `${posthogHost}/api/projects/${projectId}/cohorts/`,
  {
    headers: {
      'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`
    }
  }
);

const { results: cohorts } = await cohortsResponse.json();

for (const cohort of cohorts) {
  // Get persons in this cohort
  const personsResponse = await fetch(
    `${posthogHost}/api/projects/${projectId}/cohorts/${cohort.id}/persons/`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`
      }
    }
  );

  const { results: persons } = await personsResponse.json();

  for (const person of persons) {
    const email = person.properties.$email || person.properties.email;
    if (email) {
      await tajo.contacts.update(email, {
        attributes: {
          POSTHOG_COHORTS: cohort.name
        }
      });
    }
  }
}
```

### 运行 HogQL 查询进行分析

```javascript
// Use HogQL to query analytics data
const queryResponse = await fetch(
  `${posthogHost}/api/projects/${projectId}/query/`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: {
        kind: 'HogQLQuery',
        query: `
          SELECT
            properties.$email AS email,
            count() AS event_count,
            max(timestamp) AS last_event
          FROM events
          WHERE event = 'purchase_completed'
            AND timestamp > now() - interval 30 day
          GROUP BY email
          HAVING event_count > 3
          ORDER BY event_count DESC
          LIMIT 1000
        `
      }
    })
  }
);

const queryResult = await queryResponse.json();

for (const row of queryResult.results) {
  await tajo.contacts.update(row[0], {
    attributes: {
      PURCHASE_COUNT_30D: row[1],
      LAST_PURCHASE: row[2]
    }
  });
}
```

## 速率限制

| 端点类别 | 限制 | 说明 |
| --- | --- | --- |
| 分析端点 | 240/分钟，1,200/小时 | GET 用户、事件、洞察 |
| 查询端点 | 2,400/小时 | HogQL 和自定义查询 |
| 功能标志评估 | 600/分钟 | 本地评估端点 |
| CRUD 端点 | 480/分钟，4,800/小时 | 创建、更新、删除操作 |
| 公共端点（捕获） | 无限制 | 事件捕获、标志决策 |

批量导出

对于大规模事件数据导出，请使用 PostHog 的批量导出功能而非 API。批量导出支持 S3、BigQuery、Snowflake 等目标。

## 故障排除

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | API 密钥无效 | 在设置中验证个人 API 密钥 |
| 400 Invalid project | 项目 ID 错误 | 检查 PostHog URL 中的项目 ID |
| 用户列表为空 | 没有已识别的用户 | 确保调用了 `posthog.identify()` |
| 属性缺失 | 属性未设置 | 验证客户端 SDK 中的 `$set` 调用 |
| 速率限制 429 | 请求过多 | 实施退避，检查速率限制头部 |

### 调试模式

```yaml
connectors:
  posthog:
    debug: true
    log_level: verbose
    log_queries: true
    log_sync: true
```

## 最佳实践

1. **识别用户** - 始终调用带邮箱的 `posthog.identify()` 以启用用户同步
2. **使用群组进行细分** - 利用 PostHog 的行为群组创建 Brevo 列表
3. **批量 API 请求** - 对大型数据集使用分页和批处理
4. **使用 HogQL 进行复杂查询** - 使用类 SQL 查询提取自定义分析数据
5. **设置批量导出** - 对于大数据量，优先使用批量导出而非 API 轮询
6. **过滤相关事件** - 只同步与营销相关的事件以减少噪音

## 安全

- **个人 API 密钥** - 范围化的 Bearer 令牌认证
- **项目令牌** - 仅用于客户端操作的公共令牌
- **仅 HTTPS** - 所有端点需要 TLS 加密
- **IP 白名单** - 适用于自托管实例
- **密钥范围** - 使用特定权限范围创建 API 密钥
- **GitHub 密钥扫描** - PostHog 与 GitHub 合作检测泄露的密钥

## 相关资源

- [Optimizely 连接器](https://tajo.io/zh-cn/docs/connectors/custom/optimizely)
- [Twilio Segment 连接器](https://tajo.io/zh-cn/docs/connectors/custom/segment)
- [Snowflake 连接器](https://tajo.io/zh-cn/docs/connectors/custom/snowflake)
- [PostHog API 文档](https://posthog.com/docs/api)