Campaign Management

Video Views Pre-roll Objective

The implementation of a Video View Pre-roll campaign, also referred to as In-stream Ads, is very similar to how a VIDEO_VIEWS campaign would be set-up, with a few additional parameters that must be set in order for you to start serving ads. This guide includes a brief summary of the steps necessary to get started.

Table of Contents

Endpoints Required

Steps

Upload the video

Uploading the video involves 3 steps:

Upload the video media

First, using the Chunked media upload endpoint, you will upload the video to Twitter for processing. You must pass the media_category=amplify_video on the initial INIT using this endpoint. You’ll upload the video in chunks. Once the STATUS returns a state of succeeded you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our Promoted Video Overview.

Add the video to the ads account

Once the state returned using the STATUS command is succeeded, you’ll use the media_id returned from that endpoint to add the video to the advertiser’s library, using the POST accounts/:account_id/videos endpoint.

POST https://ads-api.twitter.com/3/abc123/videos
video_media_id=553639437322563584&Preroll+Sample+Video

{  
  "data_type":"video",
  "data":{  
    "id":"96150270-a549-4304-884e-6ba87d9bfcbd"
  },
  "request":{  
    "params":{  
      "video_media_id":553639437322563584,
      "title":"Preroll Sample Video",
      "account_id":"abc123"
    }
  }
}

Transform the video into a pre-roll asset

Transform the video into a pre-roll media asset, validating that it is eligible based on length, etc. using the PREROLL creative type on the POST accounts/:account_id/account_media endpoint.

POST https://ads-api.twitter.com/3/accounts/abc123/account_media
video_id=96150270-a549-4304-884e-6ba87d9bfcbd&creative_type=PREROLL

{  
  "data_type":"account_media",
  "data":{  
    "video_id":"96150270-a549-4304-884e-6ba87d9bfcbd",
    "media_url":null,
    "creative_type":"PREROLL",
    "id":"knb",
    "account_id":"abc123",
    "created_at":"2016-02-11T03:30:34Z",
    "updated_at":"2016-02-11T03:30:34Z",
    "deleted":false
  },
  "request":{  
    "params":{  
      "account_id":"abc123",
      "video_id":"96150270-a549-4304-884e-6ba87d9bfcbd",
      "creative_type":"PREROLL"
    }
  }
}

Setup the campaign

Campaign Creation

Create the campaign and line item/ad group. Line items should be created with an objective of VIDEO_VIEWS_PREROLL, and a product_type of MEDIA. The categories parameter must also be set to the appropriate content categories.

POST https://ads-api.twitter.com/3/accounts/abc123/campaigns
name=Preroll+Sample&funding_instrument_id=i7o2d&start_time=2016-03-01T00%3A00%3A00Z&paused=true&daily_budget_amount_local_micro=550000000

