سحب بيانات إعلانات ميتا في Google Sheets تلقائيًا

بيانات إعلانات فيسبوك في Google Sheets تقدر تسحبها تلقائيًا كل يوم بـ Apps Script ومن غير أي أداة مدفوعة، بشرط تجهّز توكن وصول (Access Token) لحساب إعلاني عندك صلاحية عليه، وتكتب سكريبت صغير بيكلّم Marketing API وبيكتب النتيجة في الشيت. الفايدة إنك تلاقي تقريرك جاهز كل صبح من غير ما تدخل Ads Manager وتصدّر ملفات. في المقال ده هاشرح الفكرة والخطوات وشكل الكود، مع تنبيهات مهمة عن التوكن والصلاحيات لأن تفاصيل الـ API وإصداراته بتتغير.

محتويات المقال

إيه اللي هتبنيه: بيانات إعلانات فيسبوك في Google Sheets

بدل ما تصدّر تقرير يدوي كل يوم، هتبني شيت فيه تبويب بيتحدّث تلقائيًا بأرقام حملاتك: الإنفاق، والظهور، والنقرات، والنتايج. بعد كده تقدر تعمل فوقه حسابات خاصة بيك (زي ROAS الحقيقي من بيانات المبيعات) أو لوحة Looker Studio.

الفايدة العملية:

• توفير وقت التقارير اليومية أو الأسبوعية للعميل.
• دمج بيانات الإعلانات مع بيانات المبيعات أو الـ COD في مكان واحد، وده بيساعد في التشخيص زي ما اتشرح في شجرة تشخيص الأرقام.
• تاريخ بيانات محفوظ عندك، ومش معتمد على شكل Ads Manager.

المتطلبات قبل ما تبدأ

1. صلاحية على الحساب الإعلاني عن طريق Business Manager (أو الحساب الشخصي لو الحساب كده).
2. تطبيق على Meta for Developers (App) وده اللي بيطلّع التوكن.
3. توكن وصول بصلاحية قراءة الإعلانات (`ads_read`). في بعض الحالات الصلاحية بتحتاج مراجعة من ميتا لو هتستخدمها لحسابات مش بتاعتك، لكن للاستخدام على حساباتك الخاصة عادةً بيكفي وضع التطوير.
4. جوجل شيت وحساب جوجل لتشغيل Apps Script.
5. رقم الحساب الإعلاني (Ad Account ID) من Ads Manager، بصيغة `act_XXXXXXXX`.

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

خطوات الإعداد من الصفر

الخطوة 1: جهّز التطبيق والتوكن

1. ادخل على Meta for Developers وأنشئ تطبيق جديد (نوع مناسب لتكامل Business).
2. أضف منتج Marketing API للتطبيق.
3. من أداة Graph API Explorer أو إعدادات System User في Business Manager، اطلع توكن بصلاحية `ads_read`.
4. التوكن القصير بيخلص بسرعة. للأتمتة اليومية استخدم توكن طويل المدى أو الأفضل System User Token من إعدادات Business، لأنه مخصص للأتمتة. اقرأ مدة صلاحية التوكن الحالية في التوثيق.

والتوكن زي كلمة سر: ما تشاركوش، وما تحطوش في شيت بيتشارك مع ناس. خزّنه في Script Properties مش جوه الكود.

الخطوة 2: جهّز الشيت وApps Script

1. افتح Google Sheet جديد وسمّي تبويب مثلًا `Data`.
2. من القايمة: الإضافات ← Apps Script.
3. من إعدادات المشروع ← خصائص السكريبت (Script Properties) أضف:
4. – `FB_TOKEN` = التوكن
5. – `AD_ACCOUNT` = `act_XXXXXXXX`

الخطوة 3: السكريبت

ده شكل مبسّط. الإصدار (`v21.0` في المثال) لازم تعدّله لأحدث إصدار متاح لما تطبّق، لأن ميتا بتوقف الإصدارات القديمة بعد فترة:

