كيفية استخدام API مكتبة إعلانات فيسبوك (Meta)

واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك/ميتا، التي نشير إليها باسم واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك، هي واجهة متاحة للجمهور تمنح المطورين إمكانية الوصول إلى الإعلانات المنشورة على فيسبوك وإنستغرام ومنصات أخرى تملكها ميتا (مثل واتساب وثريدز). من خلال واجهة برمجة التطبيقات هذه، يمكنك البحث عن الإعلانات بواسطة كلمة مفتاحية أو معرف الصفحة أو البلد أو نوع الإعلان، واسترداد البيانات الوصفية مثل المواد الإعلانية، ونطاقات الإنفاق، ومرات الظهور، ومنصات الناشرين، وغير ذلك الكثير.

تُعد واجهة برمجة التطبيقات هذه مفيدة بشكل خاص لأبحاث الشفافية، والتدقيقات التسويقية، والتحليل التنافسي، وتحليل المواد الإعلانية، أو بناء أدوات حول بيانات إعلانات وسائل التواصل الاجتماعي. سواء كنت ترغب في مراقبة الإعلانات النشطة، أو دراسة الإعلانات السياسية أو المتعلقة بالقضايا الاجتماعية (إعلانات SIEP)، أو تحليل الاستراتيجيات التسويقية، فإن واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك توفر بابًا قويًا لبيانات الإعلانات.

لماذا تستخدم واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك وماذا تتيح لك أن تفعل؟

بعض القدرات الرئيسية لواجهة برمجة تطبيقات مكتبة إعلانات فيسبوك:

1. البحث بالكلمات المفتاحية، ومعرفات الصفحات، والبلد، ونوع الإعلان — يمكنك تضييق نطاق الإعلانات بناءً على محتواها، ومن نشرها، وأين تُعرض، ونوع الحملة التي تمثلها.
2. التصفية حسب الحالة: نشط/غير نشط، نطاقات الإنفاق، مرات الظهور — مفيد عندما تريد فقط الإعلانات الجارية حاليًا أو تلك التي تتجاوز/تقل عن عتبات إنفاق معينة.
3. استرداد البيانات الوصفية للإعلان — بما في ذلك حقول مثل page_name، ad_snapshot_url، spend، impressions، publisher_platforms (فيسبوك/إنستغرام)، والمزيد.
4. دعم تغطية بيانات واسعة وطويلة الأمد — على سبيل المثال، عالميًا لإعلانات القضايا الاجتماعية والسياسية (SIEP ads)، وللعديد من المناطق للإعلانات العامة (وفقًا لسياسات ميتا الإقليمية اعتبارًا من عام 2025).
5. وصول مجاني إلى البيانات العامة — لا توجد تكلفة أولية لاسترداد بيانات الإعلانات العامة، طالما أن لديك إعداد الوصول المناسب.

باختصار، توفر واجهة برمجة التطبيقات طريقة منظمة وقابلة للبرمجة لاستكشاف وجمع بيانات الإعلانات على نطاق واسع.

دليل خطوة بخطوة: كيفية البدء باستخدام واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك

الخطوة 1: التحقق من حسابك وهويتك على فيسبوك/ميتا

• سجل الدخول/أنشئ حسابك على فيسبوك (شخصي أو تجاري).
• تأكد من أن حسابك موثق (تتطلب ميتا أحيانًا التحقق من الهوية للوصول إلى واجهة برمجة التطبيقات). (التحقق من الحساب)
• هذه الخطوة مهمة بشكل خاص إذا كنت تخطط لطلب الوصول إلى بيانات مكتبة الإعلانات عبر تطبيق.

الخطوة 2: تسجيل تطبيق مطور ميتا

• قم بزيارة Meta for Developers ← "البدء" وسجل الدخول إلى المنصة. (انقر هنا)

• أنشئ تطبيقًا جديدًا: اختر "أخرى" أو نوعًا عامًا إذا لم تكن تعلن.

• اختر أنك تريد الوصول إلى واجهات برمجة تطبيقات التسويق / مكتبة الإعلانات.

• في البداية، سيكون التطبيق في وضع التطوير — وهذا يكفي للاختبار الأساسي والاستخدام على نطاق صغير.

الخطوة 3: إنشاء رمز الوصول

