External data feeds

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.

External API requirements

Your external API must operate in these 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.

Feed settings

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

• 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 is meaningful to use and relatively easy to type. You cannot change the feed ID later.

• Description — A summary of the data returned by the feed.

• Request URL — The URL to retrieve data from, also called the feed URL. The URL is your domain, protocol, and path (e.g., https://api.example.com/products/) and any variables you want to use to personalize your messages.

  • Use double square brackets ([[var]]) for send time, or message-level, variables.
  • Use curly brackets ({{var}} — standard 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. ) for variables whose values come from audience data — attributes, custom event properties, etc.

  This example feed URL has a send time variable (msg_purpose) and variables populated with audience data (first_name and last_name):

  https://api.example.com/[[msg_purpose]]?user={{first_name}}%20{{last_name}}

   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 for send time variables — A default value is required for each send time variable used in your request URL. You can override the value when creating a message.

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.

 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.

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 property in the API.

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.