Skip to main content

Configuration Guide

Esta guía te ayudará a configurar nuevos sistemas y tenants para la integración con Facebook Ads.

Prerequisitos​

Antes de configurar un nuevo sistema, asegúrate de tener:

  1. Facebook Ad Account ID: El ID de la cuenta publicitaria (formato: act_XXXXXXXXX)
  2. Access Token: Token de acceso con permisos adecuados
  3. Tenant IDs: Lista de tenant IDs del CDP a incluir
  4. Acceso a Railway: Para configurar variables de entorno

Paso 1: Configurar Access Token​

Obtener Facebook Access Token​

  1. Ve a Facebook Graph API Explorer
  2. Selecciona tu aplicación
  3. Solicita permisos necesarios:
    • ads_management
    • ads_read
    • business_management
  4. Genera token de acceso
  5. Extiende el token a 60 días:
curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token" \
  -d "grant_type=fb_exchange_token" \
  -d "client_id={APP_ID}" \
  -d "client_secret={APP_SECRET}" \
  -d "fb_exchange_token={SHORT_LIVED_TOKEN}"

Configurar Token en Railway​

# Via Railway CLI
railway variables --set "FACEBOOK_ACCESS_TOKEN=EAAJs4xreU3IBPp7..."

# O via Railway Dashboard
# Settings > Variables > FACEBOOK_ACCESS_TOKEN

Paso 2: Insertar Configuración en Database​

Conectar a Database​

# Via Railway CLI
railway connect

# O via psql directo
psql "postgresql://postgres:PASSWORD@nozomi.proxy.rlwy.net:22425/railway"

Insertar Nueva Configuración​

-- Ejemplo: Configurar nuevo sistema "Store XYZ"
INSERT INTO cdp.facebook_configurations (
    system_name,
    ad_account_id,
    tenant_ids,
    is_active,
    schedule_hours
) VALUES (
    'storexyz_system',           -- Nombre único del sistema
    'act_1234567890',             -- Facebook Ad Account ID
    ARRAY[40, 41, 42],            -- Array de tenant IDs
    true,                         -- Activar inmediatamente
    48                            -- Sync cada 48 horas
);

Verificar Configuración​

-- Ver todas las configuraciones
SELECT
    system_name,
    ad_account_id,
    tenant_ids,
    is_active,
    schedule_hours,
    last_sync,
    next_sync,
    total_customers
FROM cdp.facebook_configurations
ORDER BY system_name;

Paso 3: Validar Tenants​

Verificar que los Tenants tienen datos​

-- Contar clientes por tenant
SELECT
    c.tenant_id,
    t.tenant_name,
    COUNT(DISTINCT c.id) as total_customers,
    COUNT(DISTINCT CASE WHEN c.email IS NOT NULL AND c.email != '' THEN c.id END) as customers_with_email,
    COUNT(DISTINCT CASE WHEN r.rfm_segment NOT IN ('Lost', 'Hibernating') THEN c.id END) as active_customers
FROM customers_master c
LEFT JOIN tenants t ON c.tenant_id = t.id
LEFT JOIN cdp_rfm_analysis r ON c.id = r.customer_id
WHERE c.tenant_id = ANY(ARRAY[40, 41, 42])  -- Tus tenant IDs
GROUP BY c.tenant_id, t.tenant_name
ORDER BY c.tenant_id;

Verificar Segmentos RFM​

-- Ver distribución de segmentos RFM por tenant
SELECT
    c.tenant_id,
    r.rfm_segment,
    COUNT(*) as customers,
    ROUND(AVG(r.monetary_score), 2) as avg_monetary
FROM customers_master c
INNER JOIN cdp_rfm_analysis r ON c.id = r.customer_id
WHERE c.tenant_id = ANY(ARRAY[40, 41, 42])
GROUP BY c.tenant_id, r.rfm_segment
ORDER BY c.tenant_id, customers DESC;

Paso 4: Test de Sincronización​

Ejecutar Test Manual​

# Conectar via Railway CLI
railway run

# Dentro del contenedor
python /app/scripts/force_facebook_sync_now.py --system storexyz_system

Monitorear Logs​

# Ver logs en tiempo real
railway logs --service facebook-automation

# Buscar errores específicos
railway logs --service facebook-automation | grep ERROR

Verificar Resultado en Database​

-- Ver resultado de última sincronización
SELECT
    system_name,
    last_sync,
    next_sync,
    total_customers,
    custom_audience_id,
    sync_status,
    error_log
FROM cdp.facebook_configurations
WHERE system_name = 'storexyz_system';

Paso 5: Verificar en Facebook​

Via Facebook Ads Manager​

  1. Ir a Facebook Ads Manager
  2. Seleccionar Ad Account
  3. Ir a Audiences (Herramientas > Audiencias)
  4. Buscar audiencia: CDP - StorexyzSystem - 2024-10
  5. Verificar:
    • Size: Número de usuarios agregados
    • Status: Ready/Processing
    • Last Update: Timestamp reciente

Via Facebook Graph API​

# Obtener información de Custom Audience
curl -X GET \
  "https://graph.facebook.com/v18.0/{CUSTOM_AUDIENCE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d "fields=id,name,approximate_count,delivery_status,time_created,time_updated"

Configuraciones Avanzadas​

Modificar Schedule​

-- Cambiar a sync cada 24 horas
UPDATE cdp.facebook_configurations
SET schedule_hours = 24
WHERE system_name = 'storexyz_system';

