Dynamic Product Ads

Dynamic Product Ads allow advertisers to serve Promoted Tweets based on products users have recently viewed on the advertisers website. Product feeds will be ingested by Twitter, and Promoted Tweets will be dynamically created.

Getting Started

Requirements

Ads API production access
Dynamic Product Ads permissions
Tailored Audience Web permissions
Advertiser accounts enabled for ads on Twitter Audience Platform

Steps for setting up Dynamic Product Ads

Related Endpoints

Frequently Asked Questions

Creating Product Feeds

Product feeds should conform to the Google Feed format.

Product Photos For each product in the product feed, we expect one main image, and optional alternative images. The maximum file size for product photos is 5MB.

Ensure the main product photos have aspect ratios of 1.91:1 or 1:1, as these are the two primary aspect ratios which are used in Dynamic Product Ads both on Twitter and the Twitter Audience Platform. If provided photos do not conform to these ratios, the photos will be resized or cropped to the nearest ratio.

Product Feed Ingestion

Once created and uploaded to your servers, use the POST /0/accounts/:account_id/product_feeds endpoint to create a product feed object associated with the advertiser’s Twitter Ads account.

Let’s create a simple product feed now, and set the feed’s country to Japan. Note that the products in this feed will only be targeted at users in the specified country.

Request:

POST https://ads-api.twitter.com/0/accounts/abcd/product_feeds?name=samplefeed&country_code=JP&url=http%3A%2F%2Ffeeds.twitter.com%2Fsamplefeed.tsv”

Response:

{
  "request": {
    "params": {
      "name": "samplefeed",
      "url": "http://feeds.twitter.com/samplefeed.tsv",
      "country_code": "JP"
    }
  },
  "data_type": "product_feed",
  "data": {
    "name": "samplefeed",
    "url": "http://feeds.twitter.com/samplefeed.tsv",
    "country_code": "JP",
    "id": "597og5g43bb4",
    "account_id": "abcd",
    "created_at": "2016-01-27T23:54:02Z",
    "updated_at": "2016-01-27T23:54:02Z",
    "deleted": false
  }
}

After the product feed object is created, the POST /0/accounts/:account_id/product_feed_uploads endpoint can be used to initiate uploads/fetches of the product feed to update the creative copy and availability information for products in the feed. Note that product uploads are asynchronous, and the GET /0/accounts/:account_id/product_feed_uploads/:product_feed_upload_id endpoint should be used to check for the status of each product feed upload.

Let’s initiate a feed upload. To do so, we’ll need the ID of the product feed. Let’s use the feed id from the response in the previous step: 597og5g43bb4.

Request:

POST https://ads-api.twitter.com/0/accounts/abcd/product_feed_uploads?product_feed_id=597og5g43bb4”

Response:

{
  "request": {
    "params": {
      "product_feed_id": "597og5g43bb4"
    }
  },
  "data_type": "product_feed_upload",
  "data": {
    "id": "5g4gpfvd9p1c",
    "upload_details": {
      "code": "",
      "processed_item_count": 0,
      "feed_item_count": 0,
      "out_of_stock_item_count": null
    },
    "status": "QUEUED",
    "created_at": "2016-01-28T00:00:17Z",
    "product_feed_id": "597og5g43bb4",
    "updated_at": "2016-01-28T00:00:17Z",
    "deleted": false
  }
}

Note that this product feed is created, but in a queued state. We can query for the state of the feed upload, and check for completion or any potential errors.

Request:

POST https://ads-api.twitter.com/0/accounts/abcd/product_feed_uploads/5g4gpfvd9p1c?product_feed_id=597og5g43bb4”

Response:

{
  "request": {
    "params": {
      "product_feed_id": "597og5g43bb4",
      "product_feed_upload_id": "5g4gpfvd9p1c"
    }
  },
  "data_type": "product_feed_upload",
  "data": {
    "id": "5g4gpfvd9p1c",
    "upload_details": {
      "code": "SUCCESS",
      "processed_item_count": 5,
      "feed_item_count": 5,
      "out_of_stock_item_count": 0
    },
    "status": "FINISHED",
    "created_at": "2016-01-28T00:00:37Z",
    "product_feed_id": "597og5g43bb4",
    "updated_at": "2016-01-28T00:00:37Z",
    "deleted": false
  }
}

Note that the feed upload has completed successfully. This indicates that all products and associated metadata has updated.

Setting up ID Sync

In order to associate products with users for Dynamic Product Ads, Twitter needs to accurately identify users visting product pages. This can be done by constructing and placing Twitter’s ID Sync pixel on the advertiser’s site.

Base URL

https://analytics.twitter.com/i/adsct

Parameters

Parameter	Description
`p_id`	your Twitter-assigned partner id
`p_user_id`	(optional) the user’s id in the partner system

