カード

注: カードをツイートに関連付けるには、card_uriパラメーターをPOST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets、POST 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

パラメーター¶

リクエストの例¶

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-Typeはapplication/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"
    }
  ]
}

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

コンポーネント¶

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

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

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

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

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

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

ラベル

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

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

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

リンク先

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

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

ウェブサイトのリンク先

アプリのリンク先

リクエストの例¶

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"
  }
}