-- Cambiar a sync semanal (168 horas)
UPDATE cdp.facebook_configurations
SET schedule_hours = 168
WHERE system_name = 'storexyz_system';

Agregar/Remover Tenants​

-- Agregar nuevo tenant al sistema
UPDATE cdp.facebook_configurations
SET tenant_ids = array_append(tenant_ids, 43)
WHERE system_name = 'storexyz_system';

-- Remover tenant
UPDATE cdp.facebook_configurations
SET tenant_ids = array_remove(tenant_ids, 40)
WHERE system_name = 'storexyz_system';

-- Reemplazar completamente
UPDATE cdp.facebook_configurations
SET tenant_ids = ARRAY[40, 41, 42, 43, 44]
WHERE system_name = 'storexyz_system';

Pausar/Reactivar Sistema​

-- Pausar sincronización
UPDATE cdp.facebook_configurations
SET is_active = false
WHERE system_name = 'storexyz_system';

-- Reactivar
UPDATE cdp.facebook_configurations
SET is_active = true
WHERE system_name = 'storexyz_system';

Filtros de Audiencias Personalizados​

Modificar Query de Extracción​

Por defecto, el sistema extrae clientes activos (no Lost/Hibernating). Para personalizar:

# Editar en: nerdistan-worker/scripts/facebook_sync.py

# Ejemplo 1: Solo clientes VIP (Champions + Loyal)
def get_customers_for_system(tenant_ids: list):
    query = """
        SELECT DISTINCT
            c.email,
            c.phone,
            c.firstname,
            c.lastname
        FROM customers_master c
        INNER JOIN cdp_rfm_analysis r ON c.id = r.customer_id
        WHERE c.tenant_id = ANY(%s)
          AND c.email IS NOT NULL
          AND r.rfm_segment IN ('Champions', 'Loyal Customers')
        ORDER BY c.email
    """
    return execute_query(query, (tenant_ids,))

# Ejemplo 2: Clientes con CLV alto
def get_customers_for_system(tenant_ids: list):
    query = """
        SELECT DISTINCT
            c.email,
            c.phone,
            c.firstname,
            c.lastname
        FROM customers_master c
        INNER JOIN cdp_clv_analysis clv ON c.id = clv.customer_id
        WHERE c.tenant_id = ANY(%s)
          AND c.email IS NOT NULL
          AND clv.predicted_clv_1y > 1000
        ORDER BY c.email
    """
    return execute_query(query, (tenant_ids,))

# Ejemplo 3: Clientes con riesgo de churn
def get_customers_for_system(tenant_ids: list):
    query = """
        SELECT DISTINCT
            c.email,
            c.phone,
            c.firstname,
            c.lastname
        FROM customers_master c
        INNER JOIN cdp_churn_analysis ch ON c.id = ch.customer_id
        WHERE c.tenant_id = ANY(%s)
          AND c.email IS NOT NULL
          AND ch.churn_risk = 'High'
        ORDER BY c.email
    """
    return execute_query(query, (tenant_ids,))

Troubleshooting Común​

Error: "Invalid Ad Account ID"​

-- Verificar formato del Ad Account ID
SELECT
    system_name,
    ad_account_id,
    CASE
        WHEN ad_account_id LIKE 'act_%' THEN 'Formato correcto'
        ELSE 'INCORRECTO - debe empezar con act_'
    END as validation
FROM cdp.facebook_configurations;

-- Corregir formato
UPDATE cdp.facebook_configurations
SET ad_account_id = 'act_' || ad_account_id
WHERE ad_account_id NOT LIKE 'act_%';

Error: "No customers found"​

-- Diagnóstico de datos
SELECT
    'Total customers' as metric,
    COUNT(*) as value
FROM customers_master
WHERE tenant_id = ANY(ARRAY[40, 41, 42])

UNION ALL

SELECT
    'With email',
    COUNT(*)
FROM customers_master
WHERE tenant_id = ANY(ARRAY[40, 41, 42])
  AND email IS NOT NULL
  AND email != ''

UNION ALL

SELECT
    'Active (not Lost/Hibernating)',
    COUNT(*)
FROM customers_master c
INNER JOIN cdp_rfm_analysis r ON c.id = r.customer_id
WHERE c.tenant_id = ANY(ARRAY[40, 41, 42])
  AND r.rfm_segment NOT IN ('Lost', 'Hibernating');

Error: "Access Token Expired"​

# Verificar expiración del token
curl -X GET \
  "https://graph.facebook.com/v18.0/debug_token" \
  -d "input_token={ACCESS_TOKEN}" \
  -d "access_token={APP_ACCESS_TOKEN}"

# Extender token (ver Paso 1)

Checklist de Configuración​

  • ✅ Facebook Ad Account ID obtenido
  • ✅ Access Token generado y extendido (60 días)
  • ✅ Token configurado en Railway variables
  • ✅ Configuración insertada en cdp.facebook_configurations
  • ✅ Tenants validados (tienen customers con email)
  • ✅ Test de sincronización ejecutado
  • ✅ Logs verificados (sin errores)
  • ✅ Custom Audience creada en Facebook
  • ✅ Size de audiencia validado
  • ✅ Schedule configurado correctamente
  • ✅ Sistema activado (is_active = true)

Próximos Pasos​

Soporte​

Para problemas o preguntas:

  • Logs: railway logs --service facebook-automation
  • Database: cdp.facebook_configurations table
  • Documentation: Esta guía y Architecture