‏API التسويق‏

البدء

أنشئ إعلانك الأول باستخدام واجهة API التسويق من خلال اتباع الخطوات التالية.

قبل البدء

يجب أن تتعرف على واجهة Graph API وبنية الحملة الإعلانية في فيسبوك. وبمجرد أن تصبح مستعدًا لبدء إجراء الاستدعاءات، ستحتاج إلى ما يلي:

بعد ذلك، يمكنك بدء الاستخدام. وتذكّر الرجوع إلى أفضل الممارسات العامة لاستخدام واجهة API التسويق.

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

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

curl -X POST \
  -F 'name="My campaign"' \
  -F 'objective="OUTCOME_TRAFFIC"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/campaigns
Open In Graph API ExplorerOpen In Postman
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Campaign = bizSdk.Campaign;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My campaign',
  'objective' : 'OUTCOME_TRAFFIC',
  'status' : 'PAUSED',
  'special_ad_categories' : [],
};
const campaigns = (new AdAccount(id)).createCampaign(
  fields,
  params
);
logApiCallResult('campaigns api call complete.', campaigns);
Open In Graph API ExplorerOpen In Postman
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My campaign',
  'objective' => 'OUTCOME_TRAFFIC',
  'status' => 'PAUSED',
  'special_ad_categories' => array(),
);
echo json_encode((new AdAccount($id))->createCampaign(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API ExplorerOpen In Postman
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.campaign import Campaign
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My campaign',
  'objective': 'OUTCOME_TRAFFIC',
  'status': 'PAUSED',
  'special_ad_categories': [],
}
print AdAccount(id).create_campaign(
  fields=fields,
  params=params,
)
Open In Graph API ExplorerOpen In Postman
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCampaign()
      .setName(\"My campaign\")
      .setObjective(Campaign.EnumObjective.VALUE_OUTCOME_TRAFFIC)
      .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
      .setParam(\"special_ad_categories\", \"[]\")
      .execute();

  }
}
Open In Graph API ExplorerOpen In Postman
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
campaigns = ad_account.campaigns.create({
    name: 'My campaign',
    objective: 'OUTCOME_TRAFFIC',
    status: 'PAUSED',
    special_ad_categories: [],
})
Open In Graph API ExplorerOpen In Postman

عند نجاح العملية، نقوم بإرجاع معرف لحملتك الإعلانية التي تم إنشاؤها حديثًا. وتذكّر حفظ هذا المعرف. كما يمكنك التحقق من إنشاء حملتك الإعلانية في مدير الإعلانات.

الموارد:

الخطوة الثانية: تحديد الاستهداف

المستندات المرجعية

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

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

أولاً، لنبحث عن البلدان المتوفرة التي تتضمن كلمة "united" (متحدة):

curl -G \
  -d 'location_types=["country"]' \
  -d 'type=adgeolocation' \
  -d 'q=united' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Open In Graph API ExplorerOpen In Postman

بعد ذلك، يمكننا البحث عن الاهتمامات التي تتضمن الكلمة "movie" (أفلام):

curl -G \
  -d 'type=adinterest' \
  -d 'q=movie' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

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

targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "interests": [{id: 6003139266461, 'name': 'Movies'}]
}

الخطوة الثالثة: إنشاء مجموعة إعلانية وتحديد الميزانية والفوترة والتحسين والمدة

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

  • المدة: تمثل المدة التي سيتم خلالها تشغيل إعلاناتك. ويمكنك تحديدها باستخدام start_time وend_time.
  • الميزانية: يمثل المبلغ الذي تريد إنفاقه. ويمكنك استخدام daily_budget أو lifetime_budget.
  • التحسين: يمثل النتيجة التي تسعى إلى تحقيقها من خلال إعلانك. ويمكنك الإعداد باستخدام optimization_goal.
  • الفوترة: تمثل الطريقة التي تريد الدفع من خلالها. ويمكنك استخدام billing_event.
  • عرض الأسعار: يمثل القيمة التي تحددها عند إجراء حدث التحسين لديك. ويمكنك استخدام الحقل bid_amount.
  • الاستهداف: يمكنك استخدام مواصفات الاستهداف التي تم إنشاؤها في الخطوة الثانية.

لإنشاء مجموعتك الإعلانية، تحتاج أيضًا إلى معرف الحملة الإعلانية الذي حفظته أثناء إجراء الخطوة الأولى:

