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 audience about things they might be interested in, without having to send custom events to Airship or assign AttributesMetadata that you can use to group and target your audience. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. .

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 each member of 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 use 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.

Using the API, you set the msg_purpose value in the #feed block for each channel’s message. Using the dashboard, you set a value in the Delivery step, and that value applies to all channels selected for that message. 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) to be 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 dashboard 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 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 Failure 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 » External data feeds.

  2. Click Add data feed.

  3. Enter feed information.

    • Friendly Name: Helps you find the feed in the Airship dashboard.
    • Feed ID: How you will reference the feed. The ID must be unique, without spaces or special characters. Use a feed ID that makes sense to you. You cannot change the feed ID later.
    • Description: The data returned by the feed.
    • Request URL: The URL to retrieve data from. Use double square brackets for variables you want to set at the message (campaign) level. Use 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. Example: https://api.example.com/[[msg_var]]?user={{attribute_var}}.
      • Default value for [var]: Enter a default value for each message-level variable used in your request URL. These fields appear automatically based on the request URL.
    • Confirm the request URL domain: The base domain, e.g., api.example.com. You do not need to copy the protocol or variables.
  4. (Optional) 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.

  5. (Optional) Click Add header to add request headers, e.g., Authorization. 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.

  6. Click Next.

  7. Confirm that you have rights to make requests from the Request URL, then click Next.

  8. (Optional) Click Add object location to map objects in the feed’s response to a different key that is easier to remember or type. Enter a name and object location. For example, if you have a user object, you might want to access the first name of your user. Enter firstName as the Name for the data and user.firstName as the Object location. See Object and Array Notation for more detail.

  9. Click Save.

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 (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.

External Data Feed Reporting and Errors

When you use an external feed in a message, its message report shows the feed that you used. It appears in the Content table in the Message Detail section of the report.