Connettore Braze

Collega la tua piattaforma di engagement Braze a Brevo per profili cliente unificati, orchestrazione di campagne cross-channel e analytics di marketing consolidate.

Panoramica

Funzionalità

• Sync dei profili utente - Sincronizzazione bidirezionale degli attributi cliente tra Braze e Brevo
• Tracciamento eventi di campagna - Traccia aperture email, click, conversioni e disiscrizioni
• Dati flusso Canvas - Sincronizza i dati del journey delle campagne multi-step per una reportistica unificata
• Mirroring dei segmenti - Replica i segmenti Braze come liste Brevo per il targeting cross-platform
• Eventi push notification - Inoltra i dati di engagement push alle timeline dei contatti Brevo
• Sync del catalogo - Sincronizza i cataloghi prodotti per raccomandazioni personalizzate

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un account Braze con accesso API abilitato
2. Una chiave REST API Braze con i permessi appropriati
3. L’URL della tua istanza Braze (es. rest.iad-01.braze.com)
4. Un account Brevo con accesso API
5. Un account Tajo con un abbonamento attivo

Autenticazione

Braze utilizza l’autenticazione con chiave API. Ogni chiave API può essere assegnata a specifici endpoint.

Creazione di una chiave API

1. Accedi alla tua dashboard Braze
2. Vai in Settings > API Keys
3. Clicca su Create New API Key
4. Nominala “Tajo Integration”
5. Abilita i seguenti permessi:

users.track
users.export.ids
users.export.segment
campaigns.list
campaigns.data_series
canvas.list
canvas.data_series
segments.list
segments.data_series
email.status
subscription.status.set
catalogs.list_items

Connessione a Tajo

tajo connectors install braze \
  --api-key $BRAZE_API_KEY \
  --instance-url rest.iad-01.braze.com

Configurazione

Setup di base

connectors:
  braze:
    enabled: true
    instance_url: "rest.iad-01.braze.com"
    api_version: "v1"

    sync:
      users: true
      campaigns: true
      canvases: true
      segments: true
      events: true

    lists:
      engaged_users: 10
      dormant_users: 11

Mappatura dei campi

Mappa gli attributi utente Braze agli attributi di contatto Brevo:

field_mapping:
  # Standard fields
  external_id: BRAZE_ID
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # Engagement metrics
  total_revenue: TOTAL_REVENUE
  push_opted_in: PUSH_OPTIN
  email_subscribe: EMAIL_STATUS

  # Custom attributes
  loyalty_points: LOYALTY_POINTS
  last_app_version: APP_VERSION
  preferred_language: LANGUAGE

Endpoint API

Tajo si integra con i seguenti endpoint REST API di Braze:

Esempi di codice

Inizializza 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('braze', {
  apiKey: process.env.BRAZE_API_KEY,
  instanceUrl: 'rest.iad-01.braze.com'
});

Sincronizza i profili utente

// Sync Braze users to Brevo contacts
await tajo.connectors.sync('braze', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01',
  batchSize: 50
});

// Check sync status
const status = await tajo.connectors.status('braze');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T10:30:00Z',
//   usersCount: 45200,
//   campaignsTracked: 28,
//   eventsProcessed: 125000
// }

Traccia eventi personalizzati

// Forward Braze events to Brevo
await tajo.connectors.handleEvent('braze', {
  type: 'user.event',
  payload: {
    external_id: 'user_12345',
    name: 'product_viewed',
    properties: {
      product_id: 'SKU-789',
      category: 'electronics',
      price: 299.99
    }
  }
});

Esporta i dati di un segmento

// Export a Braze segment and create a Brevo list
const result = await tajo.connectors.exportSegment('braze', {
  segmentId: 'segment_abc123',
  targetList: 15,
  includeAttributes: ['email', 'first_name', 'last_name', 'total_revenue']
});

console.log(`Exported ${result.count} users to Brevo list 15`);

Limiti di velocità

Braze applica limiti di velocità in base al tuo piano e alla tua istanza:

L’endpoint /users/track ha un limite predefinito di 50.000 richieste al minuto. Tajo gestisce automaticamente la limitazione di velocità con backoff esponenziale.

Risoluzione dei problemi

Problemi comuni

Modalità debug

connectors:
  braze:
    debug: true
    log_level: verbose
    log_api_calls: true

Testa la connessione

tajo connectors test braze
# ✓ API connection successful
# ✓ User export accessible
# ✓ Campaign data readable
# ✓ Segment list accessible
# ✓ Event tracking operational

Best practice

1. Usa sync incrementali - Evita le esportazioni complete; sincronizza solo i record modificati dall’ultima sync
2. Aggiorna gli utenti in batch - Raggruppa le modifiche agli attributi per minimizzare le chiamate API
3. Limita lo scope delle chiavi API - Abilita solo i permessi necessari alla tua integrazione
4. Monitora i limiti di velocità - Imposta avvisi prima di raggiungere i limiti di velocità di Braze
5. Mappa gli ID esterni in modo coerente - Usa lo stesso identificatore tra Braze e Brevo
6. Testa prima in sandbox - Usa un workspace di test Braze prima del deploy in produzione

Sicurezza

• Autenticazione con chiave API - Chiavi API con scope e permessi granulari
• Solo HTTPS - Tutte le comunicazioni API cifrate via TLS 1.2+
• IP Allowlisting - Restrizione IP opzionale per l’accesso API in Braze
• Storage cifrato - Credenziali API cifrate a riposo in Tajo
• Audit logging - Tutte le chiamate API loggate per la revisione di compliance

Risorse correlate

• Connettore Customer.io
• Connettore Iterable
• Skill Customer Sync
• API Contatti Brevo