موصل Meta Ads
اربط Meta Ads (Facebook وInstagram) بـ Brevo من خلال Tajo لمزامنة Custom Audiences، واستيراد أحداث التحويل عبر Conversions API، وربط الإعلانات الاجتماعية المدفوعة بأتمتة تسويق دورة الحياة.
نظرة عامة
| الخاصية | القيمة |
|---|---|
| المنصة | Meta Ads (Facebook، Instagram، Messenger، WhatsApp) |
| الفئة | التسويق |
| تعقيد الإعداد | متقدم |
| تكامل رسمي | لا |
| البيانات المُزامَنة | جماهير، تحويلات، حملات، عملاء محتملون |
| المهارات المتاحة | 8 |
| إصدار API | v25.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
المتطلبات الأساسية
قبل البدء، تأكد من توفر ما يلي:
- حساب Meta Business Manager
- تطبيق Facebook مع وصول Marketing API
- مستخدم نظام بصلاحيات مناسبة
- رمز Access Token بصلاحيات
ads_managementوads_read - حساب Brevo مع وصول إلى API
- حساب Tajo مع بيانات اعتماد API
المصادقة
رمز Access Token لمستخدم النظام
توصي Meta باستخدام رموز مستخدم النظام للتكاملات من خادم إلى خادم. هذه الرموز لا تنتهي.
# Required permissions for 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"
# 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 accountawait 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 كـ Meta Custom Audienceawait 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 طلبًا/دفعة | لكل استدعاء دفعة |
التحقق من الأعمال مطلوب
يتطلب الوصول الكامل إلى 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 لا يزال مضبوطًا | أزل رمز الحدث الاختباري للإنتاج |
أفضل الممارسات
- استخدم رموز مستخدم النظام - توفر مستخدمات النظام رموزًا مستقرة وغير منتهية لتكاملات الخادم
- قم بتجزئة جميع PII - جزّأ جميع المعلومات الشخصية القابلة للتعريف بـ SHA-256 قبل الإرسال إلى Meta
- أرسل CAPI وPixel معًا - استخدم Conversions API وMeta Pixel معًا للتتبع المتكرر مع إزالة التكرار
- ضمّن معرّفات الأحداث - اضبط
event_idعلى كل من أحداث CAPI وPixel لتمكين إزالة التكرار - مرّر
fbcوfbp- ضمّن Facebook Click ID وBrowser ID لأقصى إسناد للتحويلات - وثّق أعمالك - أكمل التحقق من الأعمال للوصول الكامل إلى API وحدود معدل أعلى
- استخدم
test_event_code- اختبر أحداث Conversions API في Events Manager قبل البث المباشر
الأمان
- رموز مستخدم النظام - رموز مصادقة غير شخصية، مُقيَّدة بالأعمال
- تجزئة SHA-256 - جميع PII مُجزَّأة قبل النقل إلى خوادم Meta
- App Secret Proof - طبقة إضافية اختيارية من أمان المصادقة
- تحديد نطاق الأعمال - الصلاحيات مقيدة بحسابات إعلانية وصفحات محددة
- الامتثال لـ Meta - يخضع لشروط منصة Meta وسياسات الإعلانات
- شروط معالجة البيانات - تُطبَّق شروط معالجة البيانات في Meta على بيانات EU