External data feeds

An external data feed is a connection to an external API. When you send a message, Airship uses a response from that API to personalize messages.

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 for audience segmentation. 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.

Feed settings

When you create a feed, you configure these required fields:

You can also configure additional options:

  • Request headers — HTTP request headers that may be required to successfully communicate with the external feed (e.g., authorization headers). Header values support handlebars as well, so you can populate header values from attributes and other personalization sources. Header information is not a part of the request URL.

  • Throttling and caching — Personalization using external data feeds can mean a lot of API calls in a short period of time. With throttling, you can configure a frequency rate for your requests. The minimum rate is 100 requests per second.

    You can also cache responses from your feeds and use them for multiple recipients. You may want to cache a response if you don’t expect your feed to return a different response when using the same feed URL and parameters.

    You can enable throttling or caching for a feed but not both.

  • Object locations — You can enter names and paths for objects in your feed so they are available for copying when creating a template, email, or Message Center message. Use JSON dot notation to enter the paths to the variables you want to reference.

    For example, if you have a user object, you might want to access the first name of your user. You would enter firstName as the Name for the data and user.firstName as the Object location.

    See also: Object and Array Notation.

Creating an external data feed

Refer to Feed settings for details.

  1. Go to Settings » Project Configuration and click Manage for External Data Feeds.

  2. Click Add data feed.

  3. Configure the feed information on each page, then click Done.

    • Friendly Name
    • Feed ID
    • Description
    • Request URL
    • Default values — These fields appear automatically based on the request URL. Enter a default value for each send time variable used in the request URL.
    • Confirm request URL domain— The domain only, e.g., api.example.com. You do not need to include the protocol or variables.
    • Cache response — Optional. Check box to enable.
    • Headers — Optional. Click Add header, then enter a Key and Value. Repeat for additional headers.

    • Throttle requests — Optional. Enable to configure a frequency rate for your requests. Enter the number of API requests per second. The minimum rate is 100 requests per second. This option does not appear if you enabled Cache response.
    • Confirm access rights for request URL — Check the box to confirm.

    • Object locations — Optional. Click Add object location and enter a name and object location. Repeat for additional locations.

Using a feed

You reference a feed when entering content in a message or template in the format:

{{#feed "feed_id"}}
Content referencing the feed
{{/feed}}

If your feed URL includes send time variables, you can override their default values in the #feed block as {{#feed "feed_id" var="value"}}. Or you can set a value in the Delivery step of a composer that applies to all of the channels selected for the message.

Copying feed code

When adding content for a TemplateReusable message content that saves you the trouble of having to rewrite a message. Templates support merge fields and other logic, letting you personalize the resulting messages. , email, or Message center message (Interactive editor only), you can copy code for your feeds from the sidebar, then paste it in your message content. Available code:

  • #feed blocks — Available for all feeds in your project. A preformatted block that includes the feed ID:

       {{#feed "feed_id"}}
       {{/feed}}
       

  • Object locations — Paths defined in the feed settings.

When adding content:

  1. Click Data Feeds to see your list of feeds.
  2. Click   to see a feed’s details.
  3. Hover over a feed name or object location and click   to copy the code.
  4. Select a text field in your message and paste the copied data.

Setting feed error behavior and variable default values

In the Delivery step of a composer, you must configure each feed listed in External data feed options.

  • Failure behavior — Determine how your message is handled if the feed fails. If your message still makes sense without a feed, you may want to send the message even if your data feed fails. Select Abort sending the message or Send message without this data. See also: Success, Retry, and Error Conditions.

  • Default value for [var] — This displays the default value for each send time variable in the feed URL. You can change the value to override the default for that message only.


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"
            }
        ]
    }
}

Differentiating data sources

You can use 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 Handlebars syntax — {{merge_field}}. ) that aren’t a part of a feed and variables that are part of a feed in the same #feed block. For instance, if your content uses project attribute first_name and the feed also has a property first_name, if you don’t namespace it, the feed data will take precedence over the project attribute.

To differentiate the data sources, set the feed namespace using as |alias|. This ensures that Airship uses the proper data for the 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}}

Success, Retry, and Error Conditions

You set the error behavior for your feed in the Delivery step of a composer or with the on_error object in the API.

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.

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 (60s)RetryUp to 4 retries, 60s between attempts.
502/503RetryUp to 4 retries, 60s between attempts.