الإصدار 2.11

واجهة API التسويق

تم الإصدار في 7 نوفمبر 2017 | منشور مدوّنة

• الميزات الجديدة
• أهم التغييرات
• حالات إيقاف الاستخدام
• حالات إيقاف الاستخدام الفورية

الميزات الجديدة

إعادة تصميم واجهة API مدير الأعمال

أصبح لدينا الآن علاقة جديدة والتي تمثل العملاء والوكالات. ولم يكن لدينا user في الماضي أيضًا؛ حيث كنا نعالج كل عمليات الوصول والدعوات إلى نشاط تجاري وأصوله من خلال bid/userpermissions والتي تسببت في حدوث مشكلات تتعلق بالأداء. من أبرز العناصر التي ترتبط بواجهة API الجديدة ما يلي:

• المستخدمون على نطاق النشاط التجاري- يتم ربط المستخدم الجديد بنشاط تجاري محدد ويتم منحه أذونات على نطاق ذلك النشاط التجاري. يتمكن المستخدمون من إدارة ملفاتهم الشخصية والأذونات وأصولهم المرتبطة بذلك النشاط التجاري.
• الدعوات - يمكنك دعوة الأشخاص للوصول إلى نشاط تجاري عبر نقاط نهاية جديدة. ويمكنك التحقق من حالة دعوات المستخدم وتحديثها من خلال نقاط النهاية هذه.
• فئات الأصول - يمكنك تقسيم الأنواع المختلفة من الأصول إلى فئات وتقديم نقاط نهاية مختلفة لكل فئة من الفئات. يساعد ذلك في تسهيل تقسيم صفحات النتائج عند قراءة الأصول. كما يساعد في الحد من المشكلات المتعلقة بالأداء إذا كنت تدير آلاف الأصول لأحد الأنشطة التجارية. وقمنا لأغراض إعادة التصميم بإضافة عدة نقاط نهاية جديدة.

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

• BUSINESS_ID/business_users
• BUSINESS_ID/system_users
• BUSINESS_ID/pending_users

للوصول إلى الأصول التي تم تعيينها إلى مستخدمين:

• BUSINESS_USER_ID/assigned_pages
• BUSINESS_USER_ID/assigned_ad_accounts
• BUSINESS_USER_ID/assigned_product_catalogs
• SYSTEM_USER_ID/assigned_pages
• SYSTEM_USER_ID/assigned_ad_accounts
• SYSTEM_USER_ID/assigned_product_catalogs
• PENDING_USER_ID/assigned_pages
• PENDING_USER_ID/assigned_ad_accounts
• PENDING_USER_ID/assigned_product_catalogs

للوصول إلى صفحات النشاط التجاري:

• BUSINESS_ID/owned_pages - للحصول على قائمة بالصفحات التي يمتلكها النشاط التجاري
• BUSINESS_ID/client_pages - للحصول على قائمة بصفحات عملاء النشاط التجاري
• BUSINESS_ID/pending_owned_pages - للحصول على قائمة بالصفحات التي يمتلكها النشاط التجاري التي تنتظر الحصول على الموافقة
• BUSINESS_ID/pending_client_pages - للحصول على قائمة بالصفحات التي يمتلكها عملاء النشاط التجاري التي تنتظر الحصول على الموافقة

للوصول إلى الحسابات الإعلانية للنشاط التجاري:

• BUSINESS_ID/owned_ad_accounts - للحصول على قائمة بالحسابات الإعلانية التي يمتلكها النشاط التجاري
• BUSINESS_ID/client_ad_accounts - للحصول على قائمة بالحسابات الإعلانية لعملاء النشاط التجاري
• BUSINESS_ID/pending_owned_ad_accounts - للحصول على قائمة بالحسابات الإعلانية التي يمتلكها النشاط التجاري التي تنتظر الحصول على الموافقة
• BUSINESS_ID/pending_client_ad_accounts - للحصول على قائمة بالحسابات الإعلانية لعملاء النشاط التجاري التي تنتظر الحصول على الموافقة

للوصول إلى كتالوجات منتجات النشاط التجاري

• BUSINESS_ID/owned_product_catalogs - للحصول على قائمة بكتالوجات المنتجات التي يمتلكها النشاط التجاري
• BUSINESS_ID/client_product_catalogs - للحصول على قائمة بكتالوجات المنتجات التي يمتلكها عملاء النشاط التجاري

للوصول إلى تطبيقات النشاط التجاري:

