موصل Meta Ads

اربط Meta Ads (Facebook وInstagram) بـ Brevo من خلال Tajo لمزامنة Custom Audiences، واستيراد أحداث التحويل عبر Conversions API، وربط الإعلانات الاجتماعية المدفوعة بأتمتة تسويق دورة الحياة.

نظرة عامة

الخاصيةالقيمة
المنصةMeta Ads (Facebook، Instagram، Messenger، WhatsApp)
الفئةالتسويق
تعقيد الإعدادمتقدم
تكامل رسميلا
البيانات المُزامَنةجماهير، تحويلات، حملات، عملاء محتملون
المهارات المتاحة8
إصدار APIv25.0 (Graph API)

الميزات

  • مزامنة Custom Audience - تحميل قوائم جهات اتصال Brevo كـ Meta Custom Audiences
  • Conversions API (CAPI) - إرسال أحداث التحويل من جانب الخادم لإسناد دقيق
  • مزامنة نماذج العملاء المحتملين - استيراد إرسالات Facebook Lead Ads مباشرة إلى جهات اتصال Brevo
  • رؤى الحملات - سحب مقاييس أداء الإعلانات إلى لوحات Tajo
  • جماهير Lookalike - إنشاء Lookalike Audiences من شرائح Brevo المُزامَنة
  • مزامنة الكتالوج - مزامنة كتالوجات المنتجات لإعلانات المنتجات الديناميكية
  • متعدد المنصات - تكامل واحد يغطي إعلانات Facebook وInstagram وMessenger وWhatsApp

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

  1. حساب Meta Business Manager
  2. تطبيق Facebook مع وصول Marketing API
  3. مستخدم نظام بصلاحيات مناسبة
  4. رمز Access Token بصلاحيات ads_management وads_read
  5. حساب Brevo مع وصول إلى API
  6. حساب Tajo مع بيانات اعتماد API

المصادقة

رمز Access Token لمستخدم النظام

توصي Meta باستخدام رموز مستخدم النظام للتكاملات من خادم إلى خادم. هذه الرموز لا تنتهي.

Terminal window
# Required permissions for System User
ads_management
ads_read
business_management
leads_retrieval
pages_read_engagement
catalog_management

المصادقة على مستوى التطبيق

Terminal window
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"
# Data sync options
sync:
custom_audiences: true
conversions_api: true
lead_forms: true
campaign_insights: true
# API version
api_version: "v25.0"

إعداد Custom Audience

مزامنة قوائم Brevo مع Meta Custom Audiences:

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"
# Matching fields
match_keys:
- EMAIL
- PHONE
- FN # First name
- LN # Last name
- CT # City
- ST # State
- ZIP
- COUNTRY
schedule: "daily"
sync_mode: "mirror"

إعداد Conversions API

conversions_api:
enabled: true
pixel_id: "111222333444"
test_event_code: "" # Set for testing, clear for production
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"

نقاط نهاية واجهة البرمجة

الطريقةنقطة النهايةالوصف
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
});
// Connect Meta Ads account
await 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 API
const 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: {
em: [hashSHA256('[email protected]')],
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 كـ Meta Custom Audience
await 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 Audience700 طلب/ساعةلكل حساب إعلاني
Conversions API2,000 حدث/ثانيةلكل بكسل
Insights API200 استدعاء/ساعةلكل حساب إعلاني
استرجاع العملاء المحتملين200 استدعاء/ساعةلكل صفحة
الطلبات المجمّعة50 طلبًا/دفعةلكل استدعاء دفعة

التحقق من الأعمال مطلوب

يتطلب الوصول الكامل إلى Marketing API التحقق من الأعمال في Meta Business Manager. تقتصر التطبيقات غير المُوثَّقة على وضع التطوير بحدود معدل مقيدة.

استكشاف الأخطاء وإصلاحها

المشكلةالسببالحل
OAuthExceptionالرمز منتهي أو غير صالحأعد توليد رمز وصول مستخدم النظام
معدل مطابقة Custom Audience منخفضجودة بيانات ضعيفةقم بتجزئة جميع PII بـ SHA-256، ضمّن مفاتيح مطابقة متعددة
التحويلات غير مُسنَدةمعاملات fbc/fbp مفقودةمرّر Facebook Click ID وBrowser ID من ملفات تعريف الارتباط
RATE_LIMIT_REACHEDاستدعاءات API كثيرة جدًاطبّق التراجع الأُسّي، تحقق من مستوى وصول API
نماذج العملاء المحتملين لا تتزامنصلاحية leads_retrieval مفقودةأضف الصلاحية إلى مستخدم النظام
الأحداث في وضع الاختبارtest_event_code لا يزال مضبوطًاأزل رمز الحدث الاختباري للإنتاج

أفضل الممارسات

  1. استخدم رموز مستخدم النظام - توفر مستخدمات النظام رموزًا مستقرة وغير منتهية لتكاملات الخادم
  2. قم بتجزئة جميع PII - جزّأ جميع المعلومات الشخصية القابلة للتعريف بـ SHA-256 قبل الإرسال إلى Meta
  3. أرسل CAPI وPixel معًا - استخدم Conversions API وMeta Pixel معًا للتتبع المتكرر مع إزالة التكرار
  4. ضمّن معرّفات الأحداث - اضبط event_id على كل من أحداث CAPI وPixel لتمكين إزالة التكرار
  5. مرّر fbc وfbp - ضمّن Facebook Click ID وBrowser ID لأقصى إسناد للتحويلات
  6. وثّق أعمالك - أكمل التحقق من الأعمال للوصول الكامل إلى API وحدود معدل أعلى
  7. استخدم test_event_code - اختبر أحداث Conversions API في Events Manager قبل البث المباشر

الأمان

  • رموز مستخدم النظام - رموز مصادقة غير شخصية، مُقيَّدة بالأعمال
  • تجزئة SHA-256 - جميع PII مُجزَّأة قبل النقل إلى خوادم Meta
  • App Secret Proof - طبقة إضافية اختيارية من أمان المصادقة
  • تحديد نطاق الأعمال - الصلاحيات مقيدة بحسابات إعلانية وصفحات محددة
  • الامتثال لـ Meta - يخضع لشروط منصة Meta وسياسات الإعلانات
  • شروط معالجة البيانات - تُطبَّق شروط معالجة البيانات في Meta على بيانات EU

موارد ذات صلة

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

auto-detect
مساعد AI

مرحباً! اسألني أي شيء عن الوثائق.