3: تنفيذ المطوّر

هذه الصفحة تتعامل مع عمليات الدمج اليدوية وتتناول ما يلي:

• بناء حمولة البيانات من أجل دمج إدارة علاقات العملاء
• إنشاء رمز وصول وإعداد استدعاء API
• إرسال حمولة بيانات اختبارية
• إرسال بيانات الإنتاج

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

ستحتاج إلى صلاحية وصول مسؤول بمدير الأعمال لإكمال خطوات الدمج هذه. يمكنك الحصول على صلاحية الوصول من البريد الإلكتروني المُرسَل إليك إذا تمت دعوتك كمطور. بخلاف ذلك، اتصل بمسؤول مدير الأعمال لطلب صلاحية الوصول.

الخطوة الأولى: بناء حمولة بيانات

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

1. افتح دليل دمج إدارة علاقات العملاء من علامة التبويب الإعدادات في بيكسل إدارة علاقات العملاء للبدء.


2. راجع دليل مطوري واجهة API التحويلات لفهم كيفية عمل واجهة API التحويلات.


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


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

   الاسم	الوصف
   event_name string (سلسلة)	يمثل حقلًا نموذجيًا حرًا لالتقاط مراحل تجميع بيانات العملاء المحتملين التي تستخدمها ضمن إدارة علاقات العملاء. يجب أن تشير المعلمة event_name إلى وجود بيانات عميل محتمل تتحرك عبر مسار المبيعات في برنامج إدارة علاقات العملاء. تأكد من إرسال جميع المراحل فور تحديثها، بما في ذلك العميل المحتمل الأولي.
   event_time integer (عدد صحيح)	يمثل طابعًا زمنيًا بتنسيق Unix بالثوان يشير إلى وقت تحديث حدث تحديث مرحلة بيانات العميل المحتمل بواسطة إدارة علاقات العملاء. يجب أن يحدث الطابع الزمني بعد وقت تجميع بيانات العملاء المحتملين وإلا فقد يتم تجاهل الحدث.
   action_source string (سلسلة)	القيمة:system_generated (بمجرد استخدام واجهة API التحويلات، فإنك توافق على أن المعلمة action_source دقيقة حسب معلوماتك.)
   lead_id integer (عدد صحيح)	يمثل leadgen_id المكون من 15 أو 16 رقمًا من بيانات العملاء المحتملين الذين تم تنزيلهم.
   lead_event_source string (سلسلة)	يمثل اسم إدارة علاقات العملاء الذي تأتي منه الأحداث.
   event_source string (سلسلة)	القيمة:crm

   
   
   مثال
   قد يبدو المثال على حمولة البيانات كالتالي. ملاحظة: يجب أن تستخدم lead_id صالح وإلا سيرفض النظام الحدث.

   {
       "data": [
           {
               "event_name": "initial_lead",
               "event_time": 1629424350,
               "action_source": "system_generated",
               "user_data": {
                   "lead_id": 525645896321548
               },
               "custom_data": {
                   "event_source": "crm",
                   "lead_event_source": "salesforce"
               }
           }
       ]
   }
   
   



5. إذا كانت الأحداث لا تتبع مواصفات حمولة البيانات أو لا تطابق إعلانات تجميع بيانات العملاء المحتملين من Meta، فلن يتم التعرف عليها لإجراء عملية الدمج ولن يتم استخدامها في تدريب النموذج.
   على سبيل المثال، ستُقبَل حمولة بيانات الويب من قِبل واجهة API التحويلات وتظهر في مدير الأحداث، ولكن لن يتم الاعتراف بها لعملية الدمج هذه. يجب عليك أيضًا استخدام lead_id صالح وإلا سيرفض النظام الحدث.
   لن يتم التعرف إلا على حمولة بيانات العملاء المحتملين نتيجة التحويل من أجل إجراء عملية الدمج واستخدامها في التدريب.

الخطوة الثانية: إنشاء رمز وصول واستدعاء واجهة API

بمجرد تكوين ما سترسله، تتمثل الخطوة التالية في تكوين المكان الذي سترسل إليه البيانات.

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

1. يمكنك العودة إلى دليل دمج إدارة علاقات العملاء من علامة التبويب الإعدادات في بيكسل إدارة علاقات العملاء.


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


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


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

   https://graph.facebook.com/API_VERSION/PIXEL_ID/events?access_token=ACCESS_TOKEN

   • API_VERSION: إصدار واجهة API التسويق الحالي
   • PIXEL_ID: يمكن الحصول على معرف البيكسل من مدير الأحداث لكل بيكسل
   • ACCESS_TOKEN: رمز الوصول المُنشأ أعلاه
5. يمكنك الاطلاع على إصدار واجهة API التسويق وتواريخ انتهاء الصلاحية في مستندات إصدار API. تأكد من تحديث إصدار API أو مجموعة SDK للأعمال من Meta في الرمز قبل تاريخ انتهاء صلاحية واجهة API التسويق. يمكن أن يؤدي استخدام إصدار تم إيقاف استخدامه في الرمز إلى وجود أخطاء وقد يتم تجاهل أحداثك بواسطة النظام.

الخطوة الثالثة: اختبار حمولة بيانات (اختياري)

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

1. في قسم اختبار أحداث الخادم، انقر على الرابط مستكشف Graph API. سيؤدي استخدام هذا الرابط الفريد إلى ملء بعض المعلومات من البيكسل. (يمكنك أيضًا الوصول مباشرة إلى مستكشف Graph API إذا أردت ذلك.) دوِّن قيمة test_event_code، التي يمكن أن تتغير بمرور الوقت.


