بدء الاستخدام

تعرف على كيفية تنفيذ إدارة أصول التصميمات.

تتوفر إدارة أصول التصميمات لتحديد الشركاء فقط. لمزيد من المعلومات، يُرجى التواصل مع شريك Meta لديك.

المتطلبات

لاستخدام API هذه، تحتاج إلى ما يلي:

الأذونات

عند تسجيل الدخول إلى التطبيق، ستحتاج إلى طلب الأذونات التالية من المستخدمين:

business_creative_management - إدارة مجلدات عناصر تصميمات النشاط التجاري وعناصر تصميمات النشاط التجاري. مطلوب لكل نقاط نهاية API مدير أصول عناصر تصميمات النشاط التجاري.
business_creative_insights - الوصول إلى رؤى أصول عناصر تصميمات النشاط التجاري.
business_management - إدارة مستخدمي النشاط التجاري وقبول طلبات اتفاقيات الشراكة.

التقييدات

يجب أن يكون مستخدم التطبيق (المعلن) مسؤولاً عن النشاط التجاري الذي يمثله معرف مدير الأعمال

الخطوة الأولى: إنشاء مجلد عناصر تصميمات نشاط تجاري

يمكنك إنشاء مجلد عناصر تصميمات نشاط تجاري نيابةً عن النشاط التجاري للمعلن عن طريق إجراء طلب POST لنقطة النهاية {business-id}/creative_folders. في هذه الحالة، {business-id} هو معرف النشاط التجاري للمعلن.

الإذن business_creative_management مطلوب لهذا الإجراء.

مثال على الطلب

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

مثال على الاستجابة

{ “id”: “{business-creative-folder-id}” }

يمكنك أيضًا إنشاء مجلدات فرعية.

الخطوة الثانية: إضافة التصميم إلى المجلدات

يمكنك إضافة أصول التصميمات الحالية إلى مجلد عن طريق إجراء طلب POST إلى {business-id}/images أو {business-id}/videos. تحتاج إلى الإذن business_creative_management لتنفيذ هذا الإجراء.

إضافة الصور

مثال - لإضافة صورة:

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

الاستجابة

{
  "images":{
    "{image-name}":{
      "id":"{business-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={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

الاستجابة

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

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

بالنسبة إلى مقاطع الفيديو الأكبر حجمًا، أرسل طلب start واحد أو طلبات transfer متعددة، وطلب finish واحد.

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

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={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}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

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

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

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-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={access-token}' \
  -F 'creative_folder_id={business-creative-folder-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={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

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

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

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

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

للحصول على عنوان URL خاص برابط لموضع معين لأصل محدد، يمكنك الاستعلام عن الحقل media_library_url للصورة التي تم تحميلها أو أصل الفيديو:

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

لاستخدام الرابط لموضع معين لإنشاء إعلان أو منشور صفحة، قم بإلحاق &action=CREATE_AD أو &action=CREATE_POST في نهاية الرابط:

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD