الفصل 17: التكاملات¶
الجمهور المستهدف: مهندسو DevOps، مهندسو المنصة
حسابات خدمة GCP¶
يحتاج Cat-Scan إلى بيانات اعتماد حساب خدمة GCP للتفاعل مع واجهات Google البرمجية.
الإعداد:
1. أنشئ حساب خدمة في مشروع GCP الخاص بك مع صلاحية الوصول إلى Authorized Buyers API.
2. قم بتنزيل ملف مفتاح JSON.
3. ارفعه في /settings/accounts > تبويب اتصال API.
4. تحقق من الاتصال: يختبر Cat-Scan إمكانية الوصول والصلاحيات.
ما يُتيحه:
- اكتشاف المقاعد (discoverSeats)
- مزامنة تكوين الاستهداف المسبق (syncPretargetingConfigs)
- مزامنة نقاط نهاية RTB (syncRTBEndpoints)
- جمع الإبداعات (collectCreatives)
حالة المشروع:
تحقق من صحة مشروع GCP في /settings/accounts أو عبر
GET /integrations/gcp/project-status. يتحقق هذا من صلاحية حساب الخدمة، وإمكانية الوصول إلى المشروع، وتفعيل واجهات API المطلوبة.
واجهة Google Authorized Buyers API¶
يقوم Cat-Scan بمزامنة البيانات من Authorized Buyers API:
| العملية | ما تسحبه | متى تُشغّل |
|---|---|---|
| اكتشاف المقاعد | حسابات المشترين المرتبطة بحساب الخدمة | الإعداد الأولي، عند إضافة مقاعد جديدة |
| مزامنة الاستهداف المسبق | حالة تكوين الاستهداف المسبق الحالية من Google | بعد التغييرات الخارجية في واجهة AB |
| مزامنة نقاط نهاية RTB | عناوين وحالة نقاط نهاية المزايد | الإعداد الأولي، بعد تغييرات نقاط النهاية |
| مزامنة الإبداعات | البيانات الوصفية للإبداعات (التنسيقات، الأحجام، الوجهات) | دوريًا، عبر "مزامنة الكل" في الشريط الجانبي |
تكامل Gmail¶
يُرسل Google Authorized Buyers تقارير CSV يومية بالبريد الإلكتروني. يمكن لـ Cat-Scan استيعابها تلقائيًا.
الإعداد:
1. انتقل إلى /settings/accounts > تبويب تقارير Gmail.
2. فوّض Cat-Scan للوصول إلى حساب Gmail الذي يستقبل تقارير AB.
3. سيقوم Cat-Scan بالاستقصاء عن رسائل التقارير الجديدة واستيراد ملفات CSV المرفقة.
المراقبة:
- GET /gmail/status: الحالة الحالية، عدد الرسائل غير المقروءة، آخر سبب
- POST /gmail/import/start: تشغيل دورة استيراد يدويًا
- POST /gmail/import/stop: إيقاف عملية استيراد قيد التشغيل
- GET /gmail/import/history: سجلات الاستيراد السابقة
استكشاف الأخطاء:
- عدد كبير من الرسائل غير المقروءة (أكثر من 30): تراكم في الاستيراد، قد يحتاج تدخلاً يدويًا
- last_reason: error: تحقق من السجلات، قد يحتاج إعادة تفويض
- انظر استكشاف الأخطاء وإصلاحها للخطوات التفصيلية.
مزوّدو الذكاء الاصطناعي اللغوي¶
يستخدم Cat-Scan الذكاء الاصطناعي للكشف عن لغة الإبداعات والإشارة إلى حالات عدم التطابق الجغرافي-اللغوي (مثلاً: إعلان بالإسبانية في سوق عربي).
المزوّدون المدعومون:
| المزوّد | التكوين |
|---|---|
| Gemini | مفتاح API في /settings/accounts |
| Claude | مفتاح API في /settings/accounts |
| Grok | مفتاح API في /settings/accounts |
يُكوَّن عبر GET/PUT /integrations/language-ai/config. يكفي أن يكون مزوّد واحد فقط نشطًا.
خطافات التحويلات (Webhooks)¶
تُرسل الأنظمة الخارجية أحداث التحويل إلى Cat-Scan عبر خطافات الويب.
طبقات الأمان:
| الطبقة | الغرض | التكوين |
|---|---|---|
| التحقق بـ HMAC | يضمن أصالة الطلبات (موقّعة بسر مشترك) | سر مشترك يُكوَّن في إعدادات خطافات الويب |
| تحديد المعدل | يمنع إساءة الاستخدام | تلقائي، مع حدود قابلة للتكوين |
| مراقبة الحداثة | يُنبّه عند توقف وصول الأحداث | نافذة تقادم قابلة للتكوين |
المراقبة:
- GET /conversions/security/status: حالة HMAC، وحالة تحديد المعدل، وحالة الحداثة
- GET /conversions/health: صحة الاستيعاب والتجميع الإجمالية
- GET /conversions/readiness: ما إذا كانت بيانات التحويل حديثة بما يكفي للوثوق بها
مواضيع ذات صلة¶
- نظرة عامة على البنية: موقع التكاملات في البنية العامة
- إدارة المستخدمين: إدارة حسابات الخدمة
- لمشتري الوسائط: التحويلات والإسناد يغطي إعداد التحويلات من منظور المشتري.