Marketing API

Начало работы

Следуйте этим указаниям, чтобы создать объявление с помощью Marketing API.

Прежде чем начать

Ознакомьтесь с возможностями Graph API и структурой рекламных кампаний Facebook. Для выполнения вызовов вам понадобятся:

После этого можно начинать работу. Советуем ознакомиться с рекомендациями по использованию Marketing API.

Шаг 1. Создание кампании

Создайте объект кампании (объект класса 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

В случае успеха возвращается ID созданной рекламной кампании. Сохраните его. Чтобы убедиться, что кампания создана, можно также найти ее в Ads Manager.

Ресурсы:

Шаг 2. Настройка таргетинга

Справочная документация

Перед созданием групп объявлений следует определить целевую аудиторию. Затем вы сможете создать группу объявлений и настроить атрибуты аудитории.

Существует множество параметров таргетинга. В этом примере мы используем поиск для таргетинга, чтобы найти предустановленные значения, которые можно использовать для настройки аудитории.

Сначала выполняется поиск среди доступных стран по запросу 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'}]
}

Шаг 3. Создание группы объявлений и выбор бюджета, биллинга, параметров оптимизации и продолжительности

Группа объявлений — это набор объявлений с общим бюджетом (дневным или на весь срок действия группы), графиком показа, биллингом, а также параметрами оптимизации и таргетинга. На этом шаге нужно создать новый объект класса AdSet и задать для него следующие параметры:

  • Продолжительность — как долго будет показываться реклама. Задайте ее в параметрах start_time и end_time.
  • Бюджет — сумма, которую вы готовы потратить. Используйте daily_budget или lifetime_budget.
  • Оптимизация — результаты, которые вы хотите получить. Для настройки используйте optimization_goal.
  • Биллинг — как вы собираетесь оплачивать расходы на рекламу. Используйте billing_event.
  • Ставка — какую ценность имеет для вас событие оптимизации. Используйте поле bid_amount.
  • Таргетинг — используйте параметры таргетинга, созданные на шаге 2.

Для создания группы объявлений также необходим ID рекламной кампании, сохраненный на шаге 1:

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, чтобы избежать списания средств при тестировании.

Шаг 4. Предоставление рекламного креатива

Справочная документация

На этом шаге нужно настроить визуальные элементы объявления с помощью объекта 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

Убедитесь, что вы загрузили изображение. Для этого перейдите в Библиотеку медиафайлов в Ads Manager.

На этом этапе AdCreative с вашей ссылкой ещё не отображается в Ads Manager. Вы увидите эти данные, когда закажете рекламу. Выполнить отладку рекламного креатива и указать поля для чтения можно с помощью Graph API Explorer:

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

Шаг 5. График показа

Теперь создайте объект объявления, с которым будут связаны 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

Убедитесь, что реклама добавлена в Ads Manager. Нажмите созданную кампанию, затем группу объявлений, а затем объявление.

Когда вы будете готовы заказать рекламу через API, выберите для нее статус active. Реклама пройдет проверку, на время которой для нее будет установлен статус PENDING_REVIEW. Когда проверка завершится, статус ACTIVE будет восстановлен.

Копирование рекламы

Вы также можете скопировать существующие объявления, объекты или кампании. Эта функция позволяет продублировать кампанию, чтобы изменить ее настройки или создать тестовые группы для оценки результативности. Подробнее см. в следующих разделах: