Connettore PostHog

Collega PostHog a Brevo tramite Tajo per sincronizzare dati di product analytics, eventi di comportamento utente e appartenenza alle coorti, per campagne marketing data-driven e engagement cliente personalizzato.

Panoramica

ProprietàValore
PiattaformaPostHog
CategoriaProduct Analytics (Custom)
Complessità di setupMedia
Integrazione ufficialeNo
Dati sincronizzatiEventi, Persone, Feature Flag, Coorti
Metodo di autenticazionePersonal API Key / Project Token

Funzionalità

  • Sync eventi - Inoltra gli eventi analytics PostHog a Brevo per targeting comportamentale
  • Sync profili persona - Sincronizza le proprietà person di PostHog sugli attributi dei contatti Brevo
  • Segmentazione basata su coorti - Mappa le coorti PostHog sulle liste contatti Brevo
  • Sync feature flag - Segmenta i contatti in base ai feature flag abilitati
  • Dati funnel - Usa i dati di conversion funnel per re-engagement mirato
  • Metadati session replay - Arricchisci i contatti con metriche di engagement delle sessioni

Prerequisiti

Prima di iniziare, assicurati di avere:

  1. Un account PostHog (Cloud o self-hosted)
  2. Una Personal API Key da PostHog Settings
  3. La tua Project API Key (token) da Project Settings
  4. Un account Brevo con accesso API
  5. Un account Tajo con permessi sui connettori

Autenticazione

Personal API Key (endpoint privati)

Terminal window
# Genera su 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 # oppure https://eu.posthog.com
export TAJO_API_KEY=your_tajo_api_key
export BREVO_API_KEY=your_brevo_api_key
// Gli endpoint API privati usano autenticazione Bearer
const headers = {
'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`,
'Content-Type': 'application/json'
};
// Gli endpoint pubblici usano il project token
const publicHeaders = {
'Content-Type': 'application/json'
};
// Il token viene passato nel body della richiesta per gli endpoint pubblici

Sicurezza dell'API key

Le Personal API key forniscono accesso completo all’account. Non esporle mai in codice client-side. Usa la Project API Key (token) per gli endpoint pubblici come cattura eventi e valutazione feature flag.

Configurazione

Setup di base

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 * * *" # Ogni 3 ore
event_filters:
- "$pageview"
- "purchase_completed"
- "signup_completed"
- "feature_used"
lists:
all_users: 25
active_users: 26
power_users: 27

Mapping dei campi

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

Endpoint API

EndpointMetodoDescrizione
{host}/api/projects/{id}/persons/GETElenca le persone
{host}/api/projects/{id}/events/GETElenca gli eventi
{host}/api/projects/{id}/cohorts/GETElenca le coorti
{host}/api/projects/{id}/feature_flags/GETElenca i feature flag
{host}/api/projects/{id}/feature_flags/evaluation/POSTValuta i flag
{host}/api/projects/{id}/insights/GETElenca gli insight salvati
{host}/api/projects/{id}/query/POSTEsegui query HogQL
{host}/i/v0/ePOSTCattura eventi (pubblico)
{host}/decide/?v=3POSTDecisioni feature flag (pubblico)

Esempi di codice

Inizializzare il connettore

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'
});

Sincronizzare le persone su Brevo

// Paginazione sulle persone PostHog
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;
}

Sincronizzare le coorti come liste Brevo

// Recupera le coorti PostHog e sincronizza i membri sulle liste Brevo
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) {
// Recupera le persone in questa coorte
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
}
});
}
}
}

Eseguire query HogQL per analytics

// Usa HogQL per interrogare i dati di analytics
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]
}
});
}

Limiti di rate

Categoria endpointLimiteNote
Endpoint analytics240/min, 1.200/oraGET persons, events, insights
Endpoint query2.400/oraHogQL e query personalizzate
Valutazione feature flag600/minEndpoint di valutazione locale
Endpoint CRUD480/min, 4.800/oraOperazioni di create, update, delete
Endpoint pubblici (capture)IllimitatoCattura eventi, decisioni flag

Batch Export

Per esportazioni di dati evento su larga scala, usa la funzione batch exports di PostHog invece dell’API. I batch exports supportano S3, BigQuery, Snowflake e altre destinazioni.

Risoluzione dei problemi

ProblemaCausaSoluzione
401 UnauthorizedAPI key non validaVerifica la Personal API Key nelle impostazioni
400 Invalid projectProject ID erratoControlla il project ID nell’URL di PostHog
Elenco persone vuotoNessun utente identificatoAssicurati che posthog.identify() venga chiamato
Proprietà mancantiProprietà non impostateVerifica le chiamate $set nell’SDK client
Rate limit 429Troppe richiesteImplementa backoff, controlla gli header del rate limit

Modalità debug

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

Best practice

  1. Identifica gli utenti - Chiama sempre posthog.identify() con l’email per abilitare il sync delle persone
  2. Usa le coorti per la segmentazione - Sfrutta le coorti comportamentali di PostHog per le liste Brevo
  3. Raggruppa le richieste API - Usa paginazione ed elaborazione batch per dataset grandi
  4. Usa HogQL per query complesse - Estrai analytics custom con query SQL-like
  5. Configura batch exports - Per grandi volumi di dati, preferisci i batch exports al polling API
  6. Filtra eventi rilevanti - Sincronizza solo gli eventi rilevanti per il marketing per ridurre il rumore

Sicurezza

  • Personal API Key - Autenticazione Bearer token con scope
  • Project token - Token pubblico solo per operazioni client-side
  • Solo HTTPS - Tutti gli endpoint richiedono cifratura TLS
  • IP allowlisting - Disponibile per istanze self-hosted
  • Scoping delle chiavi - Crea API key con scope di permessi specifici
  • GitHub secret scanning - PostHog collabora con GitHub per il rilevamento di chiavi trapelate

Risorse correlate

Subscribe to updates

developer-docs

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

auto-detect
Assistente AI

Ciao! Chiedimi qualsiasi cosa sulla documentazione.