إعداد التصميم من خلال ملحق FBE

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

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

المثال — دفق الإعداد من جهة الشريك (تسجيل دخول النشاط التجاري)

قبل البدء

1. سجّل كمطوّر فيسبوك للوصول إلى أدوات المطوّرين وإنشاء تطبيقات فيسبوك.

2. إذا لم تقم بذلك حتى الآن، فأنشئ تطبيق Meta.

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

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

5. الأذونات/الإمكانية الخاصة:

• manage_business_extension — الوصول إلى ملحق فيسبوك للأعمال. بمجرد منح هذه الإمكانية لتطبيقك، يمكنك العثور على لوحة مطوّر ملحق FBE ضمن المنتجات.

• Business_creative_asset_management — الوصول إلى واجهات api إدارة الأصول المتعلقة بالتصميم. بعد الحصول على هذه الإمكانية، يمكنك الحصول على إمكانية الوصول إلى الأذونات التالية:

  • business_creative_insights: يمكن الوصول إلى رؤى أصول عناصر تصميمات النشاط التجاري.

  • business_creative_management: يمكن السماح لتطبيقك بإنشاء مجلدات جديدة وتعديلها ومشاركتها وتحميل أصول لها ضمن سياق كيان نشاطك التجاري الخاص.

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

بعد إكمال مراجعة التطبيقات

إنشاء رمز وصول شريك:

• يمكنك إنشاء رمز وصول مستخدم نظام مسؤول ضمن مدير الأعمال عن طريق اتباع هذه الإرشادات.

• تأكد من أن هذا الرمز يتضمن الأذونات business_creative_insights وbusiness_creative_management وbusiness_management المحددة في خطوة 'النطاقات المتوفرة'.

تنفيذ الزر 'إرسال تصميمي إلى Facebook'

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

نوصي باستخدام نهجين للقيام بذلك:

1. (على الأقل) يتمتع المستخدم بخيار اختيار مجلد عالي المستوى أو إنشائه فقط. وضمن سياق النشاط التجاري المحدد، يمكنك الاستعلام عن كل المجلدات عالية المستوى التي يتمتع المستخدم بالوصول إليها. واطلب من المستخدم اختيار مجلد عالي المستوى موجود أو إنشاء مجلد جديد. كما يمكن للمستخدمين تحديد اسم المجلد أو استخدام اسم المجلد الافتراضي <YourBusinessName>_<UserBusinessName>_<UserName>. ويمكنك تحميل الأصول إلى المجلد عالي المستوى المحدد أو الجديد. ويتطلب هذا النهج أقل عمل لواجهة مستخدم ويمكن العثور على تفاصيل واجهة API في الخطوة الثالثة أدناه.

2. (اختياري) يتحكم المستخدم في انتقال المجلد والمجلد الفرعي بشكل كامل. وضمن سياق النشاط التجاري المحدد، يمكنك الاستعلام عن كل المجلدات عالية المستوى التي يتمتع المستخدم بالوصول إليها واطلب من المستخدم اختيار مجلد عالي المستوى موجود أو إنشاء مجلد جديد. وبالنسبة لمجلد جديد، يمكنك أن تتطلب من المستخدم تسمية المجلد أو استخدام الاسم الافتراضي <YourBusinessName>_<UserBusinessName>_<UserName>. كما أنه ضمن المجلد عالي المستوى المحدد، يتمتع المستخدم بخيار الانتقال إلى مجلد فرعي موجود أو إنشاء مجلد فرعي جديد أو تحميل الأصول. وباستخدام هذا الخيار، ستحتاج إلى تنفيذ انتقال المجلد في واجهة المستخدم. ويمكن العثور على إرشادات دمج واجهة API في الخطوة الثالثة والخطوة الرابعة أدناه.

فيما يلي الخطوات المحددة المطلوبة لتنفيذ هذا الدفق:

1. تنفيذ ملحق Facebook للأعمال
2. الحصول على سياق النشاط التجاري
3. تحديد مجلد عالي المستوى أو إنشاؤه
4. تحديد مجلد فرعي أو إنشاؤه
5. تحميل الصور/مقاطع الفيديو
6. طلب مشاركة المجلد معك (اختياري)
7. عرض رؤى الصور/مقاطع الفيديو (اختياري)

1. تنفيذ ملحق Facebook للأعمال

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

لمطالبة دفق التصميم:

• مرّر channel: CREATIVE وbusiness_vertical وCREATIVE ضمن الإعداد.
• استخدام الإذنين business_creative_management وbusiness_creative_insights

  • يلزم توفيرهما للاستعلام عن معرفات الأنشطة التجارية وإنشاء المجلدات وتحميل أصول التصميم إلى المجلد
