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.

About external data feeds

Using external data 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. .

In your message, you’ll create a merge field representing a value you want to personalize, surrounded by double curly braces {{ }}, also known as HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data. . Airship replaces the merge field (and braces) with the data specified by the merge field at send time — just like mail merge in a word processor or mail client.

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.

You can use external data feeds when creating messages in both the dashboard and API.

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 in the code copying helper in the Interactive EditorA tool for creating content for landing pages, Message Center, email, and in-app automation. You can provide your own HTML or design using the drag-and-drop WYSIWYG option. . See the TIP box in Formatting content below.

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.

External API requirements

Your external API must operate in the following ways to work with external data feeds:

  • Return correct Content-Type header for the response. We support application/json.
  • Return the correct Content-Encoding header if you are compressing your responses. We support gzip for compression.
  • Return your content as a JSON object. We do not support top-level JSON arrays. Array content must be nested in an object.
  • Return a X-UA-Segmentation-Action header to specify an action to be taken by Airship. The only value supported is drop, to block the the recipient from the send. This header is valid only for 200- and 400-level status codes and is ignored if provided for 300- or 500-level status codes. It is also ignored if the value is not recognized.

Workflow

The following is the general workflow for using external data feeds in messages.

  1. Create an external data feed in the dashboard.

  2. Reference a feed when entering content in a message or template using the following format.

    {{#feed "feed_id"}}
    Content referencing the feed, like {{first_name}} or {{mtn_weather}}.
    {{/feed}}
  3. Set failure behavior and variable values when sending the message.

Creating a feed

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

  2. Click Add data feed.

  3. Configure the feed settings:

     Tip

    If you have users with Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. set, you can use the ua_named_user_id default attribute to fetch feed data for their external ID:

    https://api.example.com/[[msg_purpose]]?user={{ua_named_user_id}}

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

      Click Add header, then enter a Key and Value. Repeat for additional headers.

    Click Next to move on.

  4. Configure:

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

    Click Next to move on.

  5. Configure:

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

  6. Click Done.

Using a feed in messages

You add your data feed to messages in two parts:

  1. Formatting the message content
  2. Entering default values for the variables you referenced in your message and determining how to handle the message if the feed fails

Formatting content

Formatting your message content is identical in the dashboard and the API. In the dashboard you add content when configuring a template or in the Content step in a composer.

Content format for External Data Feeds
   {{#feed "feed_id"}}
   Content referencing the feed, like {{first_name}} or {{mtn_weather}}.
   {{/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 that applies to all of the channels selected for the message.

 Tip

When using the Interactive EditorA tool for creating content for landing pages, Message Center, email, and in-app automation. You can provide your own HTML or design using the drag-and-drop WYSIWYG option. to create content for a template, email, landing page, or Message Center message, we provide a helper for inserting feed code. Available code:

  • Object locations — Paths defined in the feed settings.
  • #feed blocks — Available for all feeds in your project. A preformatted block that includes the feed ID:
{{#feed "feed_id"}}
{{/feed}}

When adding content:

  1. Click Data Feed in the left sidebar.
  2. Click   for a feed.
  3. Hover over a feed name or object location and click   to copy the code.
  4. Select a field in your message content and paste the copied data.

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

Setting feed failure behavior and variable 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. Also consider how ongoing (automated and recurring) messages will be affected if you later delete the feed.

    Select Abort sending the message or Send message without this data.

    See also: Success, Retry, and Error Conditions.

  • Send time variables — If your feed URL contains send time variables, each one will be listed as Default value for [var] with its default value. You can change the value here to override the default. Changes apply to the current message only.


With the API, you set the failure (error) behavior in the External Data Feed References Object. When using a data feed you must include a templates object in the payload or set the personalization option to true.

  • The value for name is the Feed ID you set when creating your feed.

  • The possible values for on_error are cancel and continue. These are equivalent to the dashboard options Abort sending the message and Send message without this data.

    continue will result in sending the message despite an error. Otherwise, a feed failure will prevent Airship from sending your message.

Example push request using an external data feed
{
    "feed_references": {
        "feeds": [
            {
                "name": "featured_products",
                "params": {
                    "region": "us"
                },
                "on_error": "continue"
            }
        ]
    }
}

Managing external data feeds

Go to Settings and click Manage for External Data Feeds to see a list of all your feeds.

Click   to edit all fields except the Feed ID. If you make changes to the Request URL, you will need to reconfirm the request URL domain. You must confirm access rights for request URL every time you edit a data feed.

Deleting a feed

 Warning

  • If you delete an external data feed, any messages content referencing its data will be handled according to the message’s feed failure behavior settings.
  • Your external data feed is deleted immediately. There is no confirmation and your external data feed cannot be restored once deleted.

  1. Go to Settings and click Manage for External Data Feeds.
  2. Click   for a data feed.
  3. Click Delete.

Success, Retry, and Error Conditions

Airship considers any 2xx response from a feed to be a success and will continue a message using the 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.