カード

: カードをツイートに関連付けるには、card_uriパラメーターをPOST accounts/:account_id/tweetPOST statuses/updatePOST accounts/:account_id/scheduled_tweetsPOST accounts/:account_id/draft_tweetsのいずれかのエンドポイントと併用します。

GET accounts/:account_id/cards

現在のアカウントに関連付けられている一部またはすべてのカードの詳細を取得します。

: 上記によって返されるカードは、POST accounts/:account_id/cardsエンドポイントを使用して作成されたもののみです。他のエンドポイントを使用して作成されたカードは返されません。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

card_uris
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的のカードのみに設定します。最大200件のカードURI値を指定できます。

タイプ: 文字列

例: card://1044294149527166979,card://1044301099031658496

count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 100
最小、最大: 11000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow

include_legacy_cards
任意

応答にレガシーのWebサイトとアプリカードを含めます。レガシーカードとは、リソースURLの形式がaccounts/:account_id/cards/:card_typeのカードです。詳細については、こちらの開発者フォーラムの投稿を参照してください。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse
q
任意

nameでカード範囲を指定する省略可能なクエリです。このパラメーターを省略すると、すべてが取得されます。最大長: 80文字。

: プレフィックスの一致は大文字と小文字を区別します。

タイプ: 文字列

例: dtc

sort_by
任意

サポートされている属性で昇順または降順に並べ替えます。詳細については、「並べ替え」を参照してください。

タイプ: 文字列

例: created_at-asc

with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/cards?count=1

応答の例

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

POST accounts/:account_id/cards

指定されたアカウントに関連付けられる新しいカードを作成します。

カード作成リクエストが受け入れるPOSTボディはJSONのみです。Content-Typeapplication/jsonに設定する必要があります。

カルーセルのガイドで詳細な使用例を参照してください。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/cards

パラメーター

JSON形式のPOSTボディにはnameカードとcomponentsの配列を含める必要があります。オブジェクトとして表されるコンポーネントでは、カードの広告主に表示する属性を説明します。

以下はペイロードの一般的な構造の例です(ただし機能していない情報も含まれます)。

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

コンポーネントに関する詳細は下表を参照してください。

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

components
必須

カードの作成に使用するコンポーネントを説明します。以下に補足情報があります。

: コンポーネントの順序が重要となります。

タイプ: オブジェクトの配列

name
必須

カードの名前。最大長: 80文字。

タイプ: 文字列

例: component based card

コンポーネント

各コンポーネントにはオブジェクトのスキーマを決めるtypeフィールドを含める必要があります。広告APIは次のコンポーネントタイプをサポートし、メディアベースと説明ベースのコンポーネントにグループ化されます。

  • メディア:
    • MEDIA: 単体の動画または画像
    • SWIPEABLE_MEDIA: 2~6点の動画または画像
  • 説明:
    • DETAILS
    • BUTTON

各コンポーネントには、typeキーに加えて一連の必須フィールドがあります。以下の表を参照してください。

コンポーネントtype フィールド 値のタイプ
MEDIA media_key 文字列
SWIPEABLE_MEDIA media_keys 文字列の配列
DETAILS title
destination
文字列
オブジェクト
BUTTON label
destination
オブジェクト
オブジェクト

以下はcomponents配列のコンテキストに含まれるBUTTONコンポーネントの例です(nameキーは意図的に省略しています)。(省略記号は追加情報を指定する必要がある箇所を示しています)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

コンポーネントオブジェクトの指定順序によって、表示する順序(上から下へ)が決まります。カードを作成するには、メディアベースのコンポーネント1つと、DETAILSBUTTONコンポーネントを使用する必要があります。説明ベースのコンポーネントはメディアの下に表示され、関連付けられたリンク先(URLまたはモバイルアプリ)があります。

ラベル

ラベルはボタンに表示されるテキストを定義するため、BUTTONコンポーネントのみに適用されます。ラベルオブジェクトには必須フィールドがtypevalueの2つあります。typeENUMに設定する必要があり、valueとしてBOOKCONNECTINSTALLOPENORDERPLAYSHOPのいずれかを使用できます。

上記の例に基づき、以下ではlabelオブジェクトがBUTTONコンポーネント内に示されます。

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

リンク先

リンク先は広告主がユーザーを誘導する場所であり、DETAILSまたはBUTTONコンポーネント内では常に必要です。リンク先にはWEBSITEAPPの2つのタイプがあります。

: ウェブサイトのリンク先はDETAILSコンポーネントとのみ併用でき、アプリのリンク先はBUTTONコンポーネントとのみ併用できます。

ウェブサイトのリンク先
名前 説明
type
必須

スキーマを決定するリンク先のタイプ。

タイプ: 列挙

使用可能な値: WEBSITE

url
必須

ユーザーのリダイレクト先となるウェブサイトのURL。

タイプ: 文字列

例: https://twittercommunity.com/c/advertiser-api

アプリのリンク先
名前 説明
type
必須

スキーマを決定するリンク先のタイプ。

タイプ: 列挙

使用可能な値: APP

country_code
必須

アプリが販売されている国の2文字のISOコード(ISO 3166-1 alpha-2)。

タイプ: 文字列

例: US

googleplay_app_id
必須の場合あり

Google Playアプリケーションパッケージの名前。

: ios_app_store_identifiergoogleplay_app_idの1つ以上が必須となります。

タイプ: 文字列

例: com.twitter.android

ios_app_store_identifier
必須の場合あり

iOSアプリストアID。

: ios_app_store_identifiergoogleplay_app_idの1つ以上が必須となります。

タイプ: 文字列

例: 333903271

googleplay_deep_link
任意

宣伝しているAndroidアプリへのディープリンク。

: googleplay_app_idが提供されている場合にのみ利用できます。

タイプ: 文字列

ios_deep_link
任意

宣伝しているiOSアプリへのディープリンク。

: ios_app_store_identifierが提供されている場合にのみ利用できます。

タイプ: 文字列

リクエストの例

POST https://ads-api.x.com/10/accounts/18ce54d4x5t/cards

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

応答の例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}