卡片

在 Postman 中运行 ❯

注意：要将卡片关联到推文，请通过 POST accounts/:account_id/tweet、POST statuses/update、POST accounts/:account_id/scheduled_tweets 或 POST accounts/:account_id/draft_tweets 端点，使用 card_uri 参数来完成。

GET accounts/:account_id/cards¶

检索与当前账号关联的部分或所有卡片的详细信息。

注意：这仅返回使用 POST accounts/:account_id/cards 端点创建的卡片。不会返回使用其他端点创建的卡片。

资源 URL¶

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

参数¶

名称	说明
account_id 必需	所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。类型：string 示例：`18ce54d4x5t`
card_uris 可选	通过指定以逗号分隔的标识符列表，将响应范围限定至所需的卡片。可最多提供 200 个卡片 URI 值。类型：string 示例：`card://1044294149527166979,card://1044301099031658496`
count 可选	指定每个不同请求尝试检索的记录数量。类型：int 默认值：`100` 最小值、最大值：`1`、`1000`
cursor 可选	指定光标以获取下一页结果。参阅分页了解更多信息。类型：string 示例：`8x7v00oow`
include_legacy_cards 可选	在响应中包含原网站和应用卡片。原卡片是资源 URL 采用以下格式的卡片：accounts/:account_id/cards/:card_type。有关其他上下文，请参阅此开发者论坛帖子。类型：boolean 默认值：`false` 可能值：`true`、`false`
q 可选	可选查询，按 `name` 指定卡片范围。省略此参数可检索所有卡片。最大长度：80 个字符。注意：执行不区分大小写的前缀匹配。类型：string 示例：`dtc`
sort_by 可选	根据支持的属性，按升序或降序排序。参阅排序了解更多信息。类型：string 示例：`created_at-asc`
with_deleted 可选	在请求中包含已删除的结果。类型：boolean 默认值：`false` 可能值：`true`、`false`

请求示例¶

GET https://ads-api.twitter.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¶

创建关联到指定账号的新卡片。

卡片创建请求只接受 JSON POST 正文。Content-Type 必须设置为 application/json。

请查看我们的轮播指南，了解详细用例。

资源 URL¶

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

参数¶

JSON POST 正文必须包含卡片 name 和 components 数组。组件以对象的形式表示，用于描述卡片中面向广告商的属性。

以下示例显示了有效负荷的常规结构（但包含无效信息）。

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

组件的其他信息如下所示。

名称说明

account_id
必需

所使用账号的标识符。出现在资源路径中，通常是所有广告商 API 请求的必要参数，不包含 GET accounts。指定账号必须与已验证的用户关联。

类型：string

示例：18ce54d4x5t

components
必需

描述用于创建卡片的组件。其他信息如下所示。

注意：组件的顺序很重要。

类型：对象数组

name
必需

卡片名称。最大长度：80 个字符。

类型：string

示例：component based card

组件¶

每个组件都必须包含一个用于确定对象架构的 type 字段。广告 API 支持以下组件类型，分为基于媒体的组件和基于说明的组件。

媒体：
- MEDIA：一个视频或一张图像
- SWIPEABLE_MEDIA：介于 2-6 个视频/图像之间
说明：
- DETAILS
- BUTTON

除了 type 键，每个组件还有一组必填字段。它们如下表所示。

组件 `type`	字段	值类型
`MEDIA`	`media_key`	string
`SWIPEABLE_MEDIA`	`media_keys`	字符串数组
`DETAILS`	`title` `destination`	string object
`BUTTON`	`label` `destination`	object object

以下是 components 数组上下文中的 BUTTON 组件示例（有意省略了 name 键）。（省略号表示需要指定更多信息的位置。）

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

指定组件对象的顺序定义了将按从上到下的顺序显示这些对象。必须使用一个基于媒体的组件以及 DETAILS 或 BUTTON 组件来创建卡片。基于说明的组件在媒体下显示，且具有关联的目标（URL 或移动应用）。

目标

目标是广告商打算吸引用户的位置。DETAILS 或 BUTTON 组件中始终必须设置目标。目标有两种类型：WEBSITE 或 APP。

注意：网站目标只能与 DETAILS 组件一起使用，应用目标只能与 BUTTON 组件一起使用。

网站目标

名称说明

名称	说明
type 必需	目标类型，用于确定其架构。类型：enum 可能值：`WEBSITE`
url 必需	重定向用户转到的网站 URL。类型：string 示例：`https://twittercommunity.com/c/advertiser-api`

type
必需

目标类型，用于确定其架构。

类型：enum

可能值：WEBSITE

url
必需

重定向用户转到的网站 URL。

类型：string

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

应用目标

名称	说明
type 必需	目标类型，用于确定其架构。类型：enum 可能值：`APP`
country_code 必需	出售应用的国家/地区的 ISO 3166-1 alpha-2 代码，长度为两个字母。类型：string 示例：`US`
googleplay_app_id 有时为必需	Google Play 应用程序包名称。注意：必须填写以下值之一：`ios_app_store_identifier` 或 `googleplay_app_id`。类型：string 示例：`com.twitter.android`
ios_app_store_identifier 有时为必需	iOS 应用商店标识符。注意：必须填写以下值之一：`ios_app_store_identifier` 或 `googleplay_app_id`。类型：string 示例：`333903271`
googleplay_deep_link 可选	正在推广的 Android 应用的深层链接。注意：仅可在已提供 `googleplay_app_id` 时使用。类型：string
ios_deep_link 可选	正在推广的 iOS 应用的深层链接。注意：仅可在已提供 `ios_app_store_identifier` 时使用。类型：string

请求示例¶

POST https://ads-api.twitter.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"
  }
}

卡片

GET accounts/:account_id/cards¶

资源 URL¶

参数¶

请求示例¶

响应示例¶

POST accounts/:account_id/cards¶

资源 URL¶

参数¶

组件¶

标签

目标

网站目标

应用目标

请求示例¶

响应示例¶