• (اختياري) استخدام الإذن business_creative_insights_share

  • يمكن السماح للمستخدم بمشاركة المجلد معك بإذن المهمة VIEW_INSIGHTS

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

التكوينات المطلوبة

الإضافات

الإعداد

يمكنك استخدام هذا الكائن لتحديد إعدادات حضور المستخدم النهائي على فيسبوك

تكوين النشاط التجاري

استخدم هذا الكائن لتكوين إعدادات النشاط التجاري للمستخدم النهائي. يتمضن ذلك أزرار الدعوات لاتخاذ إجراء (CTA) وبطاقة الخدمات والمزيد. يتضمن كل حقل "نوعًا" مرتبطًا بالجداول المعنية أدناه.

FBEBusinessPropertiesConfigData

استخدم هذا الكائن لتكوين أسماء الأنشطة التجارية.

2. الحصول على سياق النشاط التجاري

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

3. تحديد مجلد عالي المستوى أو إنشاؤه

يمكن للمستخدمين تحميل الأصول إلى المجلد عالي المستوى أو إنشاء مجلدات فرعية ضمن المجلد عالي المستوى.

أولًا، تحقق من المجلدات عالية المستوى التي يحتوي المستخدم على أذونات لها للمهمة CREATE_CONTENT من خلال إجراء طلب إلى نقطة النهاية <business_id>/creative_folders (قيد التطوير).

الحصول على مجلد عالي المستوى من النشاط التجاري للمستخدم

الطلب

curl -X GET \
    -F 'access_token={user-access-token}' \
https://graph.facebook.com/<API_VERSION>/<user_business_id>/creative_folders?filtering=[{field:"permitted_tasks", operator: "EQUAL", value:"create_content"}]

الاستجابة

{
 "id": "<folder_id>"
}

اطلب من المستخدم اختيار مجلد عالي المستوى موجود أو إنشاء مجلد عالي المستوى جديد ضمن سياق مدير أعمال المستخدم. بالنسبة لمجلد عالي المستوى جديد، يمكنك أن تتطلب من المستخدم تسمية المجلد أو استخدام <YourBusinessName>_<UserBusinessName>_<UserName> افتراضيًا. وإذا شارك المستخدم المجلد مرة أخرى معك، فسيصبح مرئيًا لنشاطك التجاري والنشاط التجاري للمستخدم في مكتبة أصول Facebook.

الحصول على طلب معلومات حول النشاط التجاري للمستخدم

الطلب

curl -X GET \
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>

الاستجابة

{
 "id": {business-id}
 "name": {user-business-name}
}

إنشاء طلب مجلد عالي المستوى

الطلب

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

الاستجابة

{
 "id": {top-level-folder-id}
}

4. تحديد مجلد فرعي أو إنشاؤه

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

الحصول على مجلد فرعي

• يتطلب الإذن business_creative_management

الطلب

curl -X GET \
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<parent_folder_id>/subfolders?fields=name

الاستجابة

{
 "data": [
   {
     "name": "<subfolder_name>",
     "id": "<subfolder_id>"
   }
 ]
}

إنشاء مجلد فرعي

• يتطلب الإذن business_creative_management

الطلب

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F "parent_folder_id={parent-folder-id}"
    -F 'access_token={user-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

الاستجابة

{
    "id": {sub-folder-id}
}

يمكن حذف المجلد والمجلد الفرعي من خلال إرسال طلب DELETE إلى نقطة النهاية <folder_id> أو <subfolder_id>.

5. تحميل الصور ومقاطع الفيديو إلى مجلد فرعي

يمكنك تحميل أصول تصميم المستخدم إلى المجلد الفرعي.

• يتطلب الإذن business_creative_management

تحميل الصور

الطلب

curl -X POST \
    -F 'bytes={image-content-in-bytes-format}' \
    -F 'name={image-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    https://graph.facebook.com/{version}/{business-id}/images

الاستجابة

{
    "images":{
         "{image-name}":{
             "id":"{business-creative-image-id}",
             "hash":"{hash}",
             "url":"{image-url}"
         }
    }
}

تحميل مقاطع الفيديو

يمكنك تحميل فيديو في طلب واحد إذا كان حجمه أقل من بضعة وحدات ميجابايت أو تحميله على أجزاء (راجع القسم التالي أدناه). وقم بإجراء استدعاء واجهة API لتحميل الفيديو من خلال graph-video.facebook.com بدلًا من graph.facebook.com.

