الحصول على معرفات الأصول ورمز الوصول

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

من خلال حل الإنابة (OBO)، بإمكان العميل الحصول على رمز الوصول باستخدام رمز وصول مستخدم النظام لدى مسؤول مدير الأعمال الشريك أيضًا، بدلاً من رمز وصول مسؤول مدير الأعمال التابع للعميل فقط.

تجميع المعرفات لنقاط نهاية API وعمليات تكوين الأنشطة التجارية

فيما يلي كيفية الحصول على هذه المعلومات:

• يلزم توفير—حدث Webhook لكل شركاء المنصات الذين يريدون أن يتم إدراجهم في App Store
• يقوم ملحق FBE بتثبيت نقطة نهاية API—موصى به للأنشطة التجارية التي تتم استضافتها ذاتيًا

إنشاء مستخدم النظام

بمجرد أن ينتهي المستخدم من تثبيت ملحق FBE، ينشئ الملحق مستخدم نظام للموظف في مدير الأعمال التابع للعميل. وتتبع تسمية مستخدم النظام الجديد هذا المخطط {App Name} System User (FBE).

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

تتوفر لدى مستخدم النظام هذا الأذونات اللازمة للوصول إلى جميع أصول ملحق FBE المرتبطة بأذونات المهام التالية:

1. الصفحة: 'MANAGE'
2. الحساب الإعلاني: 'MANAGE'
3. الكتالوج: 'MANAGE'
4. البيكسل: 'EDIT'

الحصول على رمز مستخدم النظام عبر API

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

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

بالنسبة للحقل scope، استخدم الإذن manage_business_extension، ولكن قد تحتاج أيضًا إلى ads_management أو catalog_management حسب حالة الاستخدام.

بالنسبة للحقل access_token، يمكنك إدخال رمز وصول المستخدم (user_access_token) أو رمز وصول مستخدم النظام لمسؤول مدير الأعمال الشريك (partner_bm_admin_system_user_token). تعرف على المزيد حول رمز وصول النشاط التجاري.

حدث Webhook

لتلقي تحديثات فورية بشأن عمليات تثبيت ملحق FBE وإلغاء تثبيته وإعادة تكوينه، يتم إرسال أحداث Webhook في كل مرة يقوم فيها النشاط التجاري بتثبيت ملحق FBE أو تعديله أو إلغاء تثبيته.

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

متطلبات الإعداد

1. أنشئ نقطة نهاية على خادم آمن يمكنه معالجة الطلبات من جانب فيسبوك: طلبات التحقق (GET) وإشعارات الأحداث (POST).
2. يمكنك تكوين اشتراك أحداث webhooks لملحق FBE في لوحة معلومات التطبيق:
   • في قسم ملحق فيسبوك للأعمال ضمن لوحة معلومات التطبيق، انتقل إلى علامة تبويب الإعداد، ومرّّر لأسفل نحو البطاقة Webhooks، ثم انقر على تعديل عنوان URL للاستدعاء.
   • أدخل عنوان URL لنقطة النهاية في الحقل عنوان URL للاستدعاء وأدخل سلسلة في الحقل التحقق من الرمز. سنقوم بتضمين هذه السلسلة في كل طلبات التحقق.
   • بمجرد النقر على التحقق والحفظ، سنرسل إلى نقطة النهاية طلب تحقق يجب عليك أن تتحقق من صحته.
   • سيتم الاشتراك تلقائيًا في حدث webhook لـ fbe_install. تتضمن البطاقة أيضًا مفتاح تبديل والذي يمكن استخدامه لإلغاء تنشيط الاشتراك إذا دعت الحاجة.

تحليل أحداث Webhook

في كل مرة يتم تلقي حدث webhook التثبيت، يتعين على تطبيقك تنفيذ الإجراءات التالية.

بالنسبة إلى عمليات التثبيت الجديدة

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

بالنسبة إلى عمليات التثبيت الحالية

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

تحليل حدث Webhook لحالات إلغاء التثبيت

قم بإجراء الخطوات التالية عند إلغاء التثبيت:

1. تعطيل الميزات التي يعمل التطبيق على تنفيذها لهذا النشاط التجاري.
2. إبلاغ النشاط التجاري بالتغيير الذي حدث في التكوين.

محتويات حمولة بيانات حدث Webhook

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

المثال — حمولة البيانات تتضمن الحقل onsite_commerce_eligible بالقيمة المنطقية

{
  "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
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

API تثبيت ملحق FBE

بالنسبة لأي نشاط تجاري قام بتثبيت ملحق FBE، يمكنك الاستعلام عن معلومات التثبيت الأساسية (pixel_id وقائمة بالملفات الشخصية من خلال IG Business ID and/or Page ID) باستخدام نقطة النهاية التالية:

مثال

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": [{
    "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
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

تتضمن الاستجابة الحقول التالية. يمثل هذا الآن مصدر تجميع البيانات في الأصول المرتبطة ضمن القائمة "installed_features":

استجابة 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,
    },
  ],
  ...
}

الخطوات التالية

• تكوين ميزات النشاط التجاري
• تشغيل أحداث البيكسل
• تحديث الكتالوج لديك