دليل الترحيل: من ملحق MBE بالإصدار 2 إلى ملحق MBE بالإصدار 3

يوضح هذا الدليل التغييرات المطلوبة لترحيل تطبيقات الأعمال الحالية التي تستخدم ملحق Meta للأعمال (MBE، بالإصدار 2) بحيث تكون متوافقة مع ملحق MBE بالإصدار 3. من الآن فصاعدًا، سيتطلب ملحق MBE هذه التحديثات ولن يتوافق مع الإصدارات التي تسبق الإصدار التالي من Graph API.

المزايا الرئيسية لملحق MBE بالإصدار 3

من خلال ملحق MBE بالإصدار 3، يمكن لمطوّري التطبيقات التابعة لجهة خارجية:

1. توفير تدفقات إعداد أبسط للأنشطة التجارية.

2. المساعدة في الحد من توقف العملاء عن الاستخدام.

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

4. استيعاب أنوع متعددة من الأنشطة التجارية ضمن عملية دمج ملحق FBE. على سبيل المثال، يمكن أن يوفر أي تطبيق جهة خارجية نوعًا واحدًا من الدمج لمجموعة فرعية من الأنشطة التجارية التي لا تتطلب سوى أدوات المعلنين، في حين يوفر بشكل منفصل نوعًا آخر من الدمج للأنشطة التجارية التي لا تتطلب سوى أدوات المراسلة.

قبل البدء

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

نظرة عامة

المصطلحات

الميزة: دمج محدد يمكنه توفير نتائج للأنشطة التجارية لديك. وترتبط كل عملية دمج بمتطلبات تنفيذ فريدة، ويمكنك تعيين الميزات التي تريد تمكينها. يمكن أن تتضمن الأمثلة page_cta وchat_plugin وهكذا. للحصول على قائمة كاملة، راجع قائمة الميزات هذه.

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

النية: يُعد مصطلح "النية" اسمًا في ملحق MBE لحالة استخدام معينة. على سبيل المثال، تٌعد نية CATALOG_ADS اسم حالة الاستخدام التي تسمح لتطبيقك بتشغيل إعلانات الكتالوج، لمزامنة منتجات وخدمات الكتالوج والترويج لها. تظهر النوايا في قائمة الميزات ويتم تعيينها إلى مجموعة من الميزات المتعددة التي يحصل عليها النشاط التجاري.

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

للحصول على قائمة كاملة، راجع قائمة النوايا حسب المجال هذه.

الفروق الرئيسية بين الإصدار 2 والإصدار 3

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

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

التوصيات

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

1. احتفظ بقائمة الميزات التي تم تمكينها والأصول المرتبطة بها.
2. قم بالمزامنة مع واجهات API من Meta لضمان تحديث سجل الميزات التي تم تمكينها والتأكد من دقته.

المتطلبات

يتيح ملحق MBE بالإصدار 3 لمستخدم النشاط التجاري إجراء ما يلي:

• الاشتراك في المجموعة الفرعية لميزات تطبيقك الملاءمة له

• إضافة الميزات أو إزالتها بمرور الوقت، بشكل مستقل عن الميزات الأخرى

نتيجة لذلك، تحتاج عملية دمج التطبيق إلى:

1. الاستجابة إلى التحديثات. وسيتم إرسال حدث webhook في كل مرة يمر النشاط التجاري عبر التدفق أو يتم تحديث الميزات التي تم تمكينها لدى النشاط التجاري.

2. بمجرد تلقي حدث webhook، تحقق من الميزات التي تم تمكينها من خلال استدعاء API تثبيت ملحق FBE. وفي كل مرة يمر نشاط تجاري عبر التدفق، يمكنه تمكين الميزات أو تعطيلها.

3. ضمن المنصة لديك، قم بتحديث سجل الميزات التي تم تمكينها لهذا النشاط التجاري.

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

يجب ألا يفترض تطبيقك أنه سيتم إرجاع جميع الأصول التي يدعمها التطبيق. على سبيل المثال:

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