function fetchMetaAds() {
  const props = PropertiesService.getScriptProperties();
  const token = props.getProperty('FB_TOKEN');
  const account = props.getProperty('AD_ACCOUNT');
  const fields = 'campaign_name,spend,impressions,clicks,actions,date_start';
  const url = 'https://graph.facebook.com/v21.0/' + account + '/insights'
    + '?level=campaign&time_increment=1&date_preset=last_7d'
    + '&fields=' + fields + '&limit=500&access_token=' + token;
  const res = UrlFetchApp.fetch(url, {muteHttpExceptions: true});
  const json = JSON.parse(res.getContentText());
  if (json.error) { throw new Error(json.error.message); }
  const sheet = SpreadsheetApp.getActive().getSheetByName('Data');
  sheet.clearContents();
  sheet.appendRow(['Date','Campaign','Spend','Impressions','Clicks','Purchases']);
  json.data.forEach(function (r) {
    const p = (r.actions || []).filter(function (a) { return a.action_type === 'purchase'; })[0];
    sheet.appendRow([r.date_start, r.campaign_name, r.spend, r.impressions, r.clicks, p ? p.value : 0]);
  });
}

شرح سريع:

• `/insights`: نقطة النهاية اللي بترجّع أرقام الأداء.
• `level=campaign`: المستوى. تقدر تغيّره لـ `adset` أو `ad`.
• `time_increment=1`: سطر لكل يوم.
• `date_preset`: الفترة. ممكن تحدد تواريخ بنفسك بدل الجاهزة.
• `actions`: مصفوفة بكل الأحداث، ولازم تفلتر منها الحدث اللي عايزه. وده الحدث اللي بيتغير اسمه حسب الإعداد، فاتأكد منه من استجابة الـ API الفعلية.

لو الحساب فيه بيانات كتير، النتايج بتيجي على صفحات (Pagination)، وهتحتاج تتابع الرابط `paging.next` لحد ما يخلص.

الخطوة 4: الجدولة التلقائية

1. من Apps Script اختار «المشغّلات» (Triggers).
2. أضف مشغّل جديد للدالة `fetchMetaAds`، نوعه «مؤقت» (Time-driven)، يوميًا في ساعة بعد منتصف الليل مثلًا.
3. أول مرة هيطلب منك الصلاحيات، وافق عليها.

وفكّر في كتابة الأرقام بدل مسح كل حاجة كل مرة لو عايز تحفظ التاريخ: أضف السطور الجديدة بس، أو خزّن اليومين الأخيرين وبدّلهم، لأن ميتا بتعدّل أرقام الأيام القريبة بسبب تأخر الإسناد.

ملاحظات مهمة على دقة الأرقام

• أرقام ميتا بتتغير بأثر رجعي: المشتريات المسنودة بتتحدّث خلال أيام. فقارن الفترات القديمة بحذر، وخد بالك من نافذة الإسناد.
• الأرقام ممكن تختلف عن Ads Manager لو اختلفت إعدادات الإسناد أو المنطقة الزمنية.
• الأرقام مش بتطابق التتبع الخارجي (GA4 أو المتجر). ده طبيعي وشرحته في مقال الفرق بين ميتا وGA4.

تحسينات تقدر تضيفها

• أعمدة محسوبة: CPC، وCPM، وتكلفة الشراء، وROAS.
• تبويب للعمليات الفعلية من المتجر وربط الاتنين.
• لوحة Looker Studio فوق الشيت.
• تنبيه على إيميلك لو الإنفاق عدّى حد معين.
• عمل نسخة احتياطية للشيت.

معالجة الأخطاء وحدود الاستخدام

سكريبت الأتمتة اللي بيشتغل لوحده لازم تحسب حساب إنه يقع:

• خطأ التوكن: لو انتهت الصلاحية، الـ API بيرجّع كائن `error`. الكود اللي فوق بيرمي استثناء بالرسالة، وتقدر تضيف إرسال إيميل لنفسك بـ `MailApp.sendEmail` لما يحصل ده عشان تعرف فورًا.
• حدود معدل الطلبات (Rate Limits): ميتا بتحدّ عدد الاستدعاءات. لو حسابك كبير، قلل الحقول وفترة السحب، وأضف انتظار بسيط بين الطلبات بـ `Utilities.sleep`.
• مهلة تنفيذ Apps Script: السكريبت له حد أقصى للتنفيذ في المرة الواحدة. لو الداتا كبيرة، قسّمها على أكتر من تشغيل أو اسحب مستوى أعلى (حملة بدل إعلان).
• تغيّر أسماء الحقول: ميتا ممكن تضيف أو تغيّر حقول. راجع التوثيق الرسمي عند أي خطأ مفاجئ.
• المنطقة الزمنية: تأكد إن المنطقة الزمنية للحساب الإعلاني ومنطقة الشيت بيتفقوا، وإلا هتلاقي يوم زيادة أو ناقص.

بدائل لو مش عايز كود

