استكشاف الأخطاء

هل تواجه مشاكل؟ لا تقلق - معظم المشاكل لها حلول بسيطة! اعثر على مشكلتك أدناه واتبع الحل.

فشل التحقق من Webhook

الخطأ: "The callback URL or verify token couldn't be validated."

الأسباب والحلول المحتملة:

#	Cause	Fix
1	URL is not HTTPS	Install an SSL certificate on your server
2	Typo in callback URL	Copy-paste directly from the module settings
3	Typo in verify token	Copy-paste directly from the module settings
4	Server is blocking requests	Check your firewall / security plugins
5	.htaccess redirect issues	Make sure the URL doesn't redirect (no www ↔ non-www redirect issues)
6	Selected "User" instead of "Page"	Change the dropdown to "Page" in Facebook webhooks

كيفية التصحيح:

1. افتح متصفحك وزر عنوان URL الخاص بـ webhook مباشرة:

   https://yourcrm.com/facebookleadsintegration/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=test123

2. إذا كان يعمل بشكل صحيح، يجب أن ترى test123 معروضًا على الصفحة
3. إذا رأيت صفحة خطأ، فالمشكلة على جانب الخادم الخاص بك

تلميح

Still not working? Check your server's error logs at /path/to/your/crm/application/logs/

خطأ "Invalid Scopes" أثناء تسجيل الدخول عبر Facebook

الخطأ: "Invalid Scopes: pages_manage_metadata"

الحل:

يعني هذا أن الوحدة تطلب إذنًا قديمًا. تأكد من استخدام أحدث إصدار من الوحدة (v2.0.0+)، الذي يستخدم الأذونات الصحيحة:

• pages_show_list
• pages_read_engagement
• leads_retrieval
• pages_manage_ads
• ads_management

حدّث الوحدة إلى أحدث إصدار للإصلاح.

"Error Accessing App" / "App Not Active"

الخطأ: عند محاولة الاتصال بـ Facebook، ترى "Error Accessing App" أو "The app is not active."

الأسباب والحلول المحتملة:

#	Cause	Fix
1	Wrong App ID in module settings	Double-check the App ID matches your Meta App
2	App was deleted or disabled	Check your app at developers.facebook.com/apps
3	You're not an admin/developer of the app	Add yourself in App Roles → Roles
4	App restrictions	Check App Settings → Basic → App Restrictions

Test Lead يعمل لكن Leads الحقيقية لا تصل

زر "Send Test Lead" في الوحدة يعمل، لكن leads الحقيقية من Facebook لا تظهر.

تحقق من التالي:

#	Check	How
1	Is your Page subscribed?	Settings → Connected Pages → Must show "Monitoring"
2	Is the webhook verified?	Settings → Connection Status → Webhook must be green
3	Is "leadgen" subscribed?	Meta App → Webhooks → Page → "leadgen" must be checked
4	Is the ad using the right Page?	Ads Manager → Ad Set → Make sure it uses the subscribed Page
5	Is the ad running?	Ads Manager → Campaign status should be "Active"

الاختبار باستخدام أداة Facebook:

استخدم Lead Ads Testing Tool لإرسال lead تجريبي webhook حقيقي. إذا عمل هذا لكن الإعلانات الفعلية لا تعمل، فالمشكلة على الأرجح في إعداد حملة الإعلان.

خطأ 500 على صفحات الوحدة

العرض: صفحات الوحدة تظهر صفحة فارغة أو "500 Internal Server Error"

الحلول:

1. تحقق من سجلات أخطاء PHP:

   /path/to/your/crm/application/logs/log-YYYY-MM-DD.php

2. الأسباب الشائعة:

   • إصدار PHP قديم جدًا (يحتاج 7.4+)
   • امتدادات PHP مفقودة (cURL, JSON)
   • أذونات الملفات غير صحيحة
   • ملفات الوحدة تالفة أثناء الرفع

3. إصلاح أذونات الملفات:

   find /path/to/modules/facebookleadsintegration -type f -exec chmod 644 {} \;
   find /path/to/modules/facebookleadsintegration -type d -exec chmod 755 {} \;

4. أعد رفع الوحدة إذا كانت الملفات قد تتلف

زر Copy لا يعمل

العرض: النقر على زر "Copy" بجانب webhook URL أو verify token لا يفعل شيئًا.

الحل:

• تأكد من أن CRM الخاص بك يُستخدم عبر HTTPS - Clipboard API يتطلب سياقًا آمنًا
• جرب تحديد النص يدويًا والضغط على Ctrl+C
• تحقق من وحدة التحكم في المتصفح لمعرفة أخطاء JavaScript (F12 → Console tab)