Using an example partner id of 111, the contructed pixel would be the following:

ID Sync Pixel:

<img  height="1" width="1" style="display:none;" src="https://analytics.twitter.com/i/adsct?p_id=111" />

Tracking product views with Web Event Tags

Web event tags will be used to capture user exposure to products. In addition, a product audience will be created for each Dynamic Product Ads web event tag. Each product audience contains mappings of products to users who have viewed them. One web event tag can be used for many different product pages. However if you wish to run separate campaigns for product categories, a separate web event tag/product audience should be created for each product category, to create separate targeting groups.

After creating a tag, a tracking pixel can be embedded on the product page to determine users who viewed the product, and add those users to the appropriate product audience.

Creating Web Event Tags

A web event tag is created via the POST /0/accounts/:account_id/web_event_tags endpoint. Each web event tag will create an associated product audience. The value passed to the name parameter should be unique and saved on your side, as this will be the identifier of the product audience needed for running a campaign.

Notes: During the initial beta phase, a fixed 14 day retention window will be used, and the values passed to click_window and view_through_window will not be taken into account.

As an example, let’s create a web event tag to be embedded on all product pages.

Request:

POST https://ads-api.twitter.com/0/accounts/abcd/web_event_tags?“name=All_Products&type=SITE_VISIT&retargeting_enabled=true&click_window=14&view_through_window=14”

Response:

{
    "data": {
        "click_window": 14,
        "deleted": false,
        "embed_code": "<script>...txn_id=abc123...</script>",
        "id": "xyz1",
        "name": "All_Products",
        "retargeting_enabled": true,
        "view_through_window": 14
    },
    "data_type": "web_event_tag",
    "request": {
        "params": {
            "account_id": "abcd",
            "click_window": 14,
            "name": "All_Products",
            "retargeting_enabled": true,
            "type": "SITE_VISIT",
            "view_through_window": 14
        }
    }
}

Embedding tags on product pages

Twitter is notified of user visits to product pages through embedded tracking tags. A dynamic product ad tracking tag requires different parameters than a standard web tracking tag, so the embed returned from the previous step will need to be modified to include the tw_product_id and tw_country_code parameters.

Base URL

https://analytics.twitter.com/i/adsct

Parameters