• BUSINESS_ID/owned_apps - للحصول على قائمة بالتطبيقات التي يمتلكها النشاط التجاري
• BUSINESS_ID/client_apps - للحصول على قائمة بتطبيقات عملاء النشاط التجاري
• BUSINESS_ID/pending_client_apps - للحصول على قائمة بالتطبيقات التي يمتلكها عملاء النشاط التجاري التي تنتظر الحصول على الموافقة

لمزيد من المعلومات، راجع مدير الأعمال، واجهة API ومدير الأعمال، مستخدم النظام وواجهة API إدارة أصول الأعمال وواجهة API مدير الأعمال، أفضل الممارسات.

الإعلانات الدوّارة، الموقع الفوري

يمكنك الآن إنشاء إعلان دوّار يتضمن مرفقًا يعرض موقعًا فوريًا. تمت إضافة الخيارات type=REALTIME وlocation_source_id = PAGE_ID في place_data من أجلAD_CREATIVE_ID/object_story_spec. يتوفر ذلك في حقل object_story_spec في:

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

زيارات المتجر، استهداف المواقع الجغرافية

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

• POST AD_ACCOUNT_ID/adsets يحتوي على الخيار الجديد.
• يدعم كل المناطق الجغرافية في مواصفات الاستهداف، المواقع باستثناء الاستهداف حسب country_groups ونوع موقع travel_in.
• يتوفر إنشاء الإعلانات بهدف STORE_VISITS على أساس التوفر المحدود، راجع زيارات المتجر

المجموعة الإعلانية، أنواع الوجهات

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

• تمت إضافة destination_type للمجموعات الإعلانية
• يتوفر في /ADSET_ID

مؤشر الأداء الأساسي

تمت إضافة الحقل الجديد kpi_type إلى AD_ACCOUNT_ID/CAMPAIGN_ID الذي يصف نوع مؤشر الأداء الأساسي الذي تريد تتبعه لكائنات الحملة الإعلانية أو الإعلان في الحملة الإعلانية. لعرض بيانات الرؤى بواسطة kpi_type في kpi_results قم بإجراء الاستدعاءات التالية:

• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights

لمزيد من المعلومات، راجعالحملة الإعلانية، مرجع.

أهم التغييرات

إدارة الإعلانات

• إلغاء صلاحية الإعلانات التي تستهدفright_hand_column - تقوم الإعلانات التي تستهدف هذا الموضع بتصميمات غير صالحة من أجل right_hand_column على AD_ACCOUNT_ID/adsets بعرض رسالة خطأ. لا نسمح بموضع "right_hand_column فقط" مع تنسيقات إعلانات الفيديو أو التشكيلة أو اللوحة. بالنسبة إلى موضع "right_hand_column فقط"، يمكنك استخدام تنسيق صورة واحدة أو التنسيق الدوّار فقط.

• تم تغييرGET VERSION/RF_PREDICTION_ID/pause_periods - ليقوم بعرض Array الآن، وليس String لتسهيل عملية المعالجة.

واجهة API مدير الأعمال

• تمت إعادة تسمية الحقول - تمت إعادة تسمية الحقل admin_system_user ليصبح admin، وإعادة تسمية الحقل system_user ليصبح employee. يؤثر ذلك على عناصر الربط التالية:

  • /{business-id}/userpermissions
  • /{business-id}/system_users

حالات إيقاف الاستخدام

إدارة الإعلانات

تم إيقاف استخدام التحسينات لهدفVIDEO_VIEWS - لم تعد الحملات الإعلانية بهدف VIDEO_VIEWS يمكنها استخدام أهداف CLICKS أو IMPRESSIONS أو PAGE_ENGAGEMENT أو POST_ENGAGEMENT أو REACH كأهداف تحسين:

• يؤدي إنشاء مجموعات إعلانية بأهداف التحسين هذه إلى عرض رسالة خطأ.
• وفي حالة تكرار مجموعات إعلانية يتم تشغيلها بهدف التحسين REACH، يتم تلقائيًا استبدالها بهدف التحسين VIDEO_VIEWS.
• يؤدي تكرار مجموعات إعلانية بأهداف التحسين CLICKS أو IMPRESSIONS أو PAGE_ENGAGEMENT أو POST_ENGAGEMENT إلى عرض رسالة خطأ. ويرجع السبب في حدوث الخطأ إلى أن إنشاء أو تكرار الإعلان في مجموعة إعلانية موجودة يحاول إعادة استخدام أي هدف من أهداف التحسين هذه.