2. أكمل ما يلي في أداة مستكشف Graph API:
   1. تأكد من أنك في وضع POST.
   2. تأكد من صحة كل من إصدار واجهة API ومعرف البيكسل.
   3. انتقل إلى عرض JSON.
   4. أدخِل حمولة بياناتك. يمكن إنشاء حمولة البيانات هذه يدويًا أو باستخدام أداة مساعدة حمولة البيانات. تأكد من تضمين المعلمة test_event_code من الخطوة السابقة وlead_id صالح.
3. أدخِل رمز وصول بيكسل، وانقر على زر إرسال.


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


5. يجب أن يظهر الحدث الاختباري تحت علامة التبويب الأحداث الاختبارية في مدير الأحداث بعد وقت قصير.

الخطوة الرابعة: إرسال بيانات الإنتاج

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

1. أرسِل lead_id بدلاً من معلومات تحديد الهوية الشخصية (PII) للمطابقة.


2. تأكد من إرسال جميع مراحل تجميع بيانات العملاء المحتملين فور تحديثها، بما في ذلك حدث بيانات العملاء المحتملين الأوليين الذي يمثل جميع بيانات العملاء المحتملين الذين تم إنشاؤهم على Meta وتم تنزيلهم في إدارة علاقات العملاء. فيما يلي مثال على المسار. تم تحديد أسماء الأحداث ومراحلها من قِبل المُعلِن لذا لا يلزم مطابقة هذا المثال.
   
   
   
   إذا كانت حملاتك الإعلانية تولِّد 100 عميل محتمل، فسوف نتوقع تحميل 100 حدث "عميل محتمل أولي" لتمثيل المرحلة الأولى من تجميع بيانات العملاء المحتملين. وبإرسال المرحلة الأولى من تجميع بيانات العملاء المحتملين سيعلم النظام أنه تم استقبال بيانات العملاء المحتملين وتمت معالجتها. بينما تتحرك بيانات العملاء المحتملين إلى أسفل مسار المبيعات، نتوقع تحميل 70 "عميل محتمل مؤهل للتسويق"، و30 "فرصة مبيعات"، و15 مرحلة "محوّلة".
   
   باختصار، تم إنشاء 100 عميل محتمل من الحملات الإعلانية، ولكننا نتوقع تحميل 215 حدثًا في هذا السيناريو.


3. قم بإنشاء وظيفة لاسترداد التحديثات من واجهة API الخاصة بإدارة علاقات العملاء أو قاعدة البيانات بمجرد تحديث حالة العميل المحتمل. ثم أرسل حمولة البيانات إلى واجهة API التحويلات من Meta باستخدام وظيفة مخصصة أو مجموعة SDK للأعمال من Meta. ستعتمد مدى منطقية عملية الدمج على إدارة علاقات العملاء وتكوين قاعدة البيانات لديك.
   
   يوصى بالمتغيرات من أجل:
   • lead_id
   • event_name
   • event_time
   على سبيل المثال، قد تبدو حمولة البيانات التي تنص صراحة على قيم المعلمات كما يلي:

   {
     "event_name": "initial_lead",
     "event_time": 1628294742,
     "user_data": {
       "lead_id": 1234567890123456
     },
     "action_source": "system_generated",
     "custom_data:" {
       "lead_event_source": "Salesforce",
       "event_source": "crm"
     }
   }
   

   بينما قد تبدو حمولة البيانات التي تمرر القيم من قاعدة بياناتك باستخدام المتغيرات كما يلي:

   {
     "event_name": lead_stage // "initial_lead"
     "event_time": unix_time // 1628294742
     "user_data": {
       "lead_id": fb_lead_id // 1234567890123456
     },
     "action_source": "system_generated",
     "custom_data:" {
       "lead_event_source": "Salesforce",
       "event_source": "crm"
     }
   }
   



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


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


6. يمكنك إعادة تعبئة بياناتك لمدة تصل إلى آخر 7 أيام. ويتم حساب الفرق الزمني بين event_time وupload_time. إعادة تعبئة بعض البيانات قد تسرع من عملية التدريب.

   تحذير: لا تحاول إعادة تعبئة أكثر من 7 أيام من البيانات عن طريق تعديل قيم event_time. يعتمد النموذج على طابع زمني دقيق للتحسين. وإجراء ذلك قد يتسبب في تجاهل جميع بياناتك التي تمت تعبئتها.

7. تأكد من أن قيم event_time بعد الطابع الزمني لتوليد العملاء المحتملين، وإلا قد يتم تجاهل أحداثك.


8. من المفترض أن تبدأ في رؤية الأحداث تظهر في مدير الأحداث الخاص بالبيكسل في غضون ساعة إذا كانت عملية الدمج تعمل على تحميل الأحداث إلى Meta. تذكر استخدام lead_id صالح في حمولات البيانات حتى تظهر الأحداث. افتح كل حدث تم إرساله لدمج إدارة علاقات العملاء الخاصة ببيانات العملاء المحتملين الواردة من التحويل في مدير الأحداث وتأكد من تعبئة المعلمات المخصصة lead_event_source وevent_source. إذا لم يكن الحدث يحتوي على هذه المعلمات، فلن يتم تسجيله كحدث لبيانات العملاء المحتملين الواردة من التحويل.
   
9. سيتحقق النظام مما إذا كانت أي من أحداثك صالحة كأحداث لبيانات العملاء المحتملين الواردة من التحويل. بعد يوم واحد، ستظهر علامة صح خضراء بجوار خطوة إرسال حدث إدارة علاقات العملاء الخاصة بعملية الدمج إذا تم اكتشاف حدث صالح.