• بإمكان النشاط التجاري الذي يقوم بإعداد موجز تحويلات لتحسين أداء الإعلان القيام بذلك دون إعداد زر دعوة لاتخاذ إجراء (CTA) في الصفحة أو Instagram. ويجب ألا يطالب تطبيقك النشاط التجاري بإعداد صفحة أو حساب Instagram لتمكين هذه الميزة.

تحديث الدمج إلى الإصدار 3

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

الخطوة الأولى: إعداد الميزات والاستجابة إلى التحديثات

• تحديث تدفقات Webhook: استجب إلى أحداث webhooks التي تشير إلى قيام نشاط تجاري محدد بتحديث مجموعة الميزات التي يريد تمكينها.

• تحديث الدمج من خلال API تثبيت ملحق FBE: يمكنك اكتشاف الميزات التي قام النشاط التجاري بتمكينها عن طريق استدعاء API تثبيت ملحق FBE وتحديث السجلات.

• تحديث الدمج من خلال API تكوين الميزة: يمكنك تكوين كل ميزة واستدعاء API تكوين الميزة لسحب معلومات إضافية حول كل ميزة عند الاقتضاء.

الخطوة الثانية: تكوين الميزات التي يدعمها التطبيق

الميزات التي يتم عرضها للتجار في قائمة الميزات هي تلك التي تقوم بتكوينها ضمن لوحة مطوّر ملحق MBE.

الخطوة الثالثة: تكوين المجالات

عند تكوين المجالات، تأكد من إرسال المجال المناسب لكل نشاط تجاري في تكوين الإضافات ضمن business_vertical. على سبيل المثال، إذا كان صالونًا لتصفيف الشعر، فأرسل ‘APPOINTMENTS’. إذا كان متجرًا يبيع المنتجات، فأرسل ‘ECOMMERCE'.

إذا كان النشاط التجاري ينتمي إلى أكثر من مجال واحد، فأرسل مجالات مختلفة لكل نقطة دخول على النظام (حسب الهدف الذي يحاول النشاط التجاري تحقيقه). على سبيل المثال، إذا كان صالون تصفيف الشعر يوفر إمكانية حجز مواعيد تصفيف الشعر وكذلك يبيع منتجات الشعر، فيمكنك إرسال ‘APPOINTMENTS’ من نقطة الإدخال 1 وإرسال ‘ECOMMERCE’ من نقطة الإدخال 2. يجب أن يكون لكل نقطة إدخال ميزات خاصة لكل مجال يتم تكوينها للعمل بشكل صحيح.

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

الخطوة الرابعة: تغييرات واجهة المستخدم

يعرض دفق التأهيل المحدث (الحد الأدنى للتأهيل) "قائمة ميزات" تعرض قائمة بالنوايا التي تمثل حزمًا من ميزة واحدة أو أكثر من ميزة قد قمت بتمكينها للأنشطة التجارية. يمكن للأنشطة التجارية تحديد النوايا التي تريد تثبيتها. إذا كنت ترغب في أن يقوم النشاط التجاري بتثبيت نية محددة أولاً ثم عرض قائمة الميزات، فيمكنك إدخال المعلمة intent في كائن الإعداد. يمكنك الاختيار من قائمة النوايا لهذه المعلمة. إذا كنت تريد إجراء تجربة حول تحديث واجهة المستخدم أو لا تريد واجهة المستخدم المحدثة الجديدة هذه، فإن المعلمة use_minimal_onboarding، في كائن flow_config تحدد واجهة المستخدم المطلوب عرضها. سيؤدي تعيين Use_minimal_onboarding إلى false إلى الاحتفاظ بواجهة مستخدم ملحق MBE بالإصدار 2.

الخطوة الخامسة: عرض الإدارة

يُظهر عرض الإدارة بالإصدار 3 جميع الميزات التي قام النشاط التجاري بتثبيتها ويربطها بتثبيت المزيد من الميزات. تم تحديث الرابط إلى "عرض الإدارة" ليصبح:

<a href=”https://business.facebook.com/latest/business_app_store/manage_external_business_connection?asset_id=<page_id>&business_id=<business_id>&app_id=<app_id>&external_business_id=<external_business_id>"><button>Launch Management View</button></a>

