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:

To properly serve Dynamic Creative, there are two parts:

Register product feeds
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 -H 'Authorization: Token YOUR_TOKEN' \
    -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 -H 'Authorization: Token YOUR_TOKEN' \
    -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 -H 'Authorization: Token YOUR_TOKEN' \
    -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