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 |
|---|---|
| Piattaforma | PostHog |
| Categoria | Product Analytics (Custom) |
| Complessità di setup | Media |
| Integrazione ufficiale | No |
| Dati sincronizzati | Eventi, Persone, Feature Flag, Coorti |
| Metodo di autenticazione | Personal 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:
- Un account PostHog (Cloud o self-hosted)
- Una Personal API Key da PostHog Settings
- La tua Project API Key (token) da Project Settings
- Un account Brevo con accesso API
- Un account Tajo con permessi sui connettori
Autenticazione
Personal API Key (endpoint privati)
# Genera su 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 # oppure https://eu.posthog.comexport TAJO_API_KEY=your_tajo_api_keyexport BREVO_API_KEY=your_brevo_api_key// Gli endpoint API privati usano autenticazione Bearerconst headers = { 'Authorization': `Bearer ${process.env.POSTHOG_PERSONAL_API_KEY}`, 'Content-Type': 'application/json'};
// Gli endpoint pubblici usano il project tokenconst publicHeaders = { 'Content-Type': 'application/json'};// Il token viene passato nel body della richiesta per gli endpoint pubbliciSicurezza 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: 27Mapping 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_COHORTSEndpoint API
| Endpoint | Metodo | Descrizione |
|---|---|---|
{host}/api/projects/{id}/persons/ | GET | Elenca le persone |
{host}/api/projects/{id}/events/ | GET | Elenca gli eventi |
{host}/api/projects/{id}/cohorts/ | GET | Elenca le coorti |
{host}/api/projects/{id}/feature_flags/ | GET | Elenca i feature flag |
{host}/api/projects/{id}/feature_flags/evaluation/ | POST | Valuta i flag |
{host}/api/projects/{id}/insights/ | GET | Elenca gli insight salvati |
{host}/api/projects/{id}/query/ | POST | Esegui query HogQL |
{host}/i/v0/e | POST | Cattura eventi (pubblico) |
{host}/decide/?v=3 | POST | Decisioni 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 PostHoglet 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 Brevoconst 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 analyticsconst 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 endpoint | Limite | Note |
|---|---|---|
| Endpoint analytics | 240/min, 1.200/ora | GET persons, events, insights |
| Endpoint query | 2.400/ora | HogQL e query personalizzate |
| Valutazione feature flag | 600/min | Endpoint di valutazione locale |
| Endpoint CRUD | 480/min, 4.800/ora | Operazioni di create, update, delete |
| Endpoint pubblici (capture) | Illimitato | Cattura 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
| Problema | Causa | Soluzione |
|---|---|---|
| 401 Unauthorized | API key non valida | Verifica la Personal API Key nelle impostazioni |
| 400 Invalid project | Project ID errato | Controlla il project ID nell’URL di PostHog |
| Elenco persone vuoto | Nessun utente identificato | Assicurati che posthog.identify() venga chiamato |
| Proprietà mancanti | Proprietà non impostate | Verifica le chiamate $set nell’SDK client |
| Rate limit 429 | Troppe richieste | Implementa backoff, controlla gli header del rate limit |
Modalità debug
connectors: posthog: debug: true log_level: verbose log_queries: true log_sync: trueBest practice
- Identifica gli utenti - Chiama sempre
posthog.identify()con l’email per abilitare il sync delle persone - Usa le coorti per la segmentazione - Sfrutta le coorti comportamentali di PostHog per le liste Brevo
- Raggruppa le richieste API - Usa paginazione ed elaborazione batch per dataset grandi
- Usa HogQL per query complesse - Estrai analytics custom con query SQL-like
- Configura batch exports - Per grandi volumi di dati, preferisci i batch exports al polling API
- 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