إعلانات الشريك المُدار: مرجع واجهة API

تشمل واجهات API إعلانات الشريك المُدار الأخرى:

• واجهات API إدارة البائع
• واجهات API إدارة إعلانات الشريك
• دليل المستخدم لواجهة API المتزامنة

البحث عن واجهة API النشاط التجاري للبائع

استخدم واجهة API هذه للبحث عن معرف النشاط التجاري لبائع معين أو vendor_id.

نوع رمز الوصول

لاستدعاء الواجهة API هذه، استخدم رمز الوصول الذي تم إنشاؤه بواسطة مستخدم نظام مسؤول ينتمي إلى مدير الأعمال الرئيسي (مدير أعمال المتجر).

عينة من طلب GET

curl -X GET \
  -F "child_business_external_id=<VENDOR_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/owned_businesses?access_token=<ACCESS_TOKEN>"

عينة من الاستجابة

{
    "child_business_id": 3213232
}

الوصول إلى واجهة API البيانات الوصفية للنشاط التجاري للبائع

استخدم واجهة API هذه لاسترداد البيانات الوصفية للبائع الخاصة بنشاط تجاري فرعي لبائع إعلانات الشريك المُدار. تشمل البيانات الوصفية من استجابة الواجهة API ما يلي:

• أصول إعلانات الشريك المُدار: الصفحة، الحساب الإعلاني، طريقة الدفع
• معلومات القالب المخصص للبائع
• معلومات النشاط التجاري للبائع: الاسم

نوع رمز الوصول

لاستدعاء الواجهة API هذه، استخدم رمز الوصول الذي تم إنشاؤه بواسطة مستخدم نظام مسؤول ينتمي إلى مدير الأعمال الرئيسي (مدير أعمال المتجر).

نوع معرف النشاط التجاري

استخدم معرف مدير الأعمال الفرعي لاستدعاء الواجهة API.

عينة من طلب GET

curl -X GET \
  "https://graph.facebook.com/v<API_VERSION>/<Business_id>/?fields=collaborative_ads_managed_partner_business_info&access_token=<ACCESS_TOKEN>"

عينة من الاستجابة

{
  "collaborative_ads_managed_partner_business_info": {
    "seller_business_status": "ready",
    "seller_business_info": {
      "seller_external_website_url": "https://www.website.com",
      "partner_facebook_page": {
        "id":"9999999"
      }
    },
    "ad_account": {
      "id": "act_11111111",
      "currency": "USD"
    },
    "page": {
      "id": "3333333"
    },
    "catalog_segment": {
      "id": "2222222"
    },
    "extended_credit": {
      "receiving_credit_allocation_config": {
        "partition_type": "FIXED",
        "id":"66666666"
      },
      "max_balance": {
        "amount":"5,000.00",
        "amount_in_hundredths":"500000",
        "currency":"USD",
        "offsetted_amount":"500000"
      },
      "id":"888888888"
    },
    "active_seller_campaign": {
      "status": "ACTIVE",
      "id": "1111111"
    },
    "template": [
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "4444444",
        "adgroup_template_ids": [
          "5555555"
        ],
        "targeting_type": "retargeting"      
      },
      {
        "budget_percentage": 0.5,
        "campaign_template_id": "6666666",
        "adgroup_template_ids": [
          "7777777"
        ],
        "targeting_type": "prospecting"
      } 
    ]
  },
  "id": "<child_business_manager_id>"
}
    

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

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

عينة من طلب POST

curl \
  -F 'id=<CHILD_BUSINESS_MANAGER>' \
  -F 'app_id=<App_ID>' \
  -F 'scope=ads_management,business_management' \
  -F 'access_token=<Parent BM Admin System User Access Token>' \
  -F 'appsecret_proof=<APP_SECRET>' \
  "https://graph.facebook.com/<API_VERSION>/<CHILD_BUSINESS_MANAGER_ID>/access_token"

عينة من الاستجابة

{ 
  "access_token": "<CHILD_BM_ACCESS_TOKEN>"
}

تحديث واجهة API تكوين النشاط التجاري للبائع

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

لإنشاء نشاط تجاري لبائع والحصول عليه، راجع واجهة API إنشاء نشاط تجاري للبائع. للعثور على معرف النشاط التجاري الخاص بالبائع الحالي، راجع البحث عن واجهة API النشاط التجاري للبائع.

