API مستوى التحكم في بوابة واجهة API التحويلات للحسابات المتعددة

دمج الشركاء

نظرة عامة

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

حالات الاستخدام المحتملة:

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

راجع القسم أدناه للحصول على مزيد من التفاصيل حول خطوات الدمج.

يتم استخدام مصطلح API مستوى التحكم في بوابة واجهة API التحويلات للحسابات المتعددة أو البوابة بشكل متبادل في هذا المستند.

دليل الدمج

اعتمادًا على حالة الاستخدام، يمكن أن يكون هناك مساران للدمج (كما هو موضح في الرسم البياني أدناه):

الدمج الجزئي لـ API مستوى التحكم. وهذا لا يتطلب المصادقة من المعلنين.
الدمج الكامل مع API مستوى التحكم. هذا يتطلب المصادقة من المعلنين إما باستخدام ملحق Meta للأعمال (MBE) أو الإنشاء اليدوي للرموز.

المتطلبات الأساسية

بالنسبة لكلا مساري الدمج، يحتاج الشريك أولاً إلى إكمال الخطوات التالية:

الخطوة الأولى: التأهيل كمضيف من مثيل البوابة

الخطوة الثانية: إنشاء اسم حساب API وsecret key لـ API

انتقل إلى:

https://<Conversions API Gateway Endpoint>/hub/

انتقل إلى علامة تبويب إعدادات المضيف، وحدّد صفحة إدارة حسابات API، وانقر على زر إضافة حساب API.

أعد إدخال كلمة السر. انقر على متابعة.

أدخل اسم حساب API. انقر على متابعة.

يمكن أن يتكون اسم الحساب من أحرف وأرقام فقط، ولا يمكن أن يحتوي على مساحات. الحد الأقصى للطول هو 20 حرفًا.

انسخ secret key الذي تم إنشاؤه واحفظه. لن تتمكن من عرضه مرة أخرى.

لإزالة حساب API، انقر على حذف حساب API. يرجى ملاحظة أن هذا الإجراء لا يمكن التراجع عنه ويمكن أن يتسبب في تعطيل تطبيقات أو خدمات أي معلن يستخدم API.

الدمج الجزئي

حالة استخدام مبنية على الدمج الجزئي:

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

قد يبدو دفق المستخدم عالي المستوى كما يلي:

لتحقيق ما سبق، يمكن للشريك دمج مجموعة فرعية من API مستوى التحكم، بما في ذلك:

الحصول على رمز وصول API
إنشاء حساب للمعلنين
الحصول على تفاصيل استخدام الحساب، على سبيل المثال، لأغراض الفوترة

الدمج الكامل

حالة استخدام مبنية على الدمج الكامل:

يشترك المعلن في خدمة البوابة باستخدام واجهة المستخدم الخاصة بالشريك.
يقوم الشريك بتأهيل حساب البوابة الخاص بالمعلن ويحصل على إذن لإدارة الحساب؛ ويصرح المعلن للشريك باستخدام ملحق Meta للأعمال (MBE) أو الإنشاء اليدوي للرموز.
يمكن للمعلن تنفيذ إدارة مصدر البيانات بالإضافة إلى إدارة مستخدم الحساب والنطاق والتوجيه في واجهة مستخدم الشريك.
يقوم الشريك باسترداد استخدام حساب المعلن والفواتير وفقًا لذلك.

قد يبدو دفق المستخدم عالي المستوى كما يلي:

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

المصادقة

يتوفر لدى الشركاء خياري المصادقة التاليين لوحدات بيكسل Meta التي لا تتم إدارتها بواسطتهم:

الخيار الأول - ملحق Meta للأعمال (MBE)

قبل أن تبدأ، تحتاج إلى:

إكمال جميع المتطلبات لتنفيذ ملحق MBE
الاتصال بممثل Meta لإضافة تطبيقك إلى قائمة السماح للحصول على إذن خاص: open_bridge_configuration_management

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

قمت بتعيين قيمة معلمة القناة في كائن تكوين الإعداد كـ CONVERSIONS_API_GATEWAY_ADVERTISER.
قادر على استلام استجابة حدث webhook عند إكمال التأهيل.
استخدام رمز الوصول الذي تم إرجاعه عبر ملحق MBE وتحويله إلى رمز وصول مستخدم النظام عن طريق تنفيذ استدعاء إضافي في API.
حفظ نسخة من external_business_id، pixel_id، business_id ورمز وصول مستخدم النظام في نظامك.

الخيار الثاني - رمز وصول مستخدم نظام العميل

باستخدام هذا الخيار، يمكن للشركاء تمكين المعلنين من:

إنشاء رمز وصول مستخدم النظام يدويًا عبر واجهة API التحويلات داخل الإعدادات في مدير الأحداث (EM)
مشاركة pixel_id، وbusiness_id ورمز وصول مستخدم النظام مع الشريك وحفظ نسخة منه.

الدمج

يمكن للشركاء دمج المجموعة الكاملة من API مستوى التحكم. تتوفر المزيد من التفاصيل في مرجع API.

تكافؤ API وواجهة المستخدم

نفرض تكافؤ API وواجهة المستخدم من خلال الكشف عن نقاط نهاية API نفسها المستخدمة في واجهة مستخدم البوابة. ومع ذلك، فإن أي نقطة نهاية API غير مشمولة في مرجع API تكون عرضة للتغيير أثناء التطوير في المستقبل. لتقييد التأثير غير المتوقع عند الحد الأدنى، ترجع نقاط نهاية API التي لم يتم الكشف عنها رمز الخطأ: 418. لا يزال بإمكانك استخدام API ولكن على مسؤوليتك الخاصة.