• Google Sheets Add-ons وأدوات الربط الجاهزة: بتسحب البيانات بدون كود، وبتكلّف اشتراك حسب الأداة والحجم.
• Looker Studio Connectors: لو هدفك لوحة بيانات مش شيت.
• التصدير المجدول من Ads Manager: ميزة تقارير مجدولة بتبعتلك ملف على الإيميل، وده أبسط حل لكن مش تفاعلي.
• أتمتة بأدوات زي Make أو n8n: بتربط الـ API بالشيت بخطوات بصرية. مناسبة لو عندك خبرة في الأتمتة، وراجع فصل سلم الأتمتة في ميتا عشان تحدد إيه اللي يستاهل تتأتمت.

اختار الأبسط اللي بيخدم هدفك: لو بتحتاج تقرير أسبوعي بس، التصدير المجدول كفاية. ولو بتدمج بيانات مبيعات وإعلانات وتحسب مؤشرات خاصة بيك، السكريبت أو أداة الربط أنسب. والأهم من الأداة إنك تحدد الأول إيه الأسئلة اللي المفروض التقرير يجاوب عليها. ### مثال: تحويل البيانات لتقرير قرار

بعد ما البيانات توصل الشيت، حوّلها لتقرير بيساعدك تتصرف:

1. تبويب خام (Data): السكريبت بيكتب فيه ومبتلمسوش بإيدك.
2. تبويب تقرير (Report): بتستخدم `QUERY` أو `SUMIFS` تجمّع الإنفاق والمشتريات لكل حملة في آخر 7 أيام.
3. أعمدة محسوبة: تكلفة الشراء = الإنفاق ÷ المشتريات، وROAS = قيمة المشتريات ÷ الإنفاق.
4. مقارنة بحدّك: حط في خلية ثابتة Break-even ROAS بتاعك (بتحسبه من هامش الربح) وفعّل تنسيق شرطي بيلوّن الحملة الأحمر لو تحت الحد.
5. مراجعة يومية سريعة: بدل ما تفتح كل حملة، تبص على الألوان وتفتح بس اللي محتاجة تدخل.

استخدم الأرقام ككشّاف مش كحكم نهائي. قبل ما توقف حملة بسبب يوم واحد سيء، راجع متى تزوّد الميزانية ومتى توقف عشان القرار يبقى على اتجاه وليس على تذبذب يوم.

أخطاء شائعة

• تخزين التوكن داخل الكود أو في شيت مشارك.
• نسيان إن التوكن بينتهي فيقف السكريبت فجأة، فحط تنبيه لما يحصل خطأ.
• الاعتماد على إصدار API قديم لحد ما يتوقف.
• مقارنة الأرقام مع Ads Manager بدون توحيد الإعدادات.
• سحب مستوى الإعلان لحساب ضخم من غير Pagination.

للتأكد من أحدث التفاصيل، راجع توثيق Google Apps Script الرسمي، لأن الواجهات والسياسات بتتغيّر باستمرار.

مقالات ذات صلة بتفيدك:

• تنبيهات تليجرام من Google Sheets خطوة بخطوة
• برنامج CRM مجاني لمشروع صغير: الخيارات وإزاي تبنيه في Google Sheets
• ربط فورم الموقع بـ Google Sheets بدون بلجن
• Google Apps Script للمسوّقين: من أين تبدأ

ومن المواضيع القريبة: تشغيل السكريبت تلقائيًا بالمشغلات.

أسئلة شائعة

هل ده مجاني فعلًا؟

الـ API وApps Script مجانيين في الاستخدام العادي، مع وجود حدود استخدام (Quotas) من جوجل وميتا. وهتدفع بس لو استخدمت أداة جاهزة بدل السكريبت.

مش بعرف أبرمج، أعمل إيه؟

الكود أعلاه ممكن تنسخه وتعدّل عليه بحذر، أو تستعين بمتخصص. وفي أدوات جاهزة بتعمل نفس الشغل بدون كود بس غالبًا باشتراك.

أقدر أسحب أكتر من حساب إعلاني؟

أيوه، بتكرر الاستدعاء لكل حساب وبتكتب كل واحد في تبويب أو في عمود منفصل.

إيه سبب خطأ التوكن؟

غالبًا انتهت صلاحيته أو ناقصه الصلاحية أو ماعندوش وصول للحساب الإعلاني. اقرأ رسالة الخطأ من الـ API.

لو عايز تبني تقرير تلقائي لحملاتك أو تربط بيانات الإعلانات بالمبيعات، تقدر تحجز استشارة ونظبطه حسب مشروعك.