Parameter	Description
`txn_id`	the website tag identifier (`txn_id` value found in the `embed` returned in Web Event Tag creation
`tw_country_code`	ISO 3166-2 country
`tw_product_id`	a product id from an uploaded product feed

Let’s place a tracking tag on the product page for brown men’s loafers (product code: 11990231), using the web event tag we created above. The country will be set to United States. The txn_id to use is abc123.

The generated tracking code to embed on the product page would be the following:

Tracking tag:

<script src="//platform.twitter.com/oct.js" type="text/javascript"></script>
<script type="text/javascript">twttr.conversion.trackPid('abc123', { tw_product_id: 11990231, tw_country_code: 'US' });</script>
<noscript>
<img height="1" width="1" style="display:none;" alt="" src="https://analytics.twitter.com/i/adsct?txn_id=abc123&p_id=Twitter&tw_product_id=11990231&tw_country_code=US" />
<img height="1" width="1" style="display:none;" alt="" src="//t.co/i/adsct?txn_id=abc123&p_id=Twitter&tw_product_id=11990231&tw_country_code=US" />
</noscript>

Defining a creative template

The creative template allow advertisers to customize aspects of their creatives, such as URL parameters for each platform or advertiser logo. The creative template will apply to all Dynamic Product Ads associated with the advertiser account.

If no dynamic ads creative templates are associated with the account, one can be created via the POST accounts/:account_id/dynamic_ads_creative_templates endpoint. (A maximum of one template is allowed per advertiser account.)

Let’s set the url parameters on mobile devices to source=twitter, and adding the advertiser logo by passing the media_id obtained from the upload to the POST media/upload endpoint to the logo_media_id parameter. See the Guide to Uploading Media for detailed guidance on media uploads.

Request:

https://ads-api.twitter.com/0/accounts/hkk5/dynamic_ads_creative_templates?mobile_url_params=source%3Dtwitter&logo_media_id=71781808

Response:

{
  "request": {
    "params": {
      "logo_media_id": 71781808
      "mobile_url_params": "source=twitter"
    }
  },
  "data_type": "dynamic_ads_creative_template",
  "data": {
    "web_url_params": "",
    "logo_url": "https://pbs.twimg.com/media-preview/717067808/fAJfseypm.jpg",
    "id": "5drdx7785lhc",
    "account_id": "hkk5",
    "created_at": "2016-03-11T22:30:58Z",
    "title": "TITLE",
    "updated_at": "2016-03-11T22:30:58Z",
    "tablet_url_params": "",
    "mobile_url_params": "source=twitter",
    "deleted": false
  }
}

Running a Dynamic Product Ads campaign

Creating a Dynamic Product Ads campaign involves several steps. A campaign must be created, line item(s) must be added to the campaign, and each line item must be associated with a product audience. Promoted Tweets will be dynamically created and served to users, instead of manually associated with the line item.

To start serving Promoted Tweets, let’s create a Dynamic Product Ad campaign using the POST accounts/:account_id/campaigns endpoint.

Request:

POST https://ads-api.twitter.com/0/accounts/hkk5/campaigns?name=DPA Campaign&funding_instrument_id=j4a31&total_budget_amount_local_micro=5000000&daily_budget_amount_local_micro=500000&start_time=2015-10-01T07:00:00Z

Response:

{
  "data_type": "campaign",
  "data": {
    "name": "DPA Campaign",
    "start_time": "2015-10-01T07:00:00Z",
    "reasons_not_servable": [
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 500000,
    "end_time": null,
    "funding_instrument_id": "j4a31",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 5000000,
    "id": "38h1n",
    "paused": false,
    "account_id": "hkk5",
    "currency": "USD",
    "created_at": "2015-10-02T18:53:45Z",
    "updated_at": "2015-10-02T18:53:45Z",
    "deleted": false
  },
  "request": {
    "params": {
      "name": "DPA Campaign",
      "start_time": "2015-10-01T07:00:00Z",
      "daily_budget_amount_local_micro": 500000,
      "funding_instrument_id": "j4a31",
      "total_budget_amount_local_micro": 5000000,
      "account_id": "hkk5"
    }
  }
}

The campaign is created, but is not yet servable because we’ve yet to add line items to it.

Creating a Dynamic Product Ads line item

Dynamic Product Ads line items must have an objective of WEBSITE_CLICKS and must include the PUBLISHER_NETWORKplacement, as these campaigns serve across Twitter and the Twitter Audience Platform.

In addition, the categories and advertiser_domain parameters must be set.

Instead of manually adding creatives, we can dynamically generate the correct creative for the product by setting the creative_source to DYNAMIC_PRODUCT.

Request:

POST https://ads-api.twitter.com/0/accounts/hkk5/line_items?campaign_id=38h1n&name=DPA%20Line%20Item&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER,PUBLISHER_NETWORK&bid_amount_local_micro=100000&objective=WEBSITE_CLICKS&creative_source=DYNAMIC_PRODUCT&advertiser_domain=twitter.com&categories=IAB8

Response:

{
  "data_type": "line_item",
  "data": {
    "placement_type": "PROMOTED_TWEETS_FOR_TIMELINES",
    "bid_type": "MAX",
    "name": "DPA Line Item",
    "placements": [
      "ALL_ON_TWITTER,PUBLISHER_NETWORK"
    ],
    "bid_amount_local_micro": 100000,
    "automatically_select_bid": false,
    "advertiser_domain": "twitter.com",
    "primary_web_event_tag": null,
    "charge_by": "LINK_CLICK",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "LINK_CLICK",
    "total_budget_amount_local_micro": null,
    "objective": "WEBSITE_CLICKS",
    "id": "3auk1",
    "paused": false,
    "account_id": "hkk5",
    "optimization": "DEFAULT",
    "categories": [
      "IAB8"
    ],
    "currency": "USD",
    "created_at": "2015-10-02T19:11:06Z",
    "updated_at": "2015-10-02T19:11:06Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "38h1n",
    "creative_source": "DYNAMIC_PRODUCT",
    "deleted": false
  },
  "request": {
    "params": {
      "name": "DPA Line Item",
      "placements": [
        "TWITTER_TIMELINE"
      ],
      "bid_amount_local_micro": 100000,
      "product_type": "PROMOTED_TWEETS",
      "objective": "WEBSITE_CLICKS",
      "account_id": "hkk5",
      "campaign_id": "38h1n",
      "creative_source": "DYNAMIC_PRODUCT"
    }
  }
}

Targeting a Product Audience

Product audiences are specialized tailored web audience that contains mappings of users to products. These are created and populated through web event tags as described above, and can be identified using the name used when the corresponding web event tag was created and and a list_type of PRODUCT_ID. Note that list_type value will only return as PRODUCT_ID after successful events containing product ids have been received on the web event tag.

Let’s add the product audience to our newly created line item.

First, we must find the appropriate product audience by calling the GET accounts/:account_id/tailored_audiences endpoint. list_type of PRODUCT_ID, and name of “All_Products”.

Request:

GET https://ads-api.twitter.com/0/accounts/hkk5/tailored_audiences

Response:

{
  "request": {
    "params": {
      "account_id": "hkk5"
    }
  },
  "data": [
    ...
    {
      "targetable": true,
      "name": "All_Products",
      "targetable_types": [
        "WEB",
        "EXCLUDED_WEB"
      ],
      "audience_type": "WEB",
      "id": "w1dv",
      "reasons_not_targetable": [],
      "list_type": "PRODUCT_ID",
      "created_at": "2015-10-02T18:57:45Z",
      "updated_at": "2015-10-02T18:57:45Z",
      "partner_source": "OTHER",
      "deleted": false,
      "audience_size": "4580"
    },
    ...
  ],
  "data_type": "tailored_audiences",
  "total_count": 3423,
  "next_cursor": ejg93
}

Once the corresponding product audience id has been found, it can be added as the line item’s targeting criteria via the POST accounts/:account_id/targeting_criteria. Note that dynamic audience targeting cannot be combined with other targeting types, except for excluded audiences.

Request:

POST https://ads-api.twitter.com/0/accounts/hkk5/targeting_criteria?line_item_id=3auk1&targeting_type=TAILORED_AUDIENCE&tailored_audience_type=WEB&targeting_value=w1dv

Response:

{
  "data_type": "targeting_criterion",
  "data": {
    "line_item_id": "3auk1",
    "name": "Retargeting custom audience targeting",
    "id": "5bmpci",
    "account_id": "hkk5",
    "tailored_audience_expansion": false,
    "created_at": "2015-10-02T18:59:52Z",
    "targeting_value": "w1dv",
    "updated_at": "2015-10-02T18:59:52Z",
    "tailored_audience_type": "WEB",
    "deleted": false,
    "targeting_type": "TAILORED_AUDIENCE"
  },
  "request": {
    "params": {
      "line_item_id": "3auk1",
      "account_id": "hkk5",
      "targeting_value": "w1dv",
      "tailored_audience_type": "WEB",
      "targeting_type": "TAILORED_AUDIENCE"
    }
  }
}

Excluding users from targeting

In cases where users should be excluded from Dynamic Product Ads, those users can be added to a separate tailored audience which will be excluded from targeting.

The most dynamic approach is to use a separate Web Event Tag to create a web tailored audience. Use this tag on an appropriate page to capture users that should be excluded (for example, on an order confirmation page). Alternatively, these users can be added to a CRM tailored audience.

This audience can then be added as an additional tailored_audience_excluded targeting criteria, similar to the above step.

Assuming the tailored_audience_id of the excluded users is xrox:

Request:

POST https://ads-api.twitter.com/0/accounts/hkk5/targeting_criteria?line_item_id=3auk1&targeting_type=TAILORED_AUDIENCE&tailored_audience_type=EXCLUDED_WEB&targeting_value=xrox

Response:

{
  "data_type": "targeting_criterion",
  "data": {
    "line_item_id": "3auk1",
    "name": "Retargeting custom audience targeting",
    "id": "5bn2cg",
    "account_id": "hkk5",
    "tailored_audience_expansion": false,
    "created_at": "2015-10-04T03:22:44Z",
    "targeting_value": "xrox",
    "updated_at": "2015-10-04T03:22:44Z",
    "tailored_audience_type": "EXCLUDED_WEB",
    "deleted": false,
    "targeting_type": "TAILORED_AUDIENCE"
  },
  "request": {
    "params": {
      "line_item_id": "3auk1",
      "account_id": "hkk5",
      "targeting_value": "xrox",
      "tailored_audience_type": "EXCLUDED_WEB",
      "targeting_type": "TAILORED_AUDIENCE"
    }
  }
}

Frequently Asked Questions

What analytics for Dynamic Product Ads campaigns?

All standard metrics are available at the line item level for Dynamic Product Ads. Analytics specific to Product Ads are not currently available.

Which protocols are accepted for the feed URL?

Only HTTP and HTTPS are supported for feed URL fetching today.

Which product attributes should be provided in the product feed?

We recommend the passing the following attributes in your product feed:

Description	Feed attribute
Item id	`id`
Title	`title`
Brand (if available)	`brand`
Description	`description`
Price	`price`
Url	`link`
Availability	`availability`
Product Type	`product_type`
Image URL	`image_link`
Additional images (if available)	`additional_image_link`

Are there any requirements around product pages or links?

The URL (link) passed in the product feed must be a direct link to the product page. Any redirects will not be processed.

Additionally, Twitter’s crawler will respect robots.txt when scanning URLs. Twitter uses the User-Agent of Twitterbot (with version, such as Twitterbot/1.0), which can be used to create an exception in your robots.txt file.

Are there any requirements around the match rate between product tags and the items in feed?

There are no policies which require a certain match rate between the number of product tags on the site and the number of items in the feed. However, having a close match rate help to drive improved performance.

May	JUN	Apr
	17
2015	2016	2018