الخطوة السادسة: تمكين تغييرات الميزات

لتمكين تغييرات الميزات هذه، تم تحديث واجهات API التالية:

تحديثات Webhook

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

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

الاستجابة

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    instagram_profiles": [
"<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            “additional_info”: {
               “onsite_commerce_eligible”: bool
            }
        }
    
  }]
}

حقول الاستجابة

تحديثات API تثبيت ملحق FBE

يرسل نموذج API المحدث قائمة بكل ميزة قام النشاط التجاري بتمكينها والأصول المرتبطة بكل ميزة. ويتمثل التغيير الأساسي في إضافة الحقل installed_features. كما تُعد حمولة البيانات هذه هي نفسها الواردة في استجابة Webhook.

بعد تلقي حدث webhook، اتبع الخطوات التالية الموصى بها:

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

2. قم بتمكين هذه الميزات لهذا النشاط التجاري (تتوفر تفاصيل حول معنى "التمكين" في جدول قائمة الميزات)، واسحب أي معلومات إضافية مطلوبة حول الميزات من API تكوين الميزة.

تعرض عينة الرمز التالية مثالاً على طلب يتم إرساله إلى API تثبيت ملحق FBE واستجابة API المقابلة. ويتم تمييز الحقول الإضافية للإصدار 3 ضمن الاستجابة.

الطلب

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

الاستجابة

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
<!--UPDATES BELOW-->
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            “additional_info”: {
               “onsite_commerce_eligible”: bool
            }
        }
    ]
  }]
}

تحديثات استجابة API تكوين الميزة

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

بالنسبة إلى الميزات غير القابلة للتخصيص الموضحة في قائمة الميزات، يتم عرض معرف مثيل الميزة والتمييز الممكّن فقط. ولا يمكنك سوى تحديث الميزات القابلة للتخصيص من خلال إجراء طلب POST.

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

القراءة

يمكنك قراءة حالة تكوين الميزة الحالية الخاصة بأي نشاط تجاري من خلال إجراء الطلب التالي:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

التحديث

لتحديث كل الميزات، استخدم الطلب POST التالي:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

الاستجابة

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

الاختبار

قبل الاختبار، أرسل إلى ممثل Meta لديك ما يلي:

1. الميزات التي تريد تمكينها.

2. معرفات المستخدم للأفراد الذين سيختبرون الدفق.

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

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

لاختبار تغييرات الإصدار 3 هذه، يجب المرور عبر دفق إعداد والتأكد من الآتي:

1. استلام حدث webhook عند إكمال عملية التثبيت وإلغاء التثبيت.

2. احتواء حدث Webhook وAPI التثبيت وAPI تكوين الميزة على التحديثات المذكورة أعلاه (تعرض بدقة الميزات المثبتة وغير المثبتة).

3. أن قائمة الميزات تعرض الميزات التي تريد من الأنشطة التجارية لديك تثبيتها (حسب المجال).

يمكنك اختبار دفق التأهيل عن طريق:

1. مراجعة تسجيل دخول الأعمال.

2. مراجعة تطبيقات الأعمال (إن أمكن)

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

قائمة الميزات

يوفر ملحق MBE بالإصدار 3 الميزات التالية التي يمكنك تمكينها لأنشطتك التجارية. يمكن إدخال كل هذه الميزات عبر API تثبيت ملحق FBE (أثناء دفق التثبيت)، ولكن كما هو موضح في الجدول، لا يمكن تكوين جميع الميزات عبر API تكوين الميزة (بعد أن يقوم التاجر أو المعلن بتثبيت ملحق MBE بالفعل).

عينة من الرمز في messenger_chat

<div class="fb-customerchat"
            page_id=PAGE_ID 
</div>

قائمة المجالات

يمكنك تحديد المجال (المجالات) الذي ينتمي إليه تطبيقك:

النوايا (حالات الاستخدام) حسب المجال

الإعلانات

التصميم

التجارة الإلكترونية

الموعد

الحجوزات

الأطعمة والمشروبات

إعلانات تجميع بيانات العملاء المحتملين

القياس والتحسين

دمج البيانات