المثال — أرسل POST إلى {business-id}/video وقم بتضمين اسم الفيديو والمصدر ومعرف المجلد الفرعي.

الطلب

curl -X POST \
    -F 'name={video-name}' \
    -F 'source='@{video-path}'' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    https://graph-video.facebook.com/{version}/{business-id}/videos

الاستجابة

{
  "success": true,
  "business_video_id": "<business_video_id>"
}

تحميل مقاطع الفيديو المجزأة

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

لإجراء طلب بدء وإنشاء جلسة تحميل فيديو، أرسل طلب POST إلى /{business-id}/videos وقم بتعيين الحقل upload_phase للبدء وحدد file_size بوحدات البايت

الطلب

curl -X POST \
 -F 'title={video-name}' \
 -F 'creative_folder_id={subfolder-id}' \
 -F 'access_token={user-access-token}' \
 -F 'upload_phase=start' \
 -F 'file_size={video_file_size_in_bytes}' \
 https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

الاستجابة

{
    "upload_session_id": "{session-id}",
    "video_id": "{video-id}",
    "start_offset": "0",
    "end_offset": "52428800"
}

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

المثال: إرسال الجزء الأول

الطلب

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    -F 'upload_phase=transfer' \
    -F 'upload_session_id={session-id}' \
    -F 'start_offset=0' \
    -F 'video_file_chunk=@{binary-chunk-filename}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

الاستجابة

عند النجاح، نستجيب بإزاحات للجزء التالي

{
  "start_offset": "52428800", //Start byte position of the next file chunk
  "end_offset": "104857601" //End byte position of the next file chunk
}

قم بقص الجزء التالي وتحميله بالنطاق [52428800، 104857601] من الملف وأرسله:

الطلب

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    -F 'upload_phase=transfer' \
    -F 'start_offset=52428801' \
    -F 'upload_session_id={your-upload-sesson-id}' \
    -F 'video_file_chunk={binary-chunk-filename}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

الاستجابة

أرسل كل الأجزاء الإضافية حتى يتساوى start_offset مع end_offset:

{
 "start_offset": "152043520",
 "end_offset": "152043520"
}

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

الطلب

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={business-creative-folder-id}' \
    -F 'upload_phase=finish' \
    -F 'upload_session_id={session-id}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

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

• أخطاء في التحميل القابل للاستئناف
• استخدام واجهة Graph API، التعامل مع الأخطاء

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

https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id} (قيد التطوير)

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

https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}&business_id={client_business_id}

يمكن الحصول أيضًا على عنوان url خاص برابط لموضع معين من خلال إجراء طلب GET بنقطة النهاية:

curl -X GET \
    /<folder_id or asset_id>
        ?fields=['media_library_url']
        &access_token=<user_access_token>

يسمح الرابط للمستخدم بالانتقال إلى المجلد أو الأصل مباشرةً ضمن مكتبة أصول فيسبوك.

6. طلب مشاركة المجلد معك (اختياري)

يمكنك طلب مشاركة المجلد عالي المستوى معك إذا كنت تريد إدارة المجلد أو عرض الرؤى الخاصة بالأصول. وأرسل طلب POST إلى: {business-creative-folder-id}/agencies وقم بتعيين permitted_tasks إلى CREATE_CONTENT.

مشاركة المجلد

• يتطلب الإذن business_creative_management

الطلب

curl -X POST \
    -F 'permitted_tasks=['CREATE_CONTENT','VIEW_INSIGHTS']' \
    -F 'business={partner-business-id} ' \
    -F 'access_token={user-access-token}' https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies

تتوفر الاستجابة بنوع واحد من نوعين استنادًا إلى دور المستخدم في مؤسسة النشاط التجاري:

1) إذا كان رمز العميل يمثل مسؤول مدير أعمال:

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

الاستجابة

في حالة عقد اتفاقية شراكة موجودة بالفعل بين النشاط التجاري للمستخدم ونشاطك التجاري (شارك النشاط التجاري للمستخدم مجلدًا معك وقمت بقبول طلب المشاركة من قبل):

{ 
    "success": true
}

إذا لم تقبل أي طلبات مشاركة من النشاط التجاري للمستخدم بعد:

{
    "success": true,
    "share_status": "In Progress"
}

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

لإدراج كل اتفاقيات الشراكة المتوفرة قيد الموافقة، أرسل طلب إلى {business-id}/received_sharing_agreements باستخدام رمز وصول الشريك وقم بتعيين request_status إلى IN_PROGRESS. وتحتاج إلى الإذنين business_creative_management وbusiness_management لتنفيذ هذا الإجراء.

