التنفيذ الشامل لواجهة API التحويلات

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

مزايا الدمج

• رؤية أعمق للمسار: تتيح لك واجهة API التحويلات مشاركة مصفوفة بيانات أوسع عند مقارنتها مع بيكسل Meta. باستخدام API، يمكنك اتخاذ قرارات مع وضع المزيد من المعلومات في الاعتبار، مثل بيانات إدارة علاقات العملاء وأحداث المسارات النهائية (بما في ذلك العملاء المحتملين المؤهلين) ومسارات التحويل متعددة المواقع عبر موقع ويب وموقع فعلي.

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

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

نظرة عامة

يمكنك التفكير في دمج واجهة API التحويلات في مرحلتين رئيسيتين:

• التحضير - حدد نوع الدمج المناسب لك، ثم حدد الأحداث التي تريد إرسالها، ثم راجع خيارات التحسين المتوفرة.

• التنفيذ - تعرف على كيفية تنفيذ API. في هذه المرحلة، يمكنك أيضًا استخدام دمج الشركاء.

فيما يلي لمحة سريعة عن عملية الدمج الكاملة:

مستخدمو البيكسل الموجود

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

الموافقة العامة

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

البدائل

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

الإعداد

اختيار نوع الدمج

للبدء، حدد خيار الدمج الذي ترغب في تنفيذه:

تحديد الأحداث المطلوب إرسالها

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

خيارات الحدث

يمكنك إرسال الأحداث الأكثر صلة بنشاطك التجاري. يمكنك الاطلاع على قائمة كاملة بأحداث Meta القياسية والمخصصة.

معلمات الأحداث

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

يمكنك إضافة أنواع متعددة من المعرّفات إلى أحداثك، بما في ذلك event_id أو external_id أو order_id. من المهم معرفة الفرق بين هذه المعلمات:

حداثة البيانات

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

قد يؤدي إرسال الأحداث بعد أكثر من ساعتين من حدوثها إلى انخفاض ملحوظ في أداء الإعلانات المحسّنة لهذه الأحداث. بينما قد تواجه الأحداث التي يتم إرسالها بتأخير 24 ساعة أو أكثر مشكلات كبيرة في الإسناد وعرض الإعلانات المحسّن.

إذا كنت ترسل أحداثًا ذات فترات تحويل طويلة، فأرسل الحدث في أقرب وقت ممكن من الوقت الفعلي بالنسبة لنقطة اكتمال التحويل بالكامل.

انتقل إلى الخطوة التالية بمجرد توفر التالي:

• قائمة الأحداث المطلوب إرسالها.
• الحقول المحددة التي تريد إرسالها مع كل حدث.
• تحديد عدد المرات التي سترسل خلالها الأحداث.

أنواع التحسين المتوفرة

تقدم واجهة API التحويلات أنواع التحسين التالية:

التنفيذ

هناك طريقتان لتنفيذ الدمج:

• الدمج المباشر - تقوم، بصفتك معلنًا، بتنفيذ API التحويلات مباشرةً.
• الدمج كمنصة - تقوم، بصفتك شريك تسويق، بتقديم واجهة API التحويلات كخدمة لعملائك.

الدمج المباشر

الخطوة الأولى: إعداد المتطلبات

قبل استخدام واجهة API التحويلات، يجب إعداد الأصول التالية:

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

الخطوة الثانية: تنفيذ API

بمجرد الانتهاء من المتطلبات، ابدأ عملية التنفيذ. أثناء التطوير باستخدام واجهة API التحويلات، تحقق دائمًا من وثائق المطوّر.

الاستدعاءات الاختبارية (اختياري)

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

{
  "data": [
   {
    "event_name": "Purchase",
    "event_time": 1601673450,
    "user_data": {
      "em": "7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068",
      "ph": null
     },
    "custom_data": {
      "currency": "USD",
      "value": "142.52"
    }
   }
  ]
}

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": <FB-TRACE-ID>
}

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

انتقل إلى إرسال الأحداث والتحقق منها بمجرد أن تتحقق من أحداث الاختبار في مدير الأحداث.

إرسال الأحداث والتحقق منها

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

• استخدام API > إرسال الطلبات
• الأحداث المهملة
• وقت التحميل مقابل وقت معاملة الحدث
• الطلبات المجمعة
• التجزئة

بعد أن تبدأ في إرسال الأحداث، انتقل إلى مدير الأحداث وتأكد من استلامنا للأحداث التي أرسلتها. تعرف على كيفية التحقق من أحداثك.

إذا كان التنفيذ مكملاً لبيكسل متصفح، فانتقل إلى إعدادات إلغاء التكرار. بخلاف ذلك، فإن كل شيء جاهز! يمكنك الاطلاع على قسم الدعم إذا كانت لديك استفسارات.

الخطوة الثالثة: إضافة معلمات لإلغاء التكرار

إذا كنت ترسل أحداثًا متطابقة من البيكسل الخاص بك ومن خلال واجهة API التحويلات، فستحتاج إلى إعداد إلغاء التكرار للأحداث المُرسَلة عبر كلا القناتين. أولاً، اقرأ وثائق المطوّر لفهم منطق إلغاء التكرار.

إلغاء التكرار المستند إلى الأحداث