Leads عالقة في "Pending Retry"

العرض: Sync History يعرض leads بحالة "Pending" لا تتم معالجتها.

الحلول:

1. المعالجة يدويًا: انتقل إلى Sync History → انقر على "Process Retry Queue"
2. تحقق من cron: قائمة إعادة المحاولة تتم معالجتها تلقائيًا عبر cron job في Perfex CRM
   • تأكد من تشغيل cron job: Setup → Settings → Cron Job
   • يجب استدعاء عنوان URL الخاص بـ cron كل 5 دقائق
3. تحقق من رسالة الخطأ في Sync History لمعرفة سبب فشل lead في البداية

انتهاء صلاحية Access Token

العرض: اختبار الاتصال يفشل مع "Token expired" أو تتوقف leads عن الوصول.

الحل:

تقوم الوحدة بتبديل الرموز قصيرة المدى برموز طويلة المدى (صالحة لحوالي 60 يومًا). للتحديث:

1. انتقل إلى Meta Leads → Settings
2. انتقل إلى Connected Pages
3. انقر على "Connect with Facebook" مرة أخرى
4. سجّل الدخول وامنح الأذونات
5. يتم تحديث token تلقائيًا

تلميح

ضبط تذكير لإعادة الاتصال كل 50 يومًا للحفاظ على token جديد!

الحقول لا تُعيّن بشكل صحيح

العرض: بيانات lead تظهر في الحقول الخاطئة أو مفقودة.

خطوات التصحيح:

1. انتقل إلى Sync History → انقر على إدخال lead لرؤية البيانات الخام
2. تحقق من أسماء الحقول التي يرسلها Facebook
3. انتقل إلى Field Mapping → تأكد من تطابق اسم حقل Facebook
4. تذكر: الحقول القياسية (email, full_name, phone_number) تُعيّن تلقائيًا

مشاكل أسماء الحقول الشائعة:

What You Expect	What Facebook Sends	Solution
name	full_name	Already auto-mapped
phone	phone_number	Already auto-mapped
company	company_name	Already auto-mapped
budget	custom_question_1	Create a custom mapping

الوحدة لا تظهر بعد التثبيت

الحلول:

1. تحقق من موقع الملف: يجب أن يكون مجلد الوحدة في modules/facebookleadsintegration/
2. تحقق من اسم الملف: الملف الرئيسي يجب أن يكون facebookleadsintegration.php (كل الأحرف صغيرة)
3. فعّل الوحدة: انتقل إلى Setup → Modules → انقر على Activate
4. تحقق من الأذونات: يجب أن تكون الملفات قابلة للقراءة من قبل خادم الويب (644 للملفات، 755 للمجلدات)

مشاكل خاصة بالخادم

مستخدمو Cloudflare

إذا كنت تستخدم Cloudflare، أضف IPs webhook الخاصة بـ Facebook إلى القائمة البيضاء:

1. انتقل إلى Cloudflare → WAF (Web Application Firewall)
2. أنشئ قاعدة للسماح بطلبات من Facebook
3. أو أضفها إلى القائمة البيضاء لجدار الحماية:
   • يمكن العثور على IPs webhook الخاصة بـ Facebook في: https://developers.facebook.com/docs/sharing/webmasters/getting-started/webhooks/

مستخدمو Nginx

تأكد من أن إعداد Nginx يسمح بطلبات POST إلى عنوان URL الخاص بـ webhook ولا يحظر User-Agent الخاص بـ Facebook.

الاستضافة المشتركة

معظم الاستضافة المشتركة تعمل بشكل جيد. إذا واجهت مشاكل:

• تحقق من تفعيل allow_url_fopen في PHP
• تحقق من تثبيت امتداد cURL
• تحقق من أن مضيفك لا يحظر webhooks الواردة (بعض المضيفين يركزون على الأمان يفعلون ذلك)

لا تزال بحاجة للمساعدة؟

إذا لم يحل أي من الحلول أعلاه مشكلتك:

1. تحقق من سجلات أخطاء Perfex CRM
2. تحقق من Sync History للوحدة لرسائل الخطأ
3. التقط لقطة شاشة لرسائل الخطأ
4. اتصل بنا على [email protected] مع:
   • إصدار Perfex CRM الخاص بك
   • إصدار PHP
   • رسالة الخطأ
   • خطوات إعادة إنتاج المشكلة

تحقق من الأسئلة الشائعة لمزيد من الإجابات FAQ