Connettore Mixpanel

Collega Mixpanel a Brevo tramite Tajo per unire product analytics e marketing automation. Sincronizza profili utente, eventi comportamentali e coorti per creare campagne data-driven basate sull’utilizzo reale del prodotto.

Panoramica

Funzionalità

• Ingestione eventi - Importa eventi track tramite l’Ingestion API di Mixpanel nei flussi Brevo
• Sync profilo utente - Mappa le proprietà di profilo utente Mixpanel sugli attributi dei contatti Brevo
• Export coorti - Sincronizza le coorti Mixpanel su liste contatti Brevo per campagne mirate
• Group analytics - Sincronizza dati a livello di gruppo per il marketing account-based B2B
• Identity management - Sfrutta l’identity merge di Mixpanel per profili cliente unificati
• Query JQL - Esegui query JQL personalizzate per estrarre dataset specifici per Brevo
• Lookup table - Sincronizza dati di arricchimento dalle lookup table di Mixpanel

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Mixpanel con un progetto creato
2. Il tuo Project Token Mixpanel per il tracking client-side
3. Un Service Account con i permessi appropriati per l’accesso API server-side
4. Un account Brevo con accesso API
5. Un account Tajo con credenziali API

Autenticazione

Service Account (consigliato)

Mixpanel consiglia l’uso dei Service Account per l’autenticazione API. I Service Account usano HTTP Basic Auth con username (username del service account) e password (secret del service account).

# Autenticazione Service Account
curl https://mixpanel.com/api/app/me \
  -u "SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET"

Project Token

Il Project Token viene usato per il tracking eventi client-side ed è sicuro da includere nel codice client:

// Inizializzazione client-side
mixpanel.init("YOUR_PROJECT_TOKEN");

OAuth (per integrazioni partner)

Per integrazioni app che accedono a più progetti:

curl https://mixpanel.com/api/2.0/engage \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Configurazione

Setup di base

connectors:
  mixpanel:
    enabled: true
    project_token: "your-project-token"
    service_account:
      username: "your-service-account-username"
      secret: "your-service-account-secret"
    project_id: "12345"
    data_residency: "US"  # oppure "EU"

    # Opzioni di sync dei dati
    sync:
      events: true
      profiles: true
      cohorts: true
      groups: false

    # Assegnazione liste Brevo
    lists:
      all_users: 15
      engaged_users: 16
      at_risk: 17

Mapping degli eventi

Mappa gli eventi Mixpanel sui tipi di evento Brevo:

event_mapping:
  # Evento Mixpanel -> evento Brevo
  "Purchase": "order_completed"
  "Sign Up": "customer_created"
  "Add to Cart": "cart_updated"
  "Page View": "page_viewed"
  "$experiment_started": "experiment_started"

  # Eventi custom
  "Feature Activated": "feature_used"
  "Subscription Renewed": "subscription_renewed"

Mapping delle proprietà del profilo

Mappa le proprietà utente Mixpanel sugli attributi dei contatti Brevo:

property_mapping:
  $email: email
  $first_name: FIRSTNAME
  $last_name: LASTNAME
  $phone: SMS
  $city: CITY
  $region: REGION
  $country_code: COUNTRY
  plan: PLAN_TYPE
  company: COMPANY
  signup_date: SIGNUP_DATE
  total_revenue: LTV

Endpoint API

Esempi di codice

Inizializzare il connettore Mixpanel

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

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

// Collega un progetto Mixpanel
await tajo.connectors.connect('mixpanel', {
  projectToken: process.env.MIXPANEL_TOKEN,
  serviceAccountUser: process.env.MIXPANEL_SA_USER,
  serviceAccountSecret: process.env.MIXPANEL_SA_SECRET,
  projectId: process.env.MIXPANEL_PROJECT_ID
});

Importare eventi tramite Ingestion API

// Importa eventi su Mixpanel (inoltrati automaticamente a Brevo)
const response = await fetch('https://api.mixpanel.com/import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa(
      `${process.env.MIXPANEL_SA_USER}:${process.env.MIXPANEL_SA_SECRET}`
    )
  },
  body: JSON.stringify([
    {
      event: "Purchase",
      properties: {
        distinct_id: "user_123",
        $insert_id: "evt_abc123",
        time: Math.floor(Date.now() / 1000),
        revenue: 89.99,
        product_id: "SKU-001",
        product_name: "Widget Pro"
      }
    }
  ])
});

// Risposta attesa: { "code": 200, "status": "OK", "num_records_imported": 1 }

Sincronizzare una coorte su Brevo

// Esporta una coorte Mixpanel e sincronizzala su una lista Brevo
const cohort = await tajo.connectors.syncCohort('mixpanel', {
  cohortId: 12345,
  targetList: 16,
  syncMode: 'mirror'
});

console.log(cohort);
// {
//   cohortName: "Engaged Users (Last 7 Days)",
//   membersCount: 3200,
//   syncedToBrevo: 3200,
//   listId: 16
// }

Impostare proprietà del profilo utente

// Imposta proprietà utente tramite la Engage API
const response = await fetch('https://api.mixpanel.com/engage#$set', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify([{
    $token: process.env.MIXPANEL_TOKEN,
    $distinct_id: "user_123",
    $set: {
      $email: "[email protected]",
      $first_name: "Jane",
      $last_name: "Kim",
      plan: "premium",
      total_orders: 12,
      lifetime_value: 1250.00
    }
  }])
});

Limiti di rate

Risoluzione dei problemi

Best practice

1. Usa i Service Account - Preferisci i Service Account al Project Secret per l’autenticazione server-side
2. Includi $insert_id - Imposta sempre un insert ID univoco per la deduplicazione eventi
3. Raggruppa gli update di profilo in batch - Invia fino a 2.000 update di profilo per richiesta per efficienza
4. Usa gli endpoint EU - Per la data residency EU, usa api-eu.mixpanel.com per tutte le chiamate API
5. Sincronizza le coorti secondo schedule - Imposta sync di coorte giornaliero o settimanale anziché polling continuo
6. Mappa le proprietà riservate - Usa le proprietà riservate di Mixpanel ($email, $first_name) per i dati di profilo
7. Monitora l’ingestione - Usa la pagina Events di Mixpanel per verificare che gli eventi vengano ricevuti correttamente

Sicurezza

• Solo HTTPS - Tutte le comunicazioni API richiedono cifratura TLS
• Isolamento Service Account - Accesso limitato per progetto con permessi basati su ruolo
• Deduplicazione eventi - Dedup integrata tramite $insert_id previene problemi di integrità dati
• SOC 2 Type II - Mixpanel è certificata SOC 2 Type II
• GDPR/CCPA - Supporta la cancellazione dei dati utente tramite GDPR API
• Residenza dati EU - Data center EU disponibile per la compliance europea

Risorse correlate

• Connettore Segment
• Connettore Amplitude
• Skill Customer Sync
• Brevo Events API