عناصر الربط المتأثرة بهذا التغيير:

• POST ACCOUNT_ID/adsets
• POST AD_ACCOUNT_ID/ads
• POST CAMPAIGN_ID/copies
• POST ADSET_ID/copies
• POST AD_ID/copies

تم إيقاف استخدامreach - باعتباره optimization_goal لهدف الوعي بالعلامة التجارية. تمت إزالته من أجل أو /adset؛ يتوفر لتحسين معدل تذكر الإعلان فقط. يساعد ذلك في تجنب الاضطراب بالنسبة إلى أي شخص يستخدم الوصول كهدف مخصوص.

تم إيقاف استخدام التحسينBRAND_AWARENESS - وحل محله AD_RECALL_LIFT. ويمثل ذلك نموذج عرض إعلانات جديد وأكثر فعّالية. يدعم هدف التحسين الجديد التصميم المختلط، مثل الإعلانات الثابتة وإعلانات الفيديو في نفس المجموعة الإعلانية وعرض الأسعار اليدوي. لم يعد BRAND_AWARENESS متوفرًا في:

• POST /ADSET_ID
• GET /ADSET_ID
• POST /AD_ACCOUNT_ID/adsets

تم إيقاف استخدامfrequency_cap - بما في ذلك حقول lifetime_frequency_cap وfrequency_cap_reset_period في:

• POST AD_ACCOUNT_ID/adsets
• GET /ADSET_ID
• POST /ADSET_ID

استخدم frequency_control_specs كبديل.

تم إيقاف استخدام التكلفة لكل إجراءPOST_ENGAGEMENT - لم يعد بإمكانك استخدام POST_ENGAGEMENT باعتباره billing_event لهذا الهدف. يؤدي ذلك إلى موازاة عرض الإعلانات والقياس على نحوٍ أفضل. يؤثر ذلك على نقطة النهاية: /AD_SET_ID.

رؤى الإعلانات والقياس

تم إيقاف استخدامvideo_15_sec_watched_actions على:

• GET AD_ACCOUNT_ID/insights
• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights
• POST AD_ACCOUNT_ID/insights
• POST CAMPAIGN_ID/insights
• POST ADSET_ID/insights
• POST AD_ID/insights

تم إيقاف استخدامrecurrence_value - من واجهة API القياس المتقدم. يُعرف الحقل أيضًا في واجهة Atlas API بجدول التقرير. ولقد حل محله recurrence_values. راجع القياس المتقدم، جداول التقارير.

إدارة الأعمال

تم إيقاف استخدام نقاط نهاية إعادة تصميم واجهة API مدير الأعمال:

• BUSINESS_ID/userpermissions
• BUSINESS_ID/business_persona
• business_persona_id

تم إيقاف استخدام نقاط نهاية إدارة أصولك:

• BUSINESS_ID/pages
• BUSINESS_ID/adaccounts
• BUSINESS_ID/product_catalogs
• BUSINESS_ID/apps

للوصول إلى الأصول، استخدم BUSINESS_ID/owned_ASSET أو BUSINESS_ID/client_ASSET

تم إيقاف استخدام نقاط نهاية إدارة الأصول التي يمتلكها نشاط تجاري آخر:

• BUSINESS_ID/assigned_ad_accounts
• BUSINESS_ID/assigned_pages
• BUSINESS_ID/assigned_product_catalogs

بدلاً من ذلك، استخدم BUSINESS_USER_ID/assigned_ASSET

حالات إيقاف الاستخدام الفورية

تؤثر حالات إيقاف الاستخدام هذه على كل إصدارات واجهات API ويتم تفعيلها في 14 نوفمبر 2017.

إعلانات المناسبات وإعلانات الروابط

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

التوقيعات التي تم إيقاف استخدامها:

• إعلانات المناسبات

  • الهدف: EVENT_RESPONSES
  • حقول التصميم:body، object_id
• إعلانات الروابط

  • الهدف: LINK_CLICKS
  • حقول التصميم:title، body،object_url (image_file أو image_hash)

التوقيعات المدعومة

• إعلانات المناسبات

  • الهدف: EVENT_RESPONSES
  • حقول التصميم:object_story_id أو object_story_spec
• إعلانات الروابط

  • الهدف: LINK_CLICKS
  • حقول التصميم:object_story_id أو object_story_spec

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