إدراج كل اتفاقيات الشراكة

الطلب

curl -i -X GET https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/received_sharing_agreements
    ?request_status=IN_PROGRESS
    &access_token={partner-access-token}"

يمكنك قبول طلب مشاركة عن طريق إرسال POST إلى business_sharing_agreement_request_id وتعيين request_status على APPROVE. وتحتاج فقط إلى القيام بذلك في المرة الأولى التي يشارك فيها شخص ما مجلدًا مع نشاطك التجاري. وتحتاج إلى الإذن business_management لتنفيذ هذا الإجراء:

قبول اتفاقيات الشراكة

الطلب

curl -X POST \
    -F 'request_status=APPROVE' \
    -F 'access_token={partner-access-token}' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>

الاستجابة

{ 
    "success": true
}

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

2) إذا كان رمز العميل يمثل موظفًا تابعًا لنشاط تجاري:

وتعمل واجهة API على تشغيل دفق عمل إشعار لإرسال إشعار بالبريد الإلكتروني إلى مسؤولي مدير الأعمال لاعتماد الطلب.

الاستجابة

{
   "success": true,
   "share_status": "Pending"
}

استجابة لهذه الحالة، يجب على تطبيقك إبلاغ المستخدم بما يلي:

• تمت تهيئة طلب إلى مسؤول مدير أعمال عبر البريد الإلكتروني لاعتماد طلب المشاركة
• تم إرسال بريد إلكتروني آخر إلى المستخدم حول الطلب

لإدراج كل الاتفاقيات المُعلقة التي تمت تهيئتها في النشاط التجاري للمستخدم، أرسل طلبًا إلى {business-id}/attempted_sharing_agreements وقم بتعيين request_status إلى IN_PROGRESS وتعيين requesting_business_id إلى معرف مدير أعمال المستخدم. تحتاج إلى الإذنين business_creative_management وbusiness_management لتنفيذ هذا الإجراء.

إدراج كل اتفاقيات مشاركة المجلد المُعلقة

الطلب

curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/attempted_sharing_agreements
    ?request_status=IN_PROGRESS
    &requesting_business_id=<user_business_id>
    &access_token={partner-access-token}

إدراج كل اتفاقيات مشاركة المجلد المُعلقة بمعرف الطلب

بدلًا من ذلك، إذا كان لديك معرف الطلب، يمكنك الحصول على الحالة مباشرة من خلال إرسال طلب إلى {request_id}.

• يتطلب الإذن business_creative_management

الطلب

curl -i -X GET  \
    https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>?fields=status

عندما يوافق مسؤول مدير أعمال على الطلب، تتغير الحالة إلى APPROVE وتتم مشاركة المجلد مرة أخرى مع مدير الأعمال إذا تم عقد اتفاقية مشاركة بين النشاط التجاري للمستخدم ونشاطك التجاري (شارك النشاط التجاري للمستخدم مجلدًا معك وقمت بقبول طلب مشاركة من قبل). وبخلاف ذلك، يتم تحديث share_status إلى IN_PROGRESS. ويمكنك إدراج كل اتفاقيات الشراكة بالحالة IN_PROGRESS وقبولها عبر واجهة API أو في واجهة مستخدم مدير الأعمال.

7. عرض رؤى الصور/مقاطع الفيديو (اختياري)

عندما يشارك المستخدم مجلدًا معك بإذن المهمة VIEW_INSIGHTS، يمكنك قراءة رؤى صور النشاط التجاري ومقاطع الفيديو ضمن المجلد المشترك من خلال إجراء طلب GET بنقطة نهاية <business_asset_id>/insights.

رؤى تصميم النشاط التجاري

• يلزم توفير الإذنين business_creative_management وbusiness_creative_insights.

الطلب

curl -i -X GET  \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ASSET_ID>/insights
    ?breakdowns=["age","gender"]
    &fields=impressions,inline_link_clicks,age,gender,date_start,
    &time_range={"since":"2019-08-01","until":"2019-08-22"}
    &access_token={partner-access-token}"

الاستجابة