نوع رمز الوصول

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

المعلمات المتوفرة

عينة من طلب POST

curl \
  -F "seller_external_website_url='http://shop.com'" \
  -F "ad_account=<SELLER_ACTIVE_AD_ACCOUNT_ID>" \
  "https://graph.facebook.com/v<API_VERSION>/<Child_Business_id>/managed_partner_business_setup?access_token=<ACCESS_TOKEN>"

عينة من الاستجابة

{
    "id": 3213232, // id of child business
    "meta_data": {
        "seller_business_info": {
            "seller_email_address": "goodseller@fb.com"
            "seller_external_website_url": "www.website.com"
        },
        "ad_account": {
            "id": "434343",
            "spend_limit": "500",
        },
        "page": {
            "id": "123412341",
        },
        "template": [
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "4444444",
            "adgroup_template_ids": [
              "5555555"
            ],
            "targeting_type": "retargeting"      
          },
          {
            "budget_percentage": 0.5,
            "campaign_template_id": "6666666",
            "adgroup_template_ids": [
              "7777777"
            ],
            "targeting_type": "prospecting"
          } 
        ]     
    }
}

رموز الأخطاء

استخدام القوالب

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

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

• مكون المجموعة الإعلانية للعملاء المحتملين
• المكون الإعلاني
• مكون المجموعة الإعلانية لإعادة الاستهداف
• المكون الإعلاني

أنواع القوالب

يوجد نوعان من القوالب: الافتراضية والمُخصَّصة:

متطلبات القوالب المخصصة

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

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

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

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

دفق القالب المخصص

الخطوة الأولى: إنشاء قالب حملة إعلانية مخصص

1. انتقل إلى علامة التبويب الأصول في مركز التعاون. داخل علامة التبويب هذه، يعرض قسم مخزون القوالب مجموعة من القوالب ومكونات القوالب التي يمكن استخدامها للحملات الإعلانية للبائع.
2. انقر على إنشاء قالب لفتح بطاقة متدرجة.
3. ابحث عن حملة مصدر صالحة حالية من خلال تقديم المجموعة الإعلانية أو معرف الإعلان.
4. لإنشاء مكون القالب الخاص بك، حدِّد إما المجموعة الإعلانية و/أو الإعلان المستخرج من معرف المصدر. يجب أن تقوم بإنشاء جميع المكونات الأربعة (إعلانان ومجموعتان إعلانيتان) لقالب مخصص.
5. احفظ القالب من خلال تقديم الاسم والوصف.

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

الخطوة الثانية: تطبيق القالب المخصص على البائع

يمكن استخدام القوالب المخصصة كما يلي:

• تُستخدم عند تأهيل البائع لتعيين قوالب محددة للحملات الإعلانية لبائع جديد.
• تغيير القالب للبائع لبدء عطلة أو حملة خاصة أخرى.

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

يمكن تطبيق قالب على البائعين باستخدام إحدى الطرق التالية:

دفق واجهة المستخدم لتطبيق قالب بائع واحد

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

دفق واجهة المستخدم لتطبيق قالب مجمّع

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

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

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

يمكنك الإنهاء من خلال النقر على حفظ. سيتم تطبيق مكونات القالب المحددة على البائعين المحددين.

تحديث واجهة API تكوين النشاط التجاري للبائع

استخدم تحديث واجهة API تكوين النشاط التجاري للبائع لتطبيق قالب مخصص على البائع بمعلمة الإدخال التالية: template.

"template":[
  {
    "budget_percentage":0.5,
    "campaign_template_id":"160235235998069",
    "adgroup_template_ids":[
      "447963739637509"
    ],
    "targeting_type":"retargeting"
  },
  {
    "budget_percentage":0.5,
    "campaign_template_id":"278452090413983",
    "adgroup_template_ids":[
      "458654975391261"
    ],
    "targeting_type":"prospecting"
  }
]

الخطوة الثالثة: إنشاء حملتك الإعلانية

استخدم تعليمات إنشاء الحملة الرئيسية لإنشاء إعلانات البائع وتشغيلها بالمعلمات المحددة والقالب المخصص المطبق مسبقًا. لاستخدام قالب الحملة الإعلانية المخصص المطبق على ذلك البائع، قم بتعيين use_seller_template إلى true.