カードの識別

はじめに

カードはメディアを利用したカスタマイズ可能な広告フォーマットです。ウェブサイト、アプリ、アクション誘導に関連付けて、ダイレクトメッセージの開始など、特定のユーザーアクション（エンゲージメント）を促すことができます。ツイート、予約投稿ツイート、下書きツイートに追加できます。

カードは2つの方法のいずれか（カードのcard_uriまたはpreview_url）でツイートオブジェクトを参照できます。それぞれのサンプル値を次に示します。

注: 広告APIバージョン3ではcard_uriのみが生成され、新たに作成されたカードのカード応答で返されます。

注: 広告APIバージョン5ではカード応答のpreview_urlは返されなくなります。

ツイートオブジェクト応答の参照タイプは、ツイートの作成方法によって異なります。つまり、ツイートがcard_uriリクエストパラメーターを使って作成された場合、応答でそのカードURI値が表示されます。一方、ツイートテキストの一部としてpreview_urlが含まれる場合は、応答でプレビューURLが表示されます。

card_uriを使ったツイートの識別

ツイートがカードのURI値を使って作成された場合、card_uri応答属性でカードへの参照を確認します。次の応答の例では、GET accounts/:account_id/tweetsエンドポイントを使用しています。

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

標準APIを利用する場合は、リクエストでinclude_card_uri=trueを使います。

使用するエンドポイントの種類にかかわらず、card_uriの応答属性は、ツイートがカードのURIを使用して作成された場合にのみ表示されます。

予約投稿ツイートと下書きツイートオブジェクトの場合、応答には常にcard_uri応答属性が含まれます。

preview_urlを使ったツイートの識別

ツイートテキストの一部としてプレビューURLを含めて作成されたツイートの場合、URLはentities["urls"][i]["expanded_url"] で見つかります（textフィールドには省略されたt.co URLが含まれます）。ここでの「i」は配列インデックスです（ツイートには複数のURLを含めることができます）。

予約投稿ツイートと下書きツイートオブジェクトの場合、プレビューURLは常にtextフィールドに表示されます。

カードの取得

特定のカードに関する追加情報を取得するために、2つのエンドポイント（GET accounts/:account_id/cards/allとGET accounts/:account_id/cards/all/:card_id）が用意されています。前者を使うとcard_uri別に、後者を使うとカードのID別に情報を取得できます。カードのIDはpreview_urlの最後に記載されています。上の例の場合、IDは「68w3s」です。