Set up and use External Data Feeds

Add external data feeds to your project to fetch personalization data at send time, so you can personalize messages at will.

External data feeds let Airship fetch personalization data from an external API when you send a message. Using feeds can help you tell your users about the weather or products they might be interested in, without having to send custom events to Airship or assign attributes to your audience.

For example, if your audience requests weather updates, you can set up an external data feed to fetch weather data when you send your message, and personalize messages with relevant weather updates for your audience.

Variables in the Feed URL

You can set both send-time variables and standard personalization variables. Use square brackets ([[var]]) for values that you want to set at the message or campaign level, and standard HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. ({{var}}) for audience variables — attributes, custom event properties, etc.

For example, the feed URL below has variables for msg_purpose, first_name, and last_name.

Example personalized feed
https://api.myfeed.com/[[msg_purpose]]?user={{first_name}}%20{{last_name}}

The first_name and last_name are populated from audience variables — attributes or custom event properties.

You set the msg_purpose value either in the #feed block in your message or in the Delivery step for your messaging campaign. So, if your messaging campaign includes App, Web, and SMS channels, you can set msg_purpose in the #feed block with different values for App, Web, and SMS channels or you can set a value in the Delivery step that applies to all of the channels in the campaign.

Set a variable at the message level
{{#feed "myfeed" msg_purpose="weather" as |weather|}}
    Hi, {{first_name}},
    It's going to be {{weather.temp}} in {{weather.city}} today!
{{/feed}}

Set a variable at the campaign level (in the Delivery step)

Feed Object Locations

You access properties from your feed using JSON dot notation in the #feed block. When you set up your feed, you can define objects in your feed’s response so that you don’t have to remember the exact name and location of every property in the feed.

Airship lists the object locations you define along with your feed, making it easy to reuse properties from your feed in messages and templates.

To add an object location, provide the path to the variable you want to reference in JSON dot notation, and a friendly name for the property.

Enumerate object locations when configuring a feedUse known object locations in the feed

Personalizing Messages with Feeds and Other Sources

You can reference variables (or merge fieldsA variable in your message or template that you want to populate with a personalized value for each member of the audience. Merge fields use handlebar syntax — {{merge_field}}. ) that aren’t a part of the feed — attributes, custom event properties, etc. If this is something you may do, set the feed namespace using as |alias| to differentiate between properties from the feed and other personalization variables. This ensures that Airship uses the proper variables in your messages.

In the example below, we can differentiate between attributes (first_name and user_id) and feed properties based on the parent namespace set within the feed and each blocks.

{{#feed "featured_products" region="us" as |result|}}
Hi {{first_name}}, take a look at
  {{#each (limit result.products 2) as |product|}}
    {{product.name}}: {{product.price}}
    https://example.com/us/{{user_id}}/featured/{{urlEncode product.slug}}/
  {{else}}
    Products that might interest you at https://example.com/us/products/featured
  {{/each}}
{{else}}
Couldn't fetch featured products!
{{/feed}}

Feed Success, Retry, and Error Conditions

Airship considers any 2xx response from your feed to be a success, and will continue a message using your feed response.

Airship considers any 3xx, 4xx, and 5xx codes (except 502/503) error conditions. You set the error behavior for your feed when you set up your message, determining whether to send a message without your feed or to abort the message — either in the Delivery step in the composer or with the on_error object in the API

HTTP StatusResultBehavior
2xxSuccessAirship uses the feed response, even if empty
3xxErrorerror behavior determined by user
4xxErrorerror behavior determined by user
5xxErrorerror behavior determined by user
timeout (30s)RetryUp to 4 retries, 60s between attempts
502/503RetryUp to 4 retries, 60s between attempts

Set Feed Error Behavior

When using an external data feed in a message, you determine what happens if the feed fails — whether to abort the message or send it despite the error. If your message still makes sense without a feed, you may want to send the message even if a your data feed fails.

When you set up a message that uses a feed (or use a template that includes a feed) in the Airship dashboard, you set error behavior in the Delivery step.

When using the API, you can set the on_error behavior to continue to send messages despite an error. Otherwise, a feed failure will prevent Airship from sending your message.

{
    "feed_references": {
        "feeds": [
            {
                "name": "featured_products",
                "params": {
                    "region": "us"
                },
                "on_error": "continue"
            }
        ]
    }
}

Feed Retry Conditions

Airship will make up to five attempts to get a response from your feed, retrying after 60 seconds if we receive 502/503 responses, or if the feed does not respond after 30 seconds.

If, after five attempts, Airship does not receive a 2xx response, we’ll consider the feed failed and use the error behavior that you set for your message.

Set Up a New Feed

When you set up a feed, you provide Airship with the endpoint and any HTTP request headers required to successfully communicate with the external feed (e.g., authorization headers). You can even use variables in the feed URL, so that you can provide variables at send time and ensure that your data feed uses data relevant to your audience.

You will identify and use your feed in handlebars by the Feed ID. Feed IDs are unique and cannot be changed. When you create a feed, make sure you set a Feed ID that is meaningful to use and relatively easy to type.

  1. Go to Settings » APIs & Integrations and click External data feeds.

  2. Go to New Feed and click Add  . Use a Feed ID that makes sense to you; you cannot change the feed ID later.

  3. Enter a Friendly Name for the feed. This helps you find the feed in the Airship Dashboard.

  4. Enter a Feed ID. This is how you’ll reference the feed.

  5. Enter a Description to describe the feed.

  6. Enter the Request URL. Use double square brackets for variables you want to set at the message or campaign level and curly brackets (standard HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. ) for variables that you want to come from your audience, e.g., https://api.example.com/[[msg_var]]?user={{attribute_var}}.

  7. Enable Cache Response if you want Airship to cache the response from your feed and use it for multiple recipients. You may want to cache the response if you don’t expect your feed to return a different response when using the same feed URL and parameters.

  1. Confirm the request URL domain. You do not need to copy the protocol or variables, just the base domain — e.g., api.example.com.

  2. Click Add Header to add request headers, like Authorization, etc. For each header, enter a Key and Value. Header values support handlebars as well, so you can populate header values from attributes and other personalization sources.

  3. Click Next.

  4. Confirm that you have rights to make requests from the Request URL.

  5. (Optional) Click Add Response Path to map objects in the in the feed’s response to a different key that’s easier to remember or type.

  6. Click Save to save your feed.

Using a Data Feed in a Template or Message

In templates, email, and Message Center messages you can copy HandlebarsAirship’s message personalization syntax using double curly braces, more commonly known as {{handlebars}}. Use handlebars to insert variables and conditional logic in messages and templates. for your feed into your message from the Data Feed sidebar.

For each feed in the sidebar, the first (or top) entry is the feed itself. Subsequent entries are object locations that you added when setting up your feed, making it easy to reuse properties in your feed.

In all other messages you can reference a feed by adding a block in the format {{#feed "feed_id"}}Content referencing the feed{{/feed}}.

In both cases, if your feed URL has variables in the format [[var]], you can set those variables in individual feed reference as {{#feed "feed_id" msg_var="value"}} or in the Delivery step in the dashboard. If you do not set a variable, Airship uses the default value that you assigned when setting up your feed.

Whenever you use a feed in a message, you must set the error behavior for the feed in the Delivery step.