カルーセル

Guides 目次

はじめに

Twitter広告APIでは動画カルーセルと画像カルーセルの作成と取得をサポートしています。カルーセルは2～6個のメディアアセットを含めることができるカードのタイプです。カルーセルカードを使用して、任意のウェブサイトにユーザーを誘導したり、モバイルアプリのインストールをユーザーに促したりできます。カルーセルの詳細、利点、ベストプラクティス、よくある質問については、当社の「Twitterのカルーセル広告」ページを参照してください。

他のカードタイプと同じく、カルーセルをツイートで使用して、そのツイートをプロモーションすることができます。ワークフローは以下のとおり、慣れ親しんだものと同じです。

メディアをアップロードする
カードを作成する
ツイートを作成する
ツイートをプロモーションする

唯一違う点はカードの作成方法です。他のカードの作成リクエストではクエリパラメータを受け入れますが、カルーセルカードの作成リクエストではJSON形式のPOSTボディのみを受け入れます。

エンドポイント

広告APIではカルーセルの作成と取得をサポートします。

タイプを問わず、カルーセルを作成するには、POST accounts/:account_id/cardsエンドポイントを使用します。カルーセルを取得するには、GET accounts/:account_id/cardsエンドポイントを使用します。

JSON形式のPOSTボディ

カルーセルは2つのコンポーネントを使用して作成されます。1つ目は使用するメディアアセットを指定します。2つ目はウェブサイトまたはアプリに関する情報を指定します。

具体的には、カルーセルカードを作成するには次のコンポーネントを順番に使用します。

SWIPEABLE_MEDIAコンポーネント1つ。これでメディアキーの配列を受け入れます
次のうちから1つ。
- ウェブサイト情報を指定するDETAILSコンポーネント
- アプリ情報を指定するBUTTONコンポーネント

SWIPEABLE_MEDIAコンポーネントにはmedia_keys配列を含める必要があります。配列には2～6点の画像または動画を指定できます。メディアキーが渡される順序によって表示される順番が決まります。

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

なお、メディアキーはGET accounts/:account_id/media_libraryエンドポイントにリクエストして取得できます。

2つ目のコンポーネントオブジェクトの構成は、ユーザーをウェブサイトに誘導するか、アプリのインストールを促すかに応じて異なります。2つのオプションについて以下の表にまとめました（注: 列挙したすべてのキーは必須です）。

	ウェブサイト	アプリ
コンポーネントのタイプを指定	"type":"DETAILS"	"type":"BUTTON"
ウェブサイトカルーセルがメディアの下に表示されるタイトル（ヘッドライン）を受け入れるアプリカルーセルの`label`オブジェクトはボタンラベルを指定	"title":"Twitter"	"label": { "type":"ENUM", "value":"INSTALL" }
ウェブサイトカルーセルのリンク先はウェブサイトのURL アプリカルーセルのリンク先はアプリとそれに対応する属性	"destination": { "type":"WEBSITE", "url": "https://www.twitter.com" }	"destination": { "type":"APP", ... }

上記をすべてまとめたウェブサイトカルーセルのJSON形式のPOSTボディの例を以下に示します。

{
  "name": "website carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "Twitter",
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.twitter.com"
      }
    }
  ]
}

BUTTONコンポーネント内のアプリリンク先オブジェクトには国コードと1つ以上のアプリIDが必要です。あるいはディープリンクを受け入れます。これらフィールドの説明については、リファレンスドキュメントを参照してください。

上記をすべてまとめたアプリカルーセルのJSON形式のPOSTボディの例を以下に示します。

{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

例

このセクションでは動画ウェブサイトのカルーセルカードの作成方法とツイートでの使用方法を説明しています。上述のとおり、ワークフローはメディアのアップロード、カードの作成、ツイートの作成といった慣れ親しんだものです。唯一違う点はカードの作成方法です。

メディア

まず、メディアアセットを新規にアップロードするか、既存のものを使用します。新しいメディアアセットをアップロードしてメディアライブラリに追加する方法について詳しくは、メディアライブラリのガイドを参照してください。

メディアアセットがメディアライブラリに追加されたら、GET accounts/:account_id/media_libraryエンドポイントを使用して取得します。media_typeリクエストパラメータを使用して、結果を特定のメディアタイプに絞ります。

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

カルーセルの作成

POST accounts/:account_id/cardsエンドポイントを使用してカルーセルを作成します。前のリクエストのメディアキーを使用します。メディアキーが渡される順序によって表示される順番が決まることにご留意ください。

$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "Twitter","destination":{"type":"WEBSITE", "url":"https://www.twitter.com"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "website carousel",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "Twitter",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.twitter.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

他のカードのように、カルーセルカードの応答には、card_uriが含まれ、これはツイートの作成時に使用されます。

POST accounts/:account_id/tweetエンドポイントを使用してツイートを作成します。前のリクエストからcard_uriを使用します（応答は読みやすいように一部省略されています）。

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "Ads API Internal Test App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

ツイートのプレビュー

GET accounts/:account_id/tweet_previewsを使用して、ツイートを表示します。

スワイプ
— API McTestface (@apimctestface) 2020年11月11日