Setup Product Feeds for Dynamic Creative

Note

This document is intended for setting up multiple feeds via API. If you’re intending to implement a single feed, please contact your account manager for assistance.

Dynamic Creative enables personalized ads across devices on the Web and Facebook. Dynamic ads can feature previously-viewed, recommended, and top products. Product details are populated via product feeds you host on your server. This guide shows you how to set up and configure a product feed using the NextRoll API.

To better familiarize yourself with Dynamic Creative, you should also read the getting started guide on the Help Center.

The API uses the following data model:

  • Each Advertisable has one Dynamic Configuration
  • Each Dynamic Configuration has one or more Feed Configurations
  • Each Feed Configuration has four or more Parser Configurations (i.e. one per field in the feed)

Visually this looks like:

Diagram of AdRoll product feed model

To properly serve Dynamic Creative, there are two parts:

  1. Register product feeds
  2. Capture product views and actions

Additionally, we provide methods to verify your product feeds.

Register product feeds

First, you must register one or more product feeds. Product feeds must be a public URL that we can periodically crawl. The feed can be in any of the following formats: CSV, JSON, or XML. At a minimum the feed must contain the following details for each product:

  • Product ID
  • Product title
  • Destination URL
  • Image URL

If you already have a feed of your products, you shouldn’t need to create a feed just for us. If your feed is in a standard format you can use the automatic setup. If your feed is a custom format, you should follow the manual setup instructions.

Note

If you have multiple product feeds, repeat the setup process for each feed. The products in the feed will be combined into one catalog. If you have multiple feeds with different purposes (i.e. product groups, language specific, region specific), send us a message and we should be able to accommodate you.

Automatic Setup

If your product feed uses the Google Products Feed (aka Google Base) format, you can use the POST /api/v1/product_feeds/autoconfigure method to automatically set up and configure your feed.

Manual Setup

If you can’t use the automatic setup for your feed, then you’ll need to manually configure a feed.

Add your first feed configuration

To enable your Advertisable’s dynamic configuration and add your first product feed, make a call to POST /api/v1/dynamic_configuration/enable.

Request:

curl --user apihelp@adroll.com:password \
    -d advertisable=8597013E81481B0FE28772 \
    -d "url=https://example.com/feed.json" \
    https://services.adroll.com/api/v1/dynamic_configuration/enable?apikey=MYAPIKEY

Response:

{
  "results": {
    "feedconfig_eid": "AD45655AFE435A6C46F696"
  }
}

Edit your feed configuration

Once you’ve added your first feed configuration you can configure its values using PUT /api/v1/product_feeds/edit_feed_config. See PUT /api/v1/product_feeds/add_feed_config for the list of fields you can edit.

For example, if your CSV file uses a special delimiter or escape character, you can update the setting:

Request:

curl --user apihelp@adroll.com:password \
    -d feed_config=AD45655AFE435A6C46F696 \
    -d "delimiter=," \
    https://services.adroll.com/api/v1/product_feeds/edit_feed_config?apikey=MYAPIKEY

Response:

{
  "results": {
    "escapechar": null,
    "encoding": null,
    "locale": "en_US",
    "parser_configs": [],
    "id": "AD45655AFE435A6C46F696",
    "skipfirstrow": null,
    "feedtype": null,
    "feed_url": "https://example.com/feed.json",
    "tag_name": "product",
    "quotechar": null,
    "product_group": null,
    "schedule": null,
    "follow_next_links": false,
    "feed_url_request_params": null,
    "feed_url_request_type": null,
    "skipinitialspace": null,
    "prices_in_locale_format": false,
    "feed_last_uploaded": null,
    "delimiter": ",",
    "last_feed_parse_eid": "",
    "parent_feed_id": null,
    "max_requests_per_second": null
  }
}

Add Parser Configurations

Once you’ve registered a product feed, you need to tell us which fields to parse. This is done with the POST /api/v1/product_feeds/set_parser_configs method. You’ll need to specify a parser configuration for each field. Since we require a minimum number of fields, you’ll have to configure at least four parser configurations. Depending on the Dynamic Creative template you’re using, you may need to configure additional fields. The required fields are: id, title, image, url, and price.

  • feed_config (string) - EID of the Feed Configuration object
  • parser_configs (string) - Stringified JSON object defining configuration for each field

The parser_configs parameter consists of an object of fields names as keys and field specification objects consisting of the following attributes:

  • is_required (boolean) - True if this field is required for the parsed product to be valid
  • path (string) - Column number (CSV), field name (JSON), or tag name (XML) for the field
  • attribute (string) - Attribute on the tag to use (i.e. text)
  • regular_expression (string) - Regular expression to search the field
  • regular_expression_replace (string) - Replacement string to apply to the field
  • type (string) - How to parse the field. Either: text, image, price

Example parser_configs object:

{
  "id": {
    "path": "id",
    "type": "text",
    "attribute": "text",
    "is_required": "true"
  },
  "title": {
    "path": "title",
    "type": "text",
    "attribute": "text",
    "is_required": "true"
  },
  "image": {
    "path": "image",
    "type": "image",
    "attribute": "text",
    "is_required": "true"
  },
  "url": {
    "path": "url",
    "type": "text",
    "attribute": "text",
    "is_required": "true"
  },
  "price": {
    "path": "price",
    "type": "price",
    "attribute": "text",
    "is_required": "true"
  }
}

Request:

curl --user apihelp@adroll.com:password \
    -d feed_config=AD45655AFE435A6C46F696 \
    -d "parser_configs={}" \
    https://services.adroll.com/api/v1/product_feeds/set_parser_configs?apikey=MYAPIKEY

Response:

{
  "results": true
}

Capture product views and actions

When users browse your site, you must tell us which products they are viewing and what actions they perform. This is done by passing product IDs and actions to the pixel.

For example, to specify that a product was viewed set the product_id property in the adroll_custom_data global variable:

adroll_custom_data = {
  "product_id":"YOUR_PRODUCT_ID"
};

You can specify product actions by setting the product_action property in adroll_custom_data to either AddToCart or Purchased.

For example, to specify that a product was added to a cart:

adroll_custom_data = {
  "product_id":"YOUR_PRODUCT_ID",
  "product_action": "AddToCart"
};

Verify product feed set up

There are several API methods you can use to validate your configuration:

GET /api/v1/product_feeds/feed_status
Check the current parse status of your feeds
GET /api/v1/product_feeds/match_rate
Check the match rate of your product page views to products in your feed
GET /api/v1/product_feeds/feed_downloadable
Check if we are able to fetch and download a product feed URL
GET /api/v1/product_feeds/parse_preview
Preview the results of a given parser configuration to the content of a feed