Коннектор Meta Ads
Подключите Meta Ads (Facebook и Instagram) к Brevo через Tajo для синхронизации Custom Audiences, импорта событий конверсий через Conversions API и связывания платной рекламы в социальных сетях с lifecycle-маркетинговой автоматизацией.
Обзор
| Свойство | Значение |
|---|---|
| Платформа | Meta Ads (Facebook, Instagram, Messenger, WhatsApp) |
| Категория | Marketing |
| Сложность настройки | Расширенная |
| Официальная интеграция | Нет |
| Синхронизируемые данные | Аудитории, конверсии, кампании, лиды |
| Доступных скиллов | 8 |
| Версия API | v25.0 (Graph API) |
Возможности
- Синхронизация Custom Audience, загрузка списков контактов Brevo как Custom Audiences в Meta
- Conversions API (CAPI), отправка серверных событий конверсий для точной атрибуции
- Синхронизация лид-форм, импорт заявок из Facebook Lead Ads непосредственно в контакты Brevo
- Аналитика кампаний, получение метрик эффективности рекламы в дашборды Tajo
- Похожие аудитории, создание Lookalike Audiences из синхронизированных сегментов Brevo
- Синхронизация каталога, синхронизация каталогов товаров для рекламы динамических товаров
- Мультиплатформенность, одна интеграция охватывает рекламу в Facebook, Instagram, Messenger и WhatsApp
Предварительные требования
Прежде чем начать, убедитесь, что у вас есть:
- Аккаунт Meta Business Manager
- Приложение Facebook с доступом к Marketing API
- System User с необходимыми разрешениями
- Access Token с разрешениями
ads_managementиads_read - Аккаунт Brevo с доступом к API
- Аккаунт Tajo с API-учётными данными
Аутентификация
Токен System User
Meta рекомендует использовать токены System User для серверных интеграций. Эти токены не истекают.
# Необходимые разрешения для System Userads_managementads_readbusiness_managementleads_retrievalpages_read_engagementcatalog_managementАутентификация на уровне приложения
curl -G "https://graph.facebook.com/v25.0/act_AD_ACCOUNT_ID/campaigns" \ -d "access_token=SYSTEM_USER_ACCESS_TOKEN" \ -d "fields=name,status,objective"Конфигурация
Базовая настройка
connectors: meta_ads: enabled: true app_id: "your-facebook-app-id" app_secret: "your-facebook-app-secret" access_token: "your-system-user-access-token" ad_account_id: "act_123456789" business_id: "987654321" pixel_id: "111222333444"
# Параметры синхронизации данных sync: custom_audiences: true conversions_api: true lead_forms: true campaign_insights: true
# Версия API api_version: "v25.0"Конфигурация Custom Audience
Синхронизация списков Brevo с Custom Audiences в Meta:
custom_audiences: enabled: true lists: - brevo_list_id: 5 audience_name: "All Customers" subtype: "CUSTOM" - brevo_list_id: 6 audience_name: "High LTV Customers" subtype: "CUSTOM" - brevo_list_id: 7 audience_name: "Recent Purchasers" subtype: "CUSTOM"
# Поля для совпадения match_keys: - EMAIL - PHONE - FN # Имя - LN # Фамилия - CT # Город - ST # Штат/регион - ZIP - COUNTRY
schedule: "daily" sync_mode: "mirror"Конфигурация Conversions API
conversions_api: enabled: true pixel_id: "111222333444" test_event_code: "" # Установите для тестирования, очистите для продакшна
events: - brevo_event: "order_completed" meta_event: "Purchase" value_field: "revenue" currency_field: "currency" - brevo_event: "cart_updated" meta_event: "AddToCart" - brevo_event: "customer_created" meta_event: "Lead" - brevo_event: "page_viewed" meta_event: "ViewContent"Эндпоинты API
| Метод | Эндпоинт | Описание |
|---|---|---|
POST | /v25.0/act_{id}/customaudiences | Создание Custom Audience |
POST | /v25.0/{audience_id}/users | Добавление пользователей в Custom Audience |
DELETE | /v25.0/{audience_id}/users | Удаление пользователей из Custom Audience |
POST | /v25.0/{pixel_id}/events | Отправка событий Conversions API |
GET | /v25.0/act_{id}/campaigns | Список кампаний |
GET | /v25.0/act_{id}/insights | Аналитика кампаний |
GET | /v25.0/{form_id}/leads | Получение заявок из лид-форм |
POST | /v25.0/act_{id}/adcreatives | Создание рекламных креативов |
GET | /v25.0/{catalog_id}/products | Список товаров каталога |
Примеры кода
Инициализация коннектора Meta Ads
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Подключение аккаунта Meta Adsawait tajo.connectors.connect('meta-ads', { appId: process.env.META_APP_ID, appSecret: process.env.META_APP_SECRET, accessToken: process.env.META_ACCESS_TOKEN, adAccountId: 'act_123456789', pixelId: '111222333444'});Отправка событий через Conversions API
// Отправка события покупки через Conversions APIconst response = await fetch( `https://graph.facebook.com/v25.0/${PIXEL_ID}/events`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ data: [{ event_name: 'Purchase', event_time: Math.floor(Date.now() / 1000), action_source: 'website', user_data: { ph: [hashSHA256('+15551234567')], fn: [hashSHA256('jane')], ln: [hashSHA256('kim')], client_ip_address: '192.168.1.1', client_user_agent: 'Mozilla/5.0...', fbc: 'fb.1.1234567890.AbCdEfG', // Click ID fbp: 'fb.1.1234567890.987654321' // Browser ID }, custom_data: { value: 89.99, currency: 'USD', content_ids: ['SKU-001'], content_type: 'product' } }], access_token: process.env.META_ACCESS_TOKEN }) });Синхронизация Custom Audience из списка Brevo
// Загрузка списка контактов Brevo как Custom Audience в Metaawait tajo.connectors.syncAudience('meta-ads', { brevoListId: 5, audienceName: 'High Value Customers', matchKeys: ['EMAIL', 'PHONE', 'FN', 'LN'], syncMode: 'mirror'});Получение аналитики кампаний
// Получение метрик эффективности кампанийconst insights = await tajo.connectors.query('meta-ads', { resource: 'campaigns', fields: ['campaign_name', 'impressions', 'clicks', 'spend', 'actions', 'cost_per_action_type'], dateRange: { since: '2024-01-01', until: '2024-01-31' }, level: 'campaign'});Ограничения скорости
| Ресурс | Лимит | Детали |
|---|---|---|
| Marketing API | По уровням | Зависит от уровня доступа приложения и расходов |
| Загрузки Custom Audience | 700 запросов/час | На рекламный аккаунт |
| Conversions API | 2 000 событий/сек | На пиксель |
| Insights API | 200 вызовов/час | На рекламный аккаунт |
| Получение лидов | 200 вызовов/час | На страницу |
| Пакетные запросы | 50 запросов/пакет | На batch-вызов |
Требуется верификация бизнеса
Полный доступ к Marketing API требует верификации бизнеса в Meta Business Manager. Неверифицированные приложения ограничены режимом разработки с сниженными лимитами скорости.
Устранение неполадок
| Проблема | Причина | Решение |
|---|---|---|
OAuthException | Токен истёк или недействителен | Перегенерируйте токен доступа System User |
| Низкий процент совпадений Custom Audience | Плохое качество данных | Хешируйте все PII с SHA-256, включайте несколько ключей совпадения |
| Конверсии не атрибутируются | Отсутствуют параметры fbc/fbp | Передавайте Facebook Click ID и Browser ID из cookies |
RATE_LIMIT_REACHED | Слишком много API-вызовов | Реализуйте экспоненциальную задержку, проверьте уровень API-доступа |
| Лид-формы не синхронизируются | Отсутствует разрешение leads_retrieval | Добавьте разрешение System User |
| События в тестовом режиме | test_event_code ещё установлен | Удалите тестовый код события для продакшна |
Лучшие практики
- Используйте токены System User, System Users предоставляют стабильные, не истекающие токены для серверных интеграций
- Хешируйте все PII, SHA-256-хешируйте все персональные данные перед отправкой в Meta
- Используйте и CAPI, и Pixel, применяйте и Conversions API, и Meta Pixel для дублирующего трекинга с дедупликацией
- Включайте event ID, устанавливайте
event_idдля событий CAPI и Pixel для дедупликации - Передавайте
fbcиfbp, включайте Facebook Click ID и Browser ID для максимальной атрибуции конверсий - Верифицируйте бизнес, пройдите верификацию бизнеса для полного доступа к API и более высоких лимитов
- Используйте
test_event_code, тестируйте события Conversions API в Events Manager перед запуском в продакшн
Безопасность
- Токены System User, неличные, бизнес-ограниченные токены аутентификации
- SHA-256-хеширование, все PII хешируются перед передачей на серверы Meta
- App Secret Proof, опциональный дополнительный уровень защиты аутентификации
- Бизнес-ограничение, разрешения ограничены конкретными рекламными аккаунтами и страницами
- Соответствие Meta, соблюдение Meta Platform Terms и политик рекламы
- Условия обработки данных, Data Processing Terms Meta применяются для данных ЕС