広告主API

プロモーションの対象

キャンペーンと広告グループ（行項目）

キャンペーンでは、広告のスケジュールと予算を定義します。広告主は、日別予算と全体の予算を指定します。キャンペーンは、特定の開始時間と終了時間にバインドできるほか、予算が消費されるまで継続的に実行することもできます。予算は、広告アカウントのいずれかのお支払い方法を使用して指定します。キャンペーンID（:campaign_id）は、Twitter広告UIに表示される10進法の値の36進法で表されます。

広告アカウントのアクティブキャンペーンには最大200件の制限があります。この上限は、リクエストに応じて、4,000件のアクティブキャンペーンに引き上げることができます。その際には、広告主のTwitterアカウントマネージャーが手動で設定します。キャンペーンは、終了時間に達するか、削除されるまではアクティブであると見なされます。一時停止されているキャンペーンは、指定された終了時間までアクティブであると見なされます。

行項目は、キャンペーンで定義された予算を消費します。行項目は、エンゲージメントあたりの入札額、プロモートするツイートまたはアカウント、ターゲティングルールをまとめたものです。

アナリティクス

Twitter広告APIには、広告のパフォーマンスを追跡して最適化するための、一連のアナリティクスエンドポイントが用意されています。詳細については、「アナリティクス」と「アナリティクスのベストプラクティス」を参照してください。

請求メトリックについては、データはイベントの3日後まで確定されない場合があります。それまでは、推定データとして取り扱う必要があります。最終的な請求可能額は、推定金額よりも常に少なくなります。請求可能額は、スパムや関連する低品質トラフィックで修正されます。時間に関して考慮すべきその他の事項については、「タイムゾーン」を参照してください。

キャンペーンの作成 - 詳細な手順

次の例は、twurlを使用してアプリとユーザーのインストール、設定、承認を行ったと想定しています。twurlは、TwitterのOAuth認証を適切に処理する、cURLの理念を受け継いだコマンドラインツールです。twurlは、広告API（およびREST API）機能をすばやくテスト、デバッグする優れたツールです。リクエストと応答のヘッダー全体を表示するには、-tを使用して呼び出しを追跡します。これは、cURLの-vオプションとほぼ同じものです。

この例では、キーワードでターゲティングするプロモツイートキャンペーンを作成します。

1.アカウントIDを取得します。

twurl -H ads-api-sandbox.twitter.com /9/accounts/

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Sandbox account for @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}

2.お支払い方法IDを取得します。

前のコマンドで取得したアカウントIDを使用して、GET accounts/:account_id/funding_instruments APIを実行します。

twurl -H ads-api-sandbox.twitter.com /9/accounts/xxxxxx/funding_instruments

{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "start_time": "2014-05-29T00:41:49Z",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}

3.キャンペーンを作成し、お支払い方法に関連付けます。

キャンペーンの開始時間と予算を指定します。この例では、予算500ドル、1日の上限50ドルを使用します。

twurl -H ads-api-sandbox.twitter.com -d "start_time=2019-02-09T00:00:00Z&funding_instrument_id=yyyy&name=My First Campaign&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /9/accounts/xxxxxx/campaigns

{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "My First Campaign",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "start_time": "2015-02-09T00:00:00Z",
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "My First Campaign",
      "start_time": "2015-02-09T00:00:00Z",
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4.キャンペーンに関連付けた行項目を作成します。

キャンペーンIDを取得してあるため、それに関連付けた行項目を作成できます。行項目には、入札価格、ターゲティング、キャンペーンの実際のクリエイティブ部分が含まれます。この行項目では、1.50ドルの入札額でツイートをプロモーションします。

twurl -H ads-api-sandbox.twitter.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=ENGAGEMENTS&entity_status=PAUSED" /9/accounts/xxxxxxx/line_items

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "azjx",
    "entity_status": "PAUSED",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:00Z",
    "updated_at": "2015-02-09T00:00:00Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "92ph",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 1500000,
      "product_type": "PROMOTED_TWEETS",
      "entity_status": "PAUSED",
      "account_id": "xxxxxxx",
      "campaign_id": "92ph"
    }
  }
}

5.行項目に関連付けるターゲティングプロフィールを作成します。

作成した行項目を使用すると、ターゲティング条件を割り当てることができます。サンフランシスコのベイエリア地域でフレーズキーワード「グランピーキャット」というフレーズをターゲティングします。これには、地域IDの検索と2つのtargeting_criteria POSTリクエストが必要になります。

twurl -H ads-api-sandbox.twitter.com "/9/targeting_criteria/locations?location_type=CITIES&q=San Francisco"

{
  "data": [
    {
      "name": "San Francisco-Oakland-San Jose CA, US",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}

twurl -H ads-api-sandbox.twitter.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}

twurl -H ads-api-sandbox.twitter.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:20Z",
    "deleted": false,
    "id": "2u3bd",
    "line_item_id": "yyyy",
    "name": "grumpy cat",
    "targeting_type": "PHRASE_KEYWORD",
    "targeting_value": "grumpy cat",
    "updated_at": "2013-05-30T18:05:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "PHRASE_KEYWORD",
      "targeting_value": "grumpy cat"
    }
  }
}

6.最後に、行項目の一時停止を解除します。

 twurl -H ads-api-sandbox.twitter.com -X PUT "/9/accounts/xxxxxx/line_items/yyyy/?entity_status=ACTIVE"

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "grumpy cat",
    "placements": [],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "yyyy",
    "entity_status": "ACTIVE",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "ACTIVE",
      "account_id": "xxxxxx"
    }
  }
}

これで完了です。これで、実行中のタイムラインキャンペーンで、ターゲティングした有料のアクティブなプロモツイートが掲載されます。