广告商 API
通过这套 API,以编程方式计划广告活动并在 Twitter 上管理广告。
您可以推广什么?
推广推文
- 推广推文是广告商所购买的普通推文,他们希望覆盖更广泛的用户群或鼓励现有关注者的互动量。
- 当广告商为其在 Twitter 上的位置付款时,推广推文会被明确标记为已推广。在其他方面,推广推文就像普通推文一样,可以转推、回复、点赞等等。它们具有典型的投放规则,使用 POST statuses/update 创建。
- 通过 POST accounts/:account_id/tweet 创建的“纯推广”推文可用于推广推文广告活动,但不会投放给关注者或显示在公共时间线上。要检索某些账号的纯推广推文列表,请使用 GET accounts/:account_id/scoped_timeline。
推广账号
- 推广账号是推荐关注的一部分,为人们推荐目前尚未关注但有可能感兴趣的账号。推广账号有助于推荐人们可能喜欢的多种的账号。
- 时间线推广账号将推广推文与推广账号广告活动相关联,并将显示在用户的时间线中。
推广趋势不可用于广告 API。
广告活动和广告组(行项目)
广告活动定义广告的计划和预算。广告商指定每日和总体预算。广告活动可以绑定到特定开始和结束时间,也可以连续运行,直到预算用完为止。预算源自广告账号的支付手段之一。广告活动标识符(:campaign_id
)是我们在 Twitter 广告 UI 中的 Base-10 值的 Base-36 表示。
广告账号最多有 200 个活跃广告活动。根据请求,广告商的 Twitter 账号管理员可以手动将活跃广告活动的上限提高到 4,000 个。在广告活动到达结束时间或被删除之前,我们将其视为处于活跃状态。暂停的广告活动在指定结束时间之前被视为处于活跃状态。
分析
Twitter 广告 API 提供了一组分析端点,用于跟踪和优化广告效果。参阅分析和分析最佳实践了解更多信息。
对于计费指标,数据可能在事件发生三天后才最终确定。在此之前,应将其视为推测数据。最终的可计费数字总会小于推测数字。可计费数字会根据垃圾信息和相关劣质流量进行修正。有关时间的其他注意事项,请参阅时区。
创建广告活动 - 分步说明
以下示例假定您已安装、配置并授权应用,且用户使用的是 twurl。twurl 是符合 cURL 思维的命令行工具,可以完美处理 Twitter OAuth 的身份认证。twurl 是快速测试和调试广告 API(以及 REST API)功能的绝佳工具。若要查看请求和响应的完整标头,请使用 -t
跟踪调用,大致相当于 cURL 的 -v
选项。
例如,我们会创建由关键词定位的推广推文广告活动。
1.检索账号 ID。
twurl -H ads-api-sandbox.twitter.com /5/accounts/
{
"request": {
"params": {
}
},
"data": [
{
"name": "Sandbox account for @AdsAPI",
"timezone": "America/Los_Angeles",
"timezone_switch_at": null,
"id": "xxxxxx",
"created_at": "2014-03-09T00:41:49Z",
"salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
"updated_at": "2015-01-29T00:41:49Z",
"approval_status": "ACCEPTED",
"deleted": false
}
],
"data_type": "account",
"total_count": 1,
"next_cursor": null
}
2.检索支付手段 ID。
使用前面命令中检索到的账号 ID 点击 GET accounts/:account_id/funding_instruments API。
twurl -H ads-api-sandbox.twitter.com /5/accounts/xxxxxx/funding_instruments
{
"data": [
{
"account_id": "xxxxxx",
"cancelled": true,
"created_at": "2014-03-09T00:41:49Z",
"credit_limit_local_micro": null,
"currency": "USD",
"deleted": false,
"description": null,
"end_time": null,
"funded_amount_local_micro": null,
"id": "yyyy",
"start_time": "2014-05-29T00:41:49Z",
"type": null,
"updated_at": "2014-05-29T00:41:49Z"
}
],
"data_type": "funding_instrument",
"next_cursor": null,
"request": {
"params": {
"account_id": "xxxxxx"
}
},
"total_count": 1
}
3.创建与支付手段关联的广告活动。
指定广告活动的开始时间和预算。在此示例中,我们使用 500 美元的预算,并将每日限额设置为 50 美元。
twurl -H ads-api-sandbox.twitter.com -d "start_time=2019-02-09T00:00:00Z&funding_instrument_id=yyyy&name=My First Campaign&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /5/accounts/xxxxxx/campaigns
{
"data": {
"created_at": "2015-02-09T00:00:00Z",
"currency": "USD",
"daily_budget_amount_local_micro": 50000000,
"deleted": false,
"end_time": null,
"funding_instrument_id": "yyyy",
"id": "92ph",
"name": "My First Campaign",
"paused": false,
"standard_delivery": true,
"start_time": "2015-02-09T00:00:00Z",
"total_budget_amount_local_micro": 500000000,
"updated_at": "2015-02-09T00:00:00Z"
},
"data_type": "campaign",
"request": {
"params": {
"account_id": "xxxxxx",
"daily_budget_amount_local_micro": 50000000,
"funding_instrument_id": "yyyy",
"name": "My First Campaign",
"start_time": "2015-02-09T00:00:00Z",
"total_budget_amount_local_micro": 500000000
}
}
}
4.创建与广告活动关联的行项目。
现在,我们有了广告活动 ID,可以创建行项目并与其关联。行项目包含广告活动的出价、定位和实际素材部分。对于此行项目,我们会推广出价为 1.5 美元的推文。
twurl -H ads-api-sandbox.twitter.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=TWEET_ENGAGEMENTS&paused=true" /5/accounts/xxxxxxx/line_items
{
"data_type": "line_item",
"data": {
"bid_type": "MAX",
"name": "Untitled",
"placements": [
"ALL_ON_TWITTER"
],
"bid_amount_local_micro": 1500000,
"automatically_select_bid": false,
"advertiser_domain": null,
"primary_web_event_tag": null,
"charge_by": "ENGAGEMENT",
"product_type": "PROMOTED_TWEETS",
"bid_unit": "ENGAGEMENT",
"total_budget_amount_local_micro": null,
"objective": "TWEET_ENGAGEMENTS",
"id": "azjx",
"paused": true,
"optimization": "DEFAULT",
"categories": [],
"currency": "USD",
"created_at": "2015-02-09T00:00:00Z",
"updated_at": "2015-02-09T00:00:00Z",
"include_sentiment": "POSITIVE_ONLY",
"campaign_id": "92ph",
"deleted": false
},
"request": {
"params": {
"placements": [
"ALL_ON_TWITTER"
],
"bid_amount_local_micro": 1500000,
"product_type": "PROMOTED_TWEETS",
"paused": true,
"account_id": "xxxxxxx",
"campaign_id": "92ph"
}
}
}
5.创建与行项目关联的定位个人资料。
行项目创建完成后,即可分配定位标准。我们想在旧金山湾区的位置定位短语关键词“grumpy cat”。这将需要查找位置 ID 并提交两次 targeting_criteria POST 请求。
twurl -H ads-api-sandbox.twitter.com "/5/targeting_criteria/locations?location_type=CITIES&q=San Francisco"
{
"data": [
{
"name": "San Francisco-Oakland-San Jose CA, US",
"targeting_type": "LOCATION",
"targeting_value": "5122804691e5fecc"
}
],
"data_type": "targeting_criterion",
"request": {
"params": {
"location_type": "CITY",
"q": "San Francisco"
}
}
}
twurl -H ads-api-sandbox.twitter.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /5/accounts/xxxxxx/targeting_criteria
{
"data": {
"account_id": "xxxxxx",
"created_at": "2015-02-09T00:00:15Z",
"deleted": false,
"id": "2u3be",
"line_item_id": "yyyy",
"name": "San Francisco-Oakland-San Jose CA, US",
"targeting_type": "LOCATION",
"targeting_value": "5122804691e5fecc",
"updated_at": "2013-05-30T21:01:35Z"
},
"data_type": "targeting_criterion",
"request": {
"params": {
"account_id": "xxxxxx",
"line_item_id": "yyyy",
"targeting_type": "LOCATION",
"targeting_value": "5122804691e5fecc"
}
}
}
twurl -H ads-api-sandbox.twitter.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /5/accounts/xxxxxx/targeting_criteria
{
"data": {
"account_id": "xxxxxx",
"created_at": "2015-02-09T00:00:20Z",
"deleted": false,
"id": "2u3bd",
"line_item_id": "yyyy",
"name": "grumpy cat",
"targeting_type": "PHRASE_KEYWORD",
"targeting_value": "grumpy cat",
"updated_at": "2013-05-30T18:05:35Z"
},
"data_type": "targeting_criterion",
"request": {
"params": {
"account_id": "xxxxxx",
"line_item_id": "yyyy",
"targeting_type": "PHRASE_KEYWORD",
"targeting_value": "grumpy cat"
}
}
}
6.最后,取消暂停行项目。
twurl -H ads-api-sandbox.twitter.com -X PUT "/5/accounts/xxxxxx/line_items/yyyy/?paused=false"
{
"data_type": "line_item",
"data": {
"bid_type": "MAX",
"name": "grumpy cat",
"placements": [],
"bid_amount_local_micro": 1500000,
"automatically_select_bid": false,
"advertiser_domain": null,
"primary_web_event_tag": null,
"charge_by": "ENGAGEMENT",
"product_type": "PROMOTED_TWEETS",
"bid_unit": "ENGAGEMENT",
"total_budget_amount_local_micro": null,
"objective": "TWEET_ENGAGEMENTS",
"id": "yyyy",
"paused": false,
"account_id": "xxxxxx",
"optimization": "DEFAULT",
"categories": [],
"currency": "USD",
"created_at": "2015-02-09T00:00:20Z",
"updated_at": "2015-02-09T00:00:20Z",
"include_sentiment": "POSITIVE_ONLY",
"campaign_id": "dy1f",
"deleted": false
},
"request": {
"params": {
"line_item_id": "yyyy",
"paused": false,
"account_id": "xxxxxx"
}
}
}
就是这样!我们现在得到了一个正在运行且活跃、已定位并支付的时间线推广推文广告活动。