إذا وجدنا أن تركيبة مفاتيح الخادم نفسها (event_id، event_name) ومجموعة مفاتيح المتصفح (eventID، event) قد تم إرسالها إلى معرف بيكسل نفسه خلال 48 ساعة، فإننا نتجاهل الأحداث المكررة التي تم إرسالها مؤخرًا.

للمساعدة في ضمان إلغاء تكرار الأحداث:

• بالنسبة للأحداث المطابقة، تأكد من تعيين المعلمات التالية إلى القيمة نفسها:

  • event_id من حدث الخادم ثم eventID من حدث المتصفح
  • event_name من أحداث الخادم والمتصفح
• بعد إرسال أحداث مكررة، تحقق من مدير الأحداث لمعرفة ما إذا كان قد تم إهمال الأحداث الصحيحة.
• تأكد من أن كل حدث فريد يتم إرساله عبر كلٍ من البيكسل وواجهة API التحويلات له event_id خاص به. لا ينبغي مشاركة هذا المعرف مع الأحداث الأخرى.

بديل إلغاء التكرار المستند إلى الأحداث

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

الخطوة الرابعة الاختيارية: استكشاف ميزات مجموعة SDK الأعمال

تحتوي مجموعة SDK من Meta للأعمال على ميزات متقدمة مصممة خصيصًا لمستخدمي واجهة API التحويلات:

• الطلبات غير المتزامنة - استخدم هذه الميزة إذا كنت لا تريد حظر تنفيذ البرنامج لانتظار اكتمال الطلب. باستخدام هذا النهج، يمكنك تقديم طلبك واستلام إشارة من الخادم بمجرد اكتماله. أثناء انتظار الاستجابة، يمكن للبرنامج مواصلة التنفيذ.
• التجميع المتزامن - استفد من الطلبات غير المتزامنة لزيادة الإنتاجية من خلال استخدام الموارد بشكل أكثر كفاءة. يمكنك إنشاء طلبات مجمعة لدعم حالات الاستخدام مثل عناصر تشغيل طلبات الأحداث ومهام cron والمزيد.
• واجهة خدمة HTTP - تجاوز خدمة HTTP الافتراضية لمجموعة SDK للأعمال وتنفيذ خدمتك المخصصة باستخدام الطريقة أو المكتبة المفضلة لديك.

الدمج كمنصة

الإرشادات التالية مخصصة للشركاء الذين يقدمون واجهة API التحويلات كخدمة للمعلنين.

الخطوة الأولى: إعداد المتطلبات

يجب أن يحصل تطبيقك على الميزات والأذونات التالية:

• مستوى الوصول: الوصول المتقدم
• الميزة: الوصول القياسي لإدارة الإعلانات
• الأذونات: ads_management وpages_read_engagement وads_read.

الخطوة الثانية: إرسال الأحداث نيابةً عن العملاء

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

نهج ملحق Meta للأعمال (موصى به)

يقوم ملحق Meta للأعمال بإرجاع جميع المعلومات الضرورية اللازمة لإرسال الأحداث نيابةً عن العميل عبر العملية التالية. يوفر ملحق Meta للأعمال نقطة نهاية لاسترداد رموز وصول مستخدم النظام التي تم إنشاؤها في مدير الأعمال الخاص بالعميل. تتضمن هذه العملية أذونات لإرسال أحداث الخادم وتتم تلقائيًا وبطريقة آمنة.

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

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

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

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

يشارك العميل البيكسل مع مدير الأعمال الخاص بالشريك

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

الخطوة الثالثة: إسناد الأحداث إلى منصتك

لإسناد أحداث API التحويلات إلى منصتك، استخدم حقل partner_agent. يسمح لك هذا بتعيين معرف المنصة الخاص بك عند إرسال الأحداث نيابة عن العميل. إذا كنت شريكًا مدارًا، يمكنك التواصل مع ممثل Meta الذي تتعامل معه للاتفاق على معرف لمنصتك. يجب أن تكون هذه القيمة بتنسيق أقل من 23 حرفًا وأن تتضمن حرفين أبجديين على الأقل. بعد ذلك، يجب عليك إرساله مع كل حدث خادم.

الدعم

لكل الشركاء

راجع معلومات حول تصحيح الأخطاء ومقالات مركز مساعدة الأعمال.

للشركاء المُدارين

قدِّم المعلومات التالية لممثل Meta الذي تتعامل معه، حتى يتمكن من المساعدة في اختبار عمليات الدمج واستكشاف المشكلات وحلها: معرف مدير الأعمال، معرف التطبيق، معرفات بيكسل.

وثائق API

• بدء الاستخدام - اختبار API من مدير الأعمال الخاص بك
• استخدام API
• أفضل الممارسات - واجهة API التحويلات
• إعداد واجهة API التحويلات كمنصة
• أحداث Meta القياسية
• أحداث Meta المخصصة
• المعلمات
• أداة مساعدة حمولة البيانات
• خيارات معالجة البيانات لواجهة API التحويلات وواجهة API التحويلات بلا اتصال
• إذا كنت تريد تحسين أحداث التطبيق، فاستخدم واجهة API حدث التطبيق
• إذا كانت الأحداث تتعلق بمبيعات المتجر، فاستخدم واجهة API التحويلات بلا اتصال - الأحداث بلا اتصال التي لا تمثل مبيعات متاجر تكون مؤهلة لواجهة API التحويلات