Video Views Pre-roll Objective

The implementation of a Video View Pre-roll campaign, also referred to as Open Amplify, 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.

NOTE: The VIDEO_VIEWS_PREROLL objective is in a closed alpha in the API and is only available to whitelisted alpha developers. In addition, only whitelisted advertisers are eligible to run these campaigns.

Table of Contents

Endpoints Required

Steps

Confirm the ads account has the account feature

First, you’ll want to confirm that the ads account has been whitelisted for the VIDEO_VIEWS_PREROLL_OBJECTIVE feature. You can check this using the GET accounts/:account_id/features endpoint.

GET https://ads-api.twitter.com/2/accounts/abc123/features
{  
  "data":[  
    "CPI_CHARGING",
    "AGE_TARGETING",
    "OPTIMIZED_ACTION_BIDDING",
    "MOBILE_CONVERSION_TRANSACTION_VALUE",
    "INSTALLED_APP_CATEGORY_TARGETING",
    "VIDEO_VIEWS_PREROLL_OBJECTIVE"
  ],
  "data_type":"features",
  "request":{  
    "params":{  
      "account_id":"abc123"
    }
  }
}

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/2/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/2/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"
    }
  }
}

Create the campaign

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 IAB categories.

POST https://ads-api.twitter.com/2/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"
    }
  }
}
POST https://ads-api.twitter.com/2/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=IAB1
{  
  "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":[  
      "IAB1"
    ],
    "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":[  
        "IAB1"
      ],
      "campaign_id":"47axj"
    }
  }
}

Associate the account media (video) with the line item

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

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