{  
  "data_type":"campaign",
  "data":{  
    "name":"Preroll Sample",
    "start_time":"2016-03-01T00:00:00Z",
    "reasons_not_servable":[  
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable":false,
    "daily_budget_amount_local_micro":550000000,
    "end_time":null,
    "funding_instrument_id":"i7o2d",
    "duration_in_days":null,
    "standard_delivery":true,
    "total_budget_amount_local_micro":null,
    "id":"47axj",
    "paused":true,
    "account_id":"abc123",
    "frequency_cap":null,
    "currency":"USD",
    "created_at":"2016-02-11T04:59:59Z",
    "updated_at":"2016-02-11T04:59:59Z",
    "deleted":false
  },
  "request":{  
    "params":{  
      "name":"Preroll Sample",
      "start_time":"2016-03-01T00:00:00Z",
      "daily_budget_amount_local_micro":550000000,
      "funding_instrument_id":"i7o2d",
      "paused":true,
      "account_id":"abc123"
    }
  }
}

Line Item Creation

Line items must have the categories parameter set to the appropriate set of IAB categories, retrieved via the GET content_categories endpoint. These content categories each correspond to one or more IAB categories.

In order to use these values, partners must select an appropriate content category and use the entire set of iab_categories returned in the response, to set the categories parameter on the line items endpoint. Any partial application of the iab_categories will result in the entire group being set on the line item. For example,

GET https://ads-api.twitter.com/3/content_categories

{
  "data": [
    {
      "id": "st",
      "name": "Alcohol",
      "iab_categories": [
        "IAB8-18",
        "IAB8-5"
      ]
    },
    {
      "id": "ru",
      "name": "Automotive (Cars, Trucks, Racing)",
      "iab_categories": [
        "IAB2"
      ]
    },
    {
      "id": "sk",
      "name": "Comedy",
      "iab_categories": [
        "IAB1-4"
      ]
    },
    {
      "id": "sl",
      "name": "Digital Creators",
      "iab_categories": [
        "IAB25-1"
      ]
    },
    {
      "id": "sm",
      "name": "Entertainment & Pop Culture",
      "iab_categories": [
        "IAB1-1",
        "IAB1-2",
        "IAB1-3",
        "IAB1-5"
      ]
    },
    {
      "id": "sn",
      "name": "Financial & Business News",
      "iab_categories": [
        "IAB3",
        "IAB13",
        "IAB21"
      ]
    },
    {
      "id": "so",
      "name": "Food & Drink",
      "iab_categories": [
        "IAB8-8",
        "IAB8-12",
        "IAB8-17",
        "IAB8-2",
        "IAB8-3",
        "IAB8-7",
        "IAB8-11",
        "IAB8-4",
        "IAB8-14",
        "IAB8-10",
        "IAB8-15",
        "IAB8-13",
        "IAB8-9",
        "IAB8-16",
        "IAB8-6",
        "IAB8-1"
      ]
    },
    {
      "id": "sp",
      "name": "Lifestyle (Fashion, Travel, Wellness)",
      "iab_categories": [
        "IAB16",
        "IAB9-21",
        "IAB9-4",
        "IAB9-25",
        "IAB9-8",
        "IAB4",
        "IAB9-3",
        "IAB9-15",
        "IAB7",
        "IAB6",
        "IAB9-11",
        "IAB9-16",
        "IAB9-7",
        "IAB9-20",
        "IAB9-24",
        "IAB9-17",
        "IAB9-12",
        "IAB9-31",
        "IAB9-27",
        "IAB10",
        "IAB9-10",
        "IAB9-23",
        "IAB9-6",
        "IAB9-18",
        "IAB9-13",
        "IAB9-1",
        "IAB9-28",
        "IAB20",
        "IAB9-5",
        "IAB9-26",
        "IAB22",
        "IAB23",
        "IAB9-9",
        "IAB9-22",
        "IAB18",
        "IAB9-2",
        "IAB9-19",
        "IAB9-14",
        "IAB9-29"
      ]
    },
    {
      "id": "sq",
      "name": "Music",
      "iab_categories": [
        "IAB1-6"
      ]
    },
    {
      "id": "sr",
      "name": "News & Current Events",
      "iab_categories": [
        "IAB12",
        "IAB14"
      ]
    },
    {
      "id": "s4",
      "name": "Politics",
      "iab_categories": [
        "IAB11"
      ]
    },
    {
      "id": "ss",
      "name": "Science & Education",
      "iab_categories": [
        "IAB5",
        "IAB15"
      ]
    },
    {
      "id": "se",
      "name": "Sports",
      "iab_categories": [
        "IAB17"
      ]
    },
    {
      "id": "sg",
      "name": "Technology",
      "iab_categories": [
        "IAB19"
      ]
    },
    {
      "id": "sh",
      "name": "Television",
      "iab_categories": [
        "IAB1-7"
      ]
    },
    {
      "id": "s0",
      "name": "eSports & Video Games",
      "iab_categories": [
        "IAB9-30"
      ]
    }
  ],
  "next_cursor": null,
  "request": {
    "params": {}
  }
}

Now, in order to set the categories parameter to "Science & Education", the entire set of iab_categories i.e., "IAB5", "IAB15" must be set for the line item, like so:

POST https://ads-api.twitter.com/3/accounts/abc123/line_items?campaign_id=47axj&bid_amount_local_micro=5500000&name=Ad+Group+1&product_type=MEDIA&placements=ALL_ON_TWITTER&objective=VIDEO_VIEWS_PREROLL&categories=IAB5, IAB15

{  
  "data_type":"line_item",
  "data":{  
    "bid_type":"MAX",
    "name":"Ad Group 1",
    "placements":[  
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro":5500000,
    "automatically_select_bid":false,
    "advertiser_domain":null,
    "primary_web_event_tag":null,
    "charge_by":"VIEW",
    "product_type":"MEDIA",
    "bid_unit":"VIEW",
    "total_budget_amount_local_micro":null,
    "objective":"VIDEO_VIEWS_PREROLL",
    "id":"4bii5",
    "paused":false,
    "account_id":"abc123",
    "optimization":"DEFAULT",
    "categories":[  
        "IAB5"
        "IAB15"
    ],
    "currency":"USD",
    "created_at":"2016-02-11T22:23:23Z",
    "tracking_tags":[  

    ],
    "updated_at":"2016-02-11T22:23:23Z",
    "include_sentiment":"POSITIVE_ONLY",
    "campaign_id":"47axj",
    "creative_source":"MANUAL",
    "deleted":false
  },
  "request":{  
    "params":{  
      "name":"Ad Group 1",
      "placements":[  
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro":5500000,
      "product_type":"MEDIA",
      "objective":"VIDEO_VIEWS_PREROLL",
      "account_id":"abc123",
      "categories":[  
        "IAB5"
        "IAB15"
      ],
      "campaign_id":"47axj"
    }
  }
}

Associate the account media (video) with the line item

Use the POST accounts/:account_id/media_creatives endpoint to associate the video with an ad group.

POST https://ads-api.twitter.com/3/accounts/abc123/media_creatives
line_item_id=4bii5&account_media_id=knb

{  
  "data_type":"media_creative",
  "data":{  
    "account_media_id":"74g",
    "approval_status":"ACCEPTED",
    "created_at":"2016-02-11T22:23:23Z",
    "deleted":false,
    "id":"qeq",
    "landing_url":null,
    "line_item_id":"4bii5",
    "serving_status":"ACTIVE",
    "updated_at":"2016-02-11T22:23:23Z"
  },
  "request":{  
    "params":{  
      "line_item_id":"4bii5",
      "account_media_id":"knb"
    }
  }
}

Set the CTA and destination URL

It is important to note that unlike most other campaigns on Twitter, the VIDEO_VIEWS_PREROLL objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a preroll_call_to_action entity. The POST accounts/:account_id/preroll_call_to_action endpoint allows you to control the button CTA and the destination URL.

POST https://ads-api.twitter.com/3/accounts/abc123/preroll_call_to_action
line_item_id=4bii5&call_to_action=VISIT_SITE&call_to_action_url=https%3A%2F%2Ftwitter.com%2FAdsAPI

{  
  "data_type":preroll_call_to_action,
  "data":{  
    "id":"aaa111",
    "line_item_id":"4bii5",
    "call_to_action":"WATCH_NOW",
    "call_to_action_url":"https://twitter.com/AdsAPI",
    "created_at":"2016-02-11T22:23:23Z",
    "updated_at":"2016-02-11T22:23:23Z",
    "deleted":false
  },
  "request":{  
    "params":{  
      "line_item_id":"4bii5",
      "call_to_action":"VISIT_SITE",
      "call_to_action_url":"https://twitter.com/AdsAPI"
    }
  }
}

Set targeting criteria

The targetting criterion utilized for pre-roll video ads is only avaialble using our batch targeting criteria endpoint - POST batch/accounts/:account_id/targeting_criteria.

Use CONTENT_PUBLISHER_USER as negated targeting to exclude the ad from being paired with a set of users. Provide the Twitter user_id for the handles to exclude.

Use IAB_CATEGORY as negated targeting to exclude any categories from being paired with your ad.

POST https://ads-api.twitter.com/3/batch/accounts/abc123/targeting_criteria

[  
  {  
    "operation_type":"Create",
    "params":{  
      "line_item_id":"4bii5",
      "targeting_type":"CONTENT_PUBLISHER_USER",
      "targeting_value":"312226591",
      "negated":true
    }
  },
  {  
    "operation_type":"Create",
    "params":{  
      "line_item_id":"4bii5",
      "targeting_type":"IAB_CATEGORY",
      "targeting_value":"IAB2",
      "negated":true
    }
  }
]

{  
  "data_type":"targeting_criterion",
  "data":[  
    {  
      "line_item_id":"4bii5",
      "name":"baristabar",
      "id":"6zujml",
      "operator_type":"EQ",
      "created_at":"2016-02-11T22:51:32Z",
      "targeting_value":312226591,
      "updated_at":"2016-02-11T22:51:32Z",
      "deleted":false,
      "targeting_type":"CONTENT_PUBLISHER_USER"
    },
    {  
      "line_item_id":"4bii5",
      "name":"Automotive",
      "id":"6zujmk",
      "operator_type":"EQ",
      "created_at":"2016-02-11T22:51:32Z",
      "targeting_value":"IAB2",
      "updated_at":"2016-02-11T22:51:32Z",
      "deleted":false,
      "targeting_type":"IAB_CATEGORY"
    }
  ],
  "request":[  
    {  
      "params":{  
        "line_item_id":"4bii5",
        "targeting_type":"CONTENT_PUBLISHER_USER",
        "targeting_value":312226591,
        "account_id":"18ce53uo8cb"
      },
      "operation_type":"Create"
    },
    {  
      "params":{  
        "line_item_id":"4bii5",
        "targeting_type":"IAB_CATEGORY",
        "targeting_value":"IAB2",
        "account_id":"abc123"
      },
      "operation_type":"Create"
    }
  ]
}

Launch campaign

When you’re ready to launch your campaign, simply un-pause using PUT accounts/:account_id/campaigns/:id.

PUT https://ads-api.twitter.com/3/accounts/abc123/campaigns/47axj
paused=false

{  
  "data_type":"campaign",
  "data":{  
    "name":"Preroll Sample",
    "start_time":"2016-03-01T00:00:00Z",
    "reasons_not_servable":[  

    ],
    "servable":true,
    "daily_budget_amount_local_micro":550000000,
    "end_time":null,
    "funding_instrument_id":"i7o2d",
    "duration_in_days":null,
    "standard_delivery":true,
    "total_budget_amount_local_micro":null,
    "id":"47axj",
    "paused":false,
    "account_id":"abc123",
    "frequency_cap":null,
    "currency":"USD",
    "created_at":"2016-02-11T04:59:59Z",
    "updated_at":"2016-02-11T05:02:22Z",
    "deleted":false
  },
  "request":{  
    "params":{  
      "campaign_id":"47axj",
      "paused":false,
      "account_id":"abc123"
    }
  }
}

Analytics

Analytics for VIDEO_VIEWS_PREROLL campaigns are available using our stats endpoints.