Personalizing Templates with Data Feeds

To retrieve data from external web services and use it to personalize your project's templates at send time, use data feeds.

As Iterable sends campaigns, data feeds can make per-recipient requests to external web services. Parameters in these requests make it possible for the web services to return data that's directly relevant to specific users.

This document describes how to set up data feeds and use them in Iterable campaigns.

# Table of contents

To use data feeds to personalize your Iterable templates, follow these steps:

# 1. Set up a web service

Data feeds make HTTP GET requests to JSON, XML, RSS and Atom web services, and templates use the data returned by these web services to customize their content. Before you set up a data feed in Iterable, work with your engineering team to set up a web service for it to query.

For example, a JSON web service might return the following product recommendations based on a user's purchase history:

{
  "pastPurchase": "Hot Dog Halloween Outfit for Cats",
  "suggestedProduct": [
    {
      "name": "Deluxe Cat Tree",
      "description": "A jungle for your favorite feline buddy",
      "price": 160,
      "imageUrl": "http://img-cache.cdn.gaiaonline.com/0b4be3af7262e023cce39cffa697d4cd/http://i324.photobucket.com/albums/k331/michellepaints/CC_Cat_Tree.jpg
    },
    {
      "name": "Catnip Mouse Toy",
      "description": "Cats go absolutely crazy for this realistic mouse toy!",
      "price": 4,
      "imageUrl": "https://www.crystalclearpet.com/shop/treats/images/catnip-large-mouse-11077a.jpg"
    },
    {
      "name": "Set of 3 Furry Sticks",
      "description": "Dangle this enticing toy in front of your kitty!",
      "price": 5,
      "imageUrl": "http://i01.i.aliimg.com/wsphoto/v1/1944996867/Freeshipping-font-b-Rabbit-b-font-font-b-Fur-b-font-Strip-Funny-Cat-Stick-Cat.jpg"
    }
  ]
}

Click https://static.iterable.com/sample-data-feeds/sample_data_feed.json to see this response, as generated by a sample JSON web service.

# HTTP response codes

When a data feed queries the URL for its associated web service, Iterable handles HTTP response codes as follows:

Wikipedia provides more details about HTTP status codes.

# Response times

Iterable expects a data feed's web service to return a complete response within 10 seconds. If this does not happen, Iterable re-queries the same web service 3 minutes later. After 5 unsuccessful attempts, Iterable skips sending the message to the current contact.

# Personalized responses

When data feeds query web services for data, they can provide query string parameters to request information relevant to particular users. For example, a data feed might query the following web service URL:

https://www.example.com/sample_data_feed.json?email={{#urlEncode}}{{email}}{{/urlEncode}}

This URL includes an email parameter that's set to the value of the email field on the contact's Iterable profile (URL-encoded as necessary by the #urlEncode block helper). Iterable replaces URL merge parameters with profile values or values from a campaign's triggering event.

Web services called by data feeds should respond with data relevant to given parameters.

# Other data feed formats

Iterable data feeds can also query XML, RSS and Atom web services. Websites typically use these data formats to publish frequently updated information (such as blog entries or news headlines) for consumption by other software applications. These formats are based on XML and may look similar to the following:

<rss xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
  <channel>
    <generator>NFE/5.0</generator>
    <title>""cold brew"" - Google News</title>
    <link>
      https://news.google.com/search?hl=en-US&gl=US&ceid=US:en&q=%22cold+brew%22
    </link>
    <language>en-US</language>
    <webMaster>news-webmaster@google.com</webMaster>
    <copyright>2020 Google Inc.</copyright>
    <lastBuildDate>Sun, 03 May 2020 22:35:17 GMT</lastBuildDate>
    <description>Google News</description>
    <item>
      <title>
        This Might Be the Easiest Way to Make Cold Brew Coffee at Home - Food & Wine
      </title>
      <link>
        https://www.foodandwine.com/lifestyle/kitchen/french-press-cold-brew-coffee
      </link>
      <guid isPermaLink="false">52780760175588</guid>
      <pubDate>Fri, 01 May 2020 21:58:50 GMT</pubDate>
      <description>
        <ol><li><a href="https://www.foodandwine.com/lifestyle/kitchen/french-press-cold-brew-coffee" target="_blank">This Might Be the Easiest Way to Make Cold Brew Coffee at Home</a>&nbsp;&nbsp;<font color="#6f6f6f">Food & Wine</font></li><li><a href="https://thegadgetflow.com/blog/best-coffee-accessories/" target="_blank">Cold brew or Cappuccino? Make any coffee you want with these coffee accessories</a>&nbsp;&nbsp;<font color="#6f6f6f">Gadget Flow</font></li></ol>
      </description>
      <source url="https://www.foodandwine.com">Food & Wine</source>
    </item>
  </channel>
</rss>

To reference data in an XML, RSS or Atom-based data feed, use the same syntax described below for JSON-based data feeds.

# 2. Create a data feed to call the web service

To create an Iterable data feed, navigate to Content > Data Feeds and click Create New Feed. Provide the requested information:

• Name - The name of the data feed. Used to select it in a campaign.

• Template Handlebars Alias - (Optional) An alias templates can use to reference data from this data feed. Data feed aliases clarify which data feed a merge parameter references—especially in situations where a single template uses multiple data feeds. Learn more about referencing data feeds by alias.

• URL - The URL to a web service that returns a valid data feed

• Format - The type of data the data feed will query from a web service.

• Authorization Token - (Optional) A token Iterable adds as an authorization header in the HTTP request to the data feed. Used to authenticate the request.

  NOTE

  It's possible to use an OAuth bearer token as an authorization header, as described in this document. When this token expires, you'll need to manually update the data feed.

• HTTP Headers - (Optional) Custom HTTP headers to include in the data feed's web service request. Click Add New Custom HTTP Header to add as many headers as necessary.

# Editing existing data feeds

To edit an existing data feed, navigate to Content > Data Feeds, find the relevant data feed, and click Edit Feed:

# Editing data feed aliases

Aliases improve template readability, making it possible to reference data feeds by name.

To edit a data feed's alias, navigate to Content > Data Feeds and click Edit Alias (in the drop-down menu) for the relevant data feed. This brings up the Edit Data Feed Alias window:

# Deleting data feeds

To delete a data feed, navigate to Content > Data Feeds and click Delete Feed (in the drop-down menu). This brings up a confirmation window:

# 3. Configure a template to use the data feed

To allow a template to reference data feeds, edit the template and configure the following items on the Advanced Options tab:

• Enable Template Generation Using Data Feeds
• Cache Data Feed Response...
• Merge the Data Feed and User Contexts
• Use Data Feed Alias

For more information about these options, read:

• Template Options for Email
• Template Options for In-App Messages
• Template Options for Push Notifications
• Template Options for SMS
• Template Options for Web Push Notifications

# 4. Reference the data feed in the template's content

To reference a data feed in a template's content, use double square brackets or double curly braces (depending on the template's configuration):

