Conector de Braze

Conecta tu plataforma de engagement Braze con Brevo para unificar perfiles de cliente, orquestar campañas multicanal y consolidar la analítica de marketing.

Resumen

Funcionalidades

• Sincronización de perfiles de usuario - Sincronización bidireccional de atributos de cliente entre Braze y Brevo
• Seguimiento de eventos de campaña - Registra aperturas, clics, conversiones y bajas de email
• Datos de flujos Canvas - Sincroniza los datos de recorrido de campañas multi-paso para un reporting unificado
• Replicación de segmentos - Replica los segmentos de Braze como listas de Brevo para segmentación multiplataforma
• Eventos de notificaciones push - Reenvía los datos de engagement de push al timeline del contacto en Brevo
• Sincronización de catálogos - Sincroniza los catálogos de productos para recomendaciones personalizadas

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Braze con acceso a la API activado
2. Una clave API REST de Braze con los permisos adecuados
3. La URL de tu instancia de Braze (por ejemplo, rest.iad-01.braze.com)
4. Una cuenta de Brevo con acceso a la API
5. Una cuenta de Tajo con suscripción activa

Autenticación

Braze usa autenticación con clave API. Cada clave puede limitarse a endpoints concretos.

Crear una clave API

1. Inicia sesión en el panel de Braze
2. Ve a Settings > API Keys
3. Haz clic en Create New API Key
4. Ponle el nombre “Tajo Integration”
5. Activa los siguientes permisos:

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

Conectar con Tajo

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

Configuración

Configuración básica

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

Asignación de campos

Asocia los atributos de usuario de Braze con los atributos de contacto de 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

Endpoints de la API

Tajo se integra con los siguientes endpoints de la REST API de Braze:

Ejemplos de código

Inicializar el conector

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

Sincronizar perfiles de usuario

// 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
// }

Registrar eventos personalizados

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

Exportar datos de 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`);

Límites de velocidad

Braze aplica límites de velocidad según tu plan e instancia:

El endpoint /users/track tiene un límite por defecto de 50.000 peticiones por minuto. Tajo gestiona automáticamente los límites de velocidad con backoff exponencial.

Resolución de problemas

Problemas habituales

Modo depuración

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

Probar la conexión

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

Buenas prácticas

1. Usa sincronizaciones incrementales - Evita exportaciones completas; sincroniza solo los registros modificados desde la última sincronización
2. Agrupa las actualizaciones de usuario - Agrupa los cambios de atributos para minimizar las llamadas a la API
3. Limita el alcance de las claves API - Activa solo los permisos que realmente necesita tu integración
4. Monitoriza los límites de velocidad - Configura alertas antes de alcanzar los límites de Braze
5. Asocia los IDs externos de forma coherente - Usa el mismo identificador en Braze y en Brevo
6. Prueba primero en sandbox - Utiliza un workspace de prueba de Braze antes del despliegue en producción

Seguridad

• Autenticación con clave API - Claves API con permisos granulares
• Solo HTTPS - Toda la comunicación con la API se cifra vía TLS 1.2+
• Lista blanca de IPs - Restricción opcional por IP para el acceso a la API en Braze
• Almacenamiento cifrado - Credenciales de API cifradas en reposo en Tajo
• Registro de auditoría - Todas las llamadas a la API se registran para revisión de cumplimiento

Recursos relacionados

• Conector de Customer.io
• Conector de Iterable
• Skill de sincronización de clientes
• API de contactos de Brevo