轮播 | Twitter Developer Platform

Guides contents

媒体库

识别卡片

轮播

简介

Twitter 广告 API 支持创建和检索视频轮播和图像轮播。轮播是一种卡片类型，可包含 2 到 6 个媒体资产。轮播卡片可以引导用户访问网站或鼓励他们安装移动应用。若要详细了解轮播、其优势、最佳实践和常见问题，请查看 Twitter 上的轮播广告页面。

与其他任何卡片类型一样，可在推文中使用轮播，然后推广这些推文。该工作流程与你常用的工作流程相同：

上传媒体
创建卡片
创建推文
推广推文

唯一的区别是卡片的创建方式。其他卡片创建请求可接受查询参数，而轮播卡片创建请求仅接受 JSON POST 正文。

端点

广告 API 支持创建和检索轮播。

要创建任何类型的轮播，请使用 POST accounts/:account_id/cards 端点。要检索轮播，请使用 GET accounts/:account_id/cards 端点。

JSON POST 正文

轮播使用两个组件创建而成。第一个指定将要使用的媒体资产。第二个指定网站或应用的相关信息。

具体来说，轮播卡片是按顺序使用以下组件创建的：

一个 SWIPEABLE_MEDIA 组件，它接受一组媒体密钥
以下组件之一：
- DETAILS 组件，用于指定网站信息
- BUTTON 组件，用于指定应用信息

SWIPEABLE_MEDIA 组件，必须包含 media_keys 数组，你可在其中指定 2-6 个图像或视频。媒体密钥的传递顺序决定了它们的显示顺序。

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

请注意，你可向 GET accounts/:account_id/media_library 端点发出请求，以获取媒体密钥。

第二个组件对象的组成部分取决于你是希望将用户引导到网站还是鼓励他们安装应用。下表总结了这两个选项。（注意：列出的所有密钥都是必需的。）

	网站	应用
指定组件类型	"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 组件内的应用目标对象需要国家/地区代码，还至少需要一个应用标识符。它们可以选择性地接受深层链接。有关这些字段的说明，请查看参考文档。

将这些内容放在一起，就构成了下面显示的应用轮播 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.twitter.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.twitter.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.twitter.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) November 11, 2020