{
 "data": [
   {
     "impressions": 99,
     "inline_link_clicks": 1,
     "age": "18-24",
     "gender": "female",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
   {
     "impressions": 198,
     "inline_link_clicks": 2,
     "age": "18-24",
     "gender": "male",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
   {
     "impressions": 464,
     "inline_link_clicks": 2,
     "age": "25-34",
     "gender": "female",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
 ]
}

يمكن أن يكون التقسيم حسب:

• gender
• age
• country
• publisher_platform
• platform_position
• device_platform
• ad_id
• objective
• optimization_goal
• time_range (يتطلب تاريخًا بتنسيق "YYYY-MM-DD" ويعني ذلك من بداية منتصف الليل في ذلك اليوم.)

إدارة المجلد المشترك باستخدام رمز الشريك مباشرة

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

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

1. التحقق من إذن المجلد الأصل

يمكنك إجراء استدعاء لنقطة النهاية <business_id>/creative_folders للحصول على كل المجلدات الأصل التي تمت مشاركتها معك ضمن النشاط التجاري للمستخدم.

• يتطلب الإذن business_creative_management

الحصول على مجلدات من النشاط التجاري للمستخدم

الطلب

curl -X GET \
     -F 'access_token={partner-access-token}' \  https://graph.facebook.com/<API_VERSION>/<partner_business_id>/creative_folders?filtering=[{field:"owner_business_id", operator:"EQUAL", value:"user_business_id"}]

الاستجابة

{ 
    "data": [
       { 
            "id": "<shared_folder_id>" 
       }
    ]
}

الحصول على مهام مسموح بها لديك بالمجلد

الطلب

curl -X GET \
 -F 'access_token={partner-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<folder_id>/agencies

الاستجابة

{
 "data": [
   {
     "id": "<partner_business_id>",
     "name": "<partner business name>",
     "permitted_tasks": [
       "VIEW_INSIGHTS",
       "VIEW_CONTENT",
       "CREATE_CONTENT",
       "MANAGE_CONTENT",
       "MANAGE_PERMISSIONS"]
   }
 ],
}

• إذن المهمة CREATE_CONTENT مطلوب لتحميل الصور ومقاطع الفيديو إلى مجلد مشترك
• إذن المهمة VIEW_INSIGHTS مطلوب للاستعلام عن رؤى تصميم الصور أو مقاطع الفيديو ضمن مجلد مشترك

2. إنشاء مجلد فرعي ضمن المجلد الأصل

من خلال إذن المهمة CREATE_CONTENT بالمجلد الأصل، يمكنك إنشاء مجلد فرعي في مجلد مشترك.

• يتطلب الإذن business_creative_management

إنشاء مجلد فرعي

الطلب

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F "parent_folder_id={parent-folder-id}"
    -F 'access_token={partner-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

الاستجابة

{
 "id": {subfolder-id}
}

3. تحميل الصور ومقاطع الفيديو إلى مجلد فرعي

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

تتبع معرف أصل صورة/فيديو على Facebook

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

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

سيسمح ذلك بوجود حالات استخدام ‘تعديل’ و‘تحديث’ سلسة وبسيطة والتي سيتم دعمها في المستقبل، فعلى سبيل المثال:

• مستخدم في تطبيقك يقرر متابعة تعديل أصل بعد نشره على Facebook واستخدامه في إعلان. وستتم مطالبة المستخدم بعمليات دفق ‘تحديث’ أو ‘تشغيل اختبار التقسيم’ سلسة وبسيطة إذا كان تطبيقك يرسل معرف الأصل الأصلي عند تحميل إصدار مُحدث من الصورة/الفيديو.
• مستخدم في لوحة رؤى إعلان على Facebook يتمتع بإمكانية ‘تعديل’ تصميمه، بما في ذلك تعديل الصورة/الفيديو الذي سيرسل المستخدم إلى تطبيقك ويدخل إلى معرف الأصل. واستجابة لذلك، سيتمكّن تطبيقك من فتح المشروع الذي أنشأ هذا الأصل مما يسمح للمستخدم بالمتابعة حيث توقف.

توفير عنوان URL خاص برابط لموضع معين إلى أصل وإنشاء إعلان وتنفيذ إجراءات النشر

عنوان URL خاص برابط لموضع معين للأصل

• الاستعلام عن الحقل media_library_url لأصل الصورة/الفيديو الذي تم تحميله

الطلب

curl -X GET \
    -F 'access_token={partner-access-token}' \
https://graph.facebook.com/<API_VERSION>/<asset_id>?fields=media_library_url

عنوان URL خاص برابط لموضع معين لإنشاء إعلان أو منشور صفحة

• إلحاق &action=CREATE_AD أو &action=CREATE_POST في أخر الرابط لموضع معين في الخطوة أعلاه.

المثال:

https://business.facebook.com/asset_library/business_creatives/?object_id=2838437832929622&action=CREATE_AD

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

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