マーケティングAPI

スタートガイド

次のステップに従って、マーケティングAPIで初めての広告を作成しましょう。

開始する前に

グラフAPIと、Facebookの広告キャンペーン構造について十分に理解してください。呼び出しを行う準備ができたら、以下が必要になります。

以上のものを用意したら、API呼び出しを開始できます。マーケティング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が返されます。このIDを忘れずに保存してください。キャンペーンが作成されたことは、広告マネージャでも確認できます。

リソース:

ステップ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

上記の呼び出しから返される値に基づいて、米国(United States)在住で映画(movie)に興味のある人からなるオーディエンスを作成できます。ターゲット設定の仕様は、次のようになります。

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

ステップ3: 広告セットを作成し、予算、請求、最適化、期間を定義する

広告セットとは、1日の予算または通算予算、スケジュール、請求、最適化、ターゲット設定データを共有する広告のグループです。このステップでは、AdSetクラスから新しいオブジェクトを作成し、以下を指定する必要があります。

  • 期間: 広告の掲載期間。start_timeとend_timeを使用して設定します。
  • 予算: 支出を予定している金額。daily_budgetまたはlifetime_budgetを使用します。
  • 最適化: 広告で達成したい結果。optimization_goalを使用して設定します。
  • 請求: 支払い方法。billing_eventを使用します。
  • 入札価格: 最適化イベントの発生時に入札する金額。bid_amountフィールドを使用します。
  • ターゲット設定: ステップ2で作成したターゲット設定仕様を使用します。

広告セットを作成するには、ステップ1で保存した広告キャンペーンIDも必要です。

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アプリの広告では、App StoreのURLが必要です。

クリエイティブは、広告セットの一部またはスタンドアローンとして定義できます。いずれの場合も、Facebookは広告クリエイティブを広告内で使用するために、広告アカウントのクリエイティブライブラリに格納します。

例

この例では、画像を指定して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はまだ広告マネージャに表示されません。このデータは、広告を予約すると表示されるようになります。グラフAPIエクスプローラを使用して、広告クリエイティブをデバッグできます。読み取りたいフィールドは次のように指定します。

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

ステップ5: 配信スケジュールを設定する

最後に、広告オブジェクトを作成してAdCreativeとAdSetをリンクします。Adのstatusを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に戻ります。

広告をコピーする

広告を作成する代わりに、既存の広告、アセット、キャンペーンをコピーすることもできます。コピーを使用すると、キャンペーンを手早く複製して設定を変更したり、テストグループを作成してパフォーマンス情報を抽出したりできます。詳しくは、以下をご覧ください。