PostHog 连接器
通过 Tajo 将 PostHog 连接到 Brevo,同步产品分析数据、用户行为事件和群组成员资格,打造数据驱动的营销活动和个性化客户互动。
概览
| 属性 | 值 |
|---|---|
| 平台 | PostHog |
| 类别 | 产品分析(自定义) |
| 设置复杂度 | 中等 |
| 官方集成 | 否 |
| 同步数据 | 事件、用户、功能标志、群组 |
| 认证方式 | 个人 API 密钥 / 项目令牌 |
功能
- 事件同步 - 将 PostHog 分析事件转发到 Brevo 进行行为定向
- 用户档案同步 - 将 PostHog 用户属性同步到 Brevo 联系人属性
- 基于群组的细分 - 将 PostHog 群组映射到 Brevo 联系人列表
- 功能标志同步 - 按已启用的功能标志细分联系人
- 漏斗数据 - 使用转化漏斗数据进行精准重新参与
- 会话回放元数据 - 用会话参与度指标丰富联系人信息
前提条件
开始之前,请确保您已具备:
- PostHog 账户(云端或自托管)
- 来自 PostHog 设置 的个人 API 密钥
- 来自项目设置 的项目 API 密钥(令牌)
- 具有 API 访问权限的 Brevo 账户
- 具有连接器权限的 Tajo 账户
认证
个人 API 密钥(私有端点)
# Generate at https://app.posthog.com/settings/user-api-keysexport POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_keyexport POSTHOG_PROJECT_TOKEN=phc_your_project_tokenexport POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.comexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_key// Private API endpoints use Bearer authenticationconst headers = { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json'};
// Public endpoints use the project tokenconst publicHeaders = { 'Content-Type': 'application/json'};// Token is passed in the request body for public endpointsAPI 密钥安全
个人 API 密钥提供完整账户访问权限。切勿在客户端代码中暴露。公共端点(如事件捕获和功能标志评估)使用项目 API 密钥(令牌)。
配置
基础设置
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字段映射
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_COHORTSAPI 端点
| 端点 | 方法 | 描述 |
|---|---|---|
{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 | 功能标志决策(公共) |
代码示例
初始化连接器
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
// Paginate through PostHog personslet 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 列表
// Get PostHog cohorts and sync members to Brevo listsconst 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 查询进行分析
// Use HogQL to query analytics dataconst 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 | 请求过多 | 实施退避,检查速率限制头部 |
调试模式
connectors: posthog: debug: true log_level: verbose log_queries: true log_sync: true最佳实践
- 识别用户 - 始终调用带邮箱的
posthog.identify()以启用用户同步 - 使用群组进行细分 - 利用 PostHog 的行为群组创建 Brevo 列表
- 批量 API 请求 - 对大型数据集使用分页和批处理
- 使用 HogQL 进行复杂查询 - 使用类 SQL 查询提取自定义分析数据
- 设置批量导出 - 对于大数据量,优先使用批量导出而非 API 轮询
- 过滤相关事件 - 只同步与营销相关的事件以减少噪音
安全
- 个人 API 密钥 - 范围化的 Bearer 令牌认证
- 项目令牌 - 仅用于客户端操作的公共令牌
- 仅 HTTPS - 所有端点需要 TLS 加密
- IP 白名单 - 适用于自托管实例
- 密钥范围 - 使用特定权限范围创建 API 密钥
- GitHub 密钥扫描 - PostHog 与 GitHub 合作检测泄露的密钥