curl -X POST \
  -F 'name="My Reach Ad Set"' \
  -F 'optimization_goal="REACH"' \
  -F 'billing_event="IMPRESSIONS"' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id="<AD_CAMPAIGN_ID>"' \
  -F 'targeting={
       "geo_locations": {
         "countries": [
           "US"
         ]
       },
       "facebook_positions": [
         "feed"
       ]
     }' \
  -F 'status="PAUSED"' \
  -F 'promoted_object={
       "page_id": "<PAGE_ID>"
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adsets
Open In Graph API ExplorerOpen In Postman
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const AdSet = bizSdk.AdSet;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Reach Ad Set',
  'optimization_goal' : 'REACH',
  'billing_event' : 'IMPRESSIONS',
  'bid_amount' : '2',
  'daily_budget' : '1000',
  'campaign_id' : '<adCampaignLinkClicksID>',
  'targeting' : {'geo_locations':{'countries':['US']},'facebook_positions':['feed']},
  'status' : 'PAUSED',
  'promoted_object' : {'page_id':'<pageID>'},
};
const adsets = (new AdAccount(id)).createAdSet(
  fields,
  params
);
logApiCallResult('adsets api call complete.', adsets);
Open In Graph API ExplorerOpen In Postman
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdSet;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Reach Ad Set',
  'optimization_goal' => 'REACH',
  'billing_event' => 'IMPRESSIONS',
  'bid_amount' => '2',
  'daily_budget' => '1000',
  'campaign_id' => '<adCampaignLinkClicksID>',
  'targeting' => array('geo_locations' => array('countries' => array('US')),'facebook_positions' => array('feed')),
  'status' => 'PAUSED',
  'promoted_object' => array('page_id' => '<pageID>'),
);
echo json_encode((new AdAccount($id))->createAdSet(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API ExplorerOpen In Postman
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.adset import AdSet
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Reach Ad Set',
  'optimization_goal': 'REACH',
  'billing_event': 'IMPRESSIONS',
  'bid_amount': '2',
  'daily_budget': '1000',
  'campaign_id': '<adCampaignLinkClicksID>',
  'targeting': {'geo_locations':{'countries':['US']},'facebook_positions':['feed']},
  'status': 'PAUSED',
  'promoted_object': {'page_id':'<pageID>'},
}
print AdAccount(id).create_ad_set(
  fields=fields,
  params=params,
)
Open In Graph API ExplorerOpen In Postman
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAdSet()
      .setName(\"My Reach Ad Set\")
      .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
      .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
      .setBidAmount(2L)
      .setDailyBudget(1000L)
      .setCampaignId(\"<adCampaignLinkClicksID>\")
      .setTargeting(
          new Targeting()
            .setFieldFacebookPositions(Arrays.asList(\"feed\"))
            .setFieldGeoLocations(
              new TargetingGeoLocation()
                .setFieldCountries(Arrays.asList(\"US\"))
            )
        )
      .setStatus(AdSet.EnumStatus.VALUE_PAUSED)
      .setPromotedObject(\"{\\"page_id\\":\\"<pageID>\\"}\")
      .execute();

  }
}
Open In Graph API ExplorerOpen In Postman
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
adsets = ad_account.adsets.create({
    name: 'My Reach Ad Set',
    optimization_goal: 'REACH',
    billing_event: 'IMPRESSIONS',
    bid_amount: '2',
    daily_budget: '1000',
    campaign_id: '<adCampaignLinkClicksID>',
    targeting: {'geo_locations':{'countries':['US']},'facebook_positions':['feed']},
    status: 'PAUSED',
    promoted_object: {'page_id':'<pageID>'},
})
Open In Graph API ExplorerOpen In Postman

نوصي بإنشاء مجموعة إعلانية بالحالة PAUSED لتجنب تحصيل أي رسوم أثناء الاختبار.

الخطوة الرابعة: توفير تصميم الإعلان

المستندات المرجعية

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

  • الصور ومقاطع الفيديو
  • العنوان والوصف
  • الروابط
  • أزرار الدعوة لاتخاذ إجراء

استنادًا إلى الهدف الذي تستخدمه، قد تحتاج إلى توفير حقول متقدمة. فعلى سبيل المثال، تتطلب الإعلانات في تطبيق بنظام iOS توفير عنوان URL لمتجر التطبيقات.

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

مثال

يوضح هذا المثال كيفية توفير صورة، وإنشاء الكائن AdCreative.

أولاً، أنشئ الكائن AdImage من ملف صورة:

curl \
  -F 'filename=@<IMAGE_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages

بعد ذلك، استخدم تجزئة الصورة لإنشاء AdCreative:

curl -X POST \
  -F 'name="Sample Creative"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "https://facebook.com/<PAGE_ID>",
         "message": "try it out"
       }
     }' \
  -F 'degrees_of_freedom_spec={
      "creative_features_spec": {
        "standard_enhancements": {
          "enroll_status": "OPT_IN"
        }
      }
    }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Open In Graph API ExplorerOpen In Postman

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

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

GET /{my-creative-id} HTTP/1.1
Host: graph.facebook.com/?fields=object_story_spec

الخطوة الخامسة: جدولة العرض

أخيرًا، أنشئ الكائن إعلان لربط AdCreative وAdSet. وحاول تعيين status في Ad إلى paused لتجنب تقديم طلب بشكل فوري.

curl -X POST \
  -F 'name="My Ad"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads
Open In Graph API ExplorerOpen In Postman
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
Open In Graph API ExplorerOpen In Postman
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API ExplorerOpen In Postman
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
Open In Graph API ExplorerOpen In Postman
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}
Open In Graph API ExplorerOpen In Postman
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})
Open In Graph API ExplorerOpen In Postman

تحقق من وجود إعلانك في مدير الإعلانات. وانقر على الحملة الإعلانية التي أنشأتها للتو، ثم على المجموعة الإعلانية وعلى الإعلان.

بمجرد أن تشعر بالراحة حيال الانتهاء من حجز الإعلانات باستخدام واجهة API، يمكنك تعيين الحالة إلى active. وأولًا، يخضع الإعلان لعملية مراجعة الإعلانات ويتم تعيينه إلى الحالة PENDING_REVIEW. وبمجرد الانتهاء من مراجعته، تتم إعادته إلى الحالة ACTIVE.

نسخ الإعلانات

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