• Double square brackets

  Double square brackets are the default way to access data feed data. For example, the following expression references the price of the first item in the suggestedProduct array of the data feed defined above: [[suggestedProduct.[0].price]].

• Double curly braces

  Double curly braces normally reference user profile data. However, when you enable a template's Merge the Data Feed and User Contexts option (in the Advanced Options tab of the template editor), double curly braces can also reference data feed data. For example, for the data feed defined above, this merge parameter references the price of the first item in the suggestedProduct array: {{suggestedProduct.[0].price}}.

# Referencing data feeds by alias

For this to work, you must:

• Assign an alias to the data feed in question (on the Content > Data Feeds screen).
• Enable Use Data Feed Alias on the template's Advanced Options tab.

# Example template using data feeds

This example shows a template that uses data feed and user profile data:

# 5. Integrate the template into a campaign

Iterable campaigns can query data feeds in two ways:

• Once per recipient, at campaign send time (to maximize personalization)
• Once during campaign setup (minimizing the load on the sever that hosts the web service)

# Querying data feeds at campaign send time (once per recipient)

The most common way to fetch a data feed is at campaign send time, once per recipient. With this approach, data from the feed is both up-to-date and customized for the recipient (assuming user-specific merge parameters are included in the data feed's URL). To query data feeds in this way:

1. When creating a campaign, continue to step #2 (Template).

2. Select a base template or start from scratch:

   • To derive the campaign template from an existing base template, select the base template and click Continue to Design.

   • To create a new campaign template from scratch, click Create a New Template.

3. On step #3 (Design), go to the Advanced Options tab and configure the campaign template's various data feed options, as described above (if they're not already configured correctly).

4. Edit the campaign template as necessary. To save it, scroll to the bottom of the screen and click Save Template.

5. To verify that everything looks right, preview the template with data.

   NOTE

   If the data feed changes before you send the campaign, the campaign's content will differ from the preview.

6. When you're ready, send the campaign. Iterable queries the data feed for each recipient, taking your data feed caching preferences in to account.

# Querying a data feed once during campaign setup

Alternatively, Iterable can query a data feed one time during campaign setup, integrating that data directly into the campaign's content. This minimizes load on the data feed's web service.

To query a data feed once during campaign setup:

1. When creating a campaign, continue to step #2 (Template).

2. Select a base template contains data feed references. Click Use Template With Data Feed.

3. A Select Data Feed to Merge Into Template window appears. Select the right data feed and click Use This Data Feed.

4. The template editor appears. Note that Iterable has already queried the data feed's web service and merged relevant values into the campaign template.

5. Edit the campaign template as necessary. To save it, scroll to the bottom of the screen and click Save Template.

6. To verify that everything looks right, preview the template with data.

7. When you're ready, send the campaign. Iterable does not query the data feed again.

# Further reading

• Template Options for Email
• Template Options for In-App Messages
• Template Options for Push Notifications
• Template Options for SMS
• Template Options for Web Push Notifications