• استخدم مستكشف واجهة برمجة تطبيقات Graph (Graph API Explorer) أو أدوات ميتا لإنشاء رمز وصول للمستخدم.
• تأكد من أن الرمز لديه الأذونات الضرورية (مثل ads_read، وربما ads_archive أو غيرها حسب متطلبات ميتا). (فيسبوك للمطورين)

ملاحظة: رموز الوصول تنتهي صلاحيتها؛ قد تحتاج إلى تمديدها أو إنشاء رموز ذات صلاحية طويلة اعتمادًا على استخدامك.

الخطوة 4: إجراء أول استدعاء لواجهة برمجة التطبيقات

يمكنك الاستعلام عن نقطة النهاية /ads_archive (الجذر الخاص بواجهة برمجة تطبيقات مكتبة الإعلانات). استخدم أحدث إصدار لواجهة برمجة التطبيقات (على سبيل المثال v23.0 أو أحدث). (فيسبوك للمطورين)

مثال: باستخدام curl

curl -G \
  -d "search_terms=skincare" \
  -d "ad_reached_countries=['US']" \
  -d "ad_active_status=ACTIVE" \
  -d "fields=page_name,ad_snapshot_url,spend,impressions,publisher_platforms" \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  "https://graph.facebook.com/v23.0/ads_archive"

مثال: باستخدام JavaScript (fetch)

const response = await fetch(
  `https://graph.facebook.com/v23.0/ads_archive?` +
  `search_terms=skincare&ad_reached_countries=['US']&ad_active_status=ACTIVE` +
  `&fields=page_name,spend,impressions,publisher_platforms` +
  `&access_token=YOUR_ACCESS_TOKEN`
);
const data = await response.json();
console.log(data);

سيتضمن رد JSON مصفوفة من كائنات الإعلانات، يحتوي كل منها على بيانات وصفية مثل page_name، ad_snapshot_url، نطاقات الإنفاق، نطاق مرات الظهور، منصات الناشرين، وربما المزيد من الحقول.

الخطوة 5: التعامل مع ترقيم الصفحات والنتائج الكبيرة

نظرًا لأن مكتبة الإعلانات قد تُرجع العديد من النتائج، تستخدم واجهة برمجة التطبيقات ترقيم الصفحات. كن مستعدًا للتكرار عبر الصفحات اللاحقة — افحص الاستجابة بحثًا عن رموز paging أو المؤشر وكرر وفقًا لذلك. غالبًا ما يقوم المطورون ببناء حلقات في التعليمات البرمجية لتجميع مجموعات النتائج الكبيرة.

الخطوة 6: حالات الاستخدام — ماذا يمكنك أن تفعل بهذه البيانات؟

فيما يلي حالات الاستخدام الشائعة:

1. التحليل التنافسي — استرداد الإعلانات من صفحة فيسبوك لمنافس (عبر معرف الصفحة) لدراسة موادهم الإعلانية، تقديرات الإنفاق، أو نطاق الاستهداف.
2. مراقبة الاتجاهات والأبحاث — تتبع أنواع الإعلانات النشطة حسب الكلمة المفتاحية، المنطقة، نوع الوسائط، أو نوع الإعلان (مثل السياسية، الإسكان، القضايا الاجتماعية).
3. لوحات معلومات استخبارات التسويق — تجميع البيانات (نطاقات الإنفاق، مرات الظهور، تكرار الإعلان) وتصورها بمرور الوقت أو عبر المناطق.
4. تحليل/إلهام المواد الإعلانية — جلب وأرشفة المواد الإعلانية (عناوين URL للصور/الفيديو) للإلهام في المنتجات أو لتدقيقات الامتثال.
5. البحث الأكاديمي/الشفافية — استخدام بيانات الإعلانات للدراسات حول الإعلانات السياسية، حملات القضايا الاجتماعية، أو اتجاهات السوق.

تُبرز حالات الاستخدام هذه قيمة الحصول على وصول منظم ومبرمج لبيانات الإعلانات.

اختبار واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك باستخدام Apidog

استخدم Apidog كساحة اختبار لواجهة برمجة تطبيقات مكتبة إعلانات فيسبوك. إليك كيفية البدء باختبار واجهات برمجة التطبيقات الخاصة بك في Apidog:

1. في Apidog، أنشئ نقطة نهاية API جديدة: اضبط الطريقة على GET، وعنوان URL على https://graph.facebook.com/v23.0/ads_archive.

