PostHog 连接器

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

概览

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

功能

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

前提条件

开始之前,请确保您已具备:

  1. PostHog 账户(云端或自托管)
  2. 来自 PostHog 设置 的个人 API 密钥
  3. 来自项目设置 的项目 API 密钥(令牌)
  4. 具有 API 访问权限的 Brevo 账户
  5. 具有连接器权限的 Tajo 账户

认证

个人 API 密钥(私有端点)

Terminal window
# 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
// 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 密钥(令牌)。

配置

基础设置

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_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/ePOST捕获事件(公共)
{host}/decide/?v=3POST功能标志决策(公共)

代码示例

初始化连接器

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 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 列表

// 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 查询进行分析

// 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 UnauthorizedAPI 密钥无效在设置中验证个人 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

最佳实践

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

安全

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

相关资源

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
AI 助手

你好!关于文档有任何问题都可以问我。