広告主API

この一連のAPIを利用すると、プログラムを使用してキャンペーンのスケジュールを設定し、Twitter上の広告を管理できます。

プロモーションの対象

プロモツイート

  • プロモツイートは、より幅広いユーザーグループにリーチしたり、既存のフォロワーによるエンゲージメントを促進したりしようとする広告主が購入する一般的なツイートです。
  • 広告主がTwitterの配置に料金を支払っている場合は、プロモツイートには「プロモ」のラベルが明示されます。それ以外の点は、プロモツイートは通常のツイートとまったく同じように機能し、リツイート、返信、いいねなどを行うことができます。通常の配信ルールを持ち、POST statuses/updateを使用して作成されます。
  • POST accounts/:account_id/tweetで作成した「プロモーション専用」ツイートは、プロモツイートキャンペーンで使用できますが、フォロワーには配信されず、公開タイムラインにも表示されません。特定のアカウントのプロモーション専用ツイートのリストを取得するには、GET accounts/:account_id/scoped_timelineを使用します。

プロモアカウント

  • プロモアカウントは、おすすめアカウントの一部です。つまり、アカウントが現在フォローしていないアカウントで、興味関心を持つと思われるアカウントを提案します。プロモアカウントは、アカウントが楽しめる、より幅広い多様なアカウントを紹介するのに役立ちます。
  • タイムラインのプロモアカウントでは、プロモツイートがプロモアカウントキャンペーンに関連付けられると、ユーザーのタイムラインに表示されます。

プロモトレンドは、広告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"
    }
  }
}

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