2. ضمن معلمات الاستعلام (query parameters)، أضف معلمات مثل search_terms، ad_reached_countries، fields، و access_token.

3. اضغط على "إرسال" (Send) — سيقوم Apidog بجلب البيانات وعرض استجابة JSON لك في شكل منظم.

4. يمكنك التجربة مع مجموعات متعددة من المعلمات، واختبار ترقيم الصفحات، وحتى حفظ أمثلة الاستجابات للتوثيق أو التحليل.

يُعد هذا النهج مفيدًا بشكل خاص للاستكشاف السريع لبيانات الإعلانات، واختبار استعلامات البحث، وبناء عمليات التكامل دون كتابة رمز برمجي كامل.

الأسئلة الشائعة

س1. هل أحتاج إلى حساب إعلانات خاص أو حساب تجاري لاستخدام واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك؟
لا — حساب ميتا موثق يكفي عادةً. ومع ذلك، يجب عليك تسجيل تطبيق مطور ميتا والحصول على رمز وصول مع الأذونات المناسبة (مثل ads_read، ads_archive). يحتاج بعض المستخدمين إلى إكمال التحقق من الهوية للحصول على وصول كامل.

س2. هل يمكنني الحصول على بيانات لأي إعلان (وليس فقط الإعلانات السياسية أو المتعلقة بالقضايا الاجتماعية)؟
نعم — تدعم واجهة برمجة التطبيقات الإعلانات العامة (وليس فقط إعلانات SIEP). يمكنك استخدام ad_type=all (أو حذف الفلتر) اعتمادًا على المنطقة وتوفر الإعلان.

س3. كم عدد الإعلانات التي يمكنني استردادها في طلب واحد؟
بشكل افتراضي، تُرجع واجهة برمجة التطبيقات عددًا محدودًا من الإعلانات لكل طلب (ترقيم الصفحات). لاسترداد المزيد، تحتاج إلى التكرار عبر الصفحات باستخدام مؤشر الترقيم المتوفر في الاستجابة.

س4. هل يمكنني الوصول إلى المواد الإعلانية (الصور، مقاطع الفيديو) عبر واجهة برمجة التطبيقات؟
تحصل على ad_snapshot_url أو حقول مشابهة ترتبط بمعاينة المواد الإعلانية. ومع ذلك، لا توفر ميتا دائمًا ملفات وسائط مباشرة — قد يتطلب جلب الصور أو مقاطع الفيديو الفعلية خطوات إضافية.

س5. هل توجد طريقة لأتمتة استرداد البيانات وتجنب مشكلات انتهاء صلاحية الرمز المميز؟
نعم — يمكنك إنشاء رموز مميزة طويلة الأمد في أدوات مطوري ميتا أو إعداد نظام خلفي يقوم بتحديث الرموز بشكل دوري. لاسترداد البيانات على نطاق واسع، من الشائع دمج إدارة الرموز المميزة مع حلقات ترقيم الصفحات. قم دائمًا بتخزين الرموز المميزة بأمان.

الخلاصة

توفر واجهة برمجة تطبيقات مكتبة إعلانات فيسبوك (ميتا) بوابة قوية ومنظمة لبيانات الإعلانات — مما يمكّن المطورين والمسوقين والباحثين والمحللين من البحث وجمع وتحليل حملات الإعلانات برمجيًا عبر منصات ميتا. باستخدامها، يمكنك بناء لوحات معلومات، وإجراء تحليل تنافسي، وتنفيذ أبحاث الشفافية، أو تجميع المواد الإعلانية على نطاق واسع.

من خلال إعداد تطبيق مطور ميتا، والحصول على رمز وصول مناسب، وتقديم طلبات إلى نقطة النهاية /ads_archive — مع الاختبار اختياريًا عبر أدوات مثل Apidog — يمكنك فتح ثروة من بيانات مكتبة الإعلانات. بينما توجد قيود (أذونات، حدود المعدل، ترقيم الصفحات، استرداد الوسائط)، فإن الفوائد غالبًا ما تفوق الجهد المبذول.

لأي شخص يحتاج إلى بيانات إعلانات عامة من فيسبوك/ميتا — تُعد واجهة برمجة تطبيقات مكتبة الإعلانات خيارًا قيمًا ورسميًا ومرنًا.