Personalization and Templates

Use handlebars to personalize messages and templates, ensuring that your messages speak to every individual member of your audience.

Personalization is the ability to populate messages with data specific to each individual member of your audience, ensuring that your audience receives messages that are specific and relevant to them.

You’ll use 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. to personalize messages and message actions. You can add simple merge fields or complex logic to determine the content you want your audience to see. When you send a message, Airship evaluates your handlebars to populate content for each member.

What Values Can I Use to Personalize a Message?

You’ll personalize messages and templates using 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. to specify variables that you want to populate messages or evaluate blocks of content. The variables you use to personalize messages can vary based on the kind of message you want to send and the data that you want to draw from.

You can personalize messages using:

You can personalize messages from multiple sources, making it possible for you to have personalization variables with the same name in a message. If two variables share the same name, Airship attempts to use the value nearest to your audience — the value that best represents your audience.

This order isn’t guaranteed, but, in general, Airship attempts to use custom event properties (from an event representing a direct user action) > attributes (values stored on user in Airship) > feed variables (information fully external to Airship and thus farthest from Airship’s interaction with the customer).

For example, if you personalize a message with a custom event property called name and you already have an attribute called name, Airship will normally use the custom event property because it was emitted from a customer action (whereas the attribute existed in Airship).

 Tip

You should name your templates according to the sources they use for personalization, so it’s clear when and where you can reuse your template.

Personalization Using Attributes

Attributes are values assigned to individual channels or named users that help you organize and understand your audience. You can use attributes to personalize messages for your audience. Use {{attribute_name}} to use an attribute in a message or template. The attribute_name is replaced by the associated value for your audience.

Because attributes can represent different kinds of values — text, dates, date-ranges, etc — make sure you know the format of your attributes before using them in a message or template. For example, date attributes print their value only, without precision or operator, so you may want to specify either or both so that the value makes sense in your message.

Personalization Using a Data Feed

An External Data Feed is a connection between Airship an external API; when you send a message referencing a feed, Airship populates variables in your message using the response from the external API.

External data feeds provide a flexible way to personalize messages, without waiting for custom events to come into the system or populating attributes on your audience.

See the External Data Feeds Tutorial for more information about setting up a data feed and using data feeds in your messages.

Example personalization using a feed
{{#feed "featured_products" region="us" as |result|}}
  {{#each (limit result.products 2) as |product|}}
    {{product.name}}: {{product.price}}
    https://cool-store.tld/us/products/{{urlEncode product.slug}}/
  {{else}}
    Check back later for deals!
  {{/each}}
{{else}}
Couldn't fetch featured products!
{{/feed}}

Personalization Using Custom Events

When you trigger an AutomationA set of conditions that your audience must meet before they receive a message. or a JourneyA series of messages that is initiated by a single automation trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine the continuation of the series. with a Custom EventEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom events can trigger automation and journeys. You can code them into your app or website, or send them to Airship from an external source using the custom event API. Custom events contain properties that you can use to personalize messages. , you can use properties from the custom event to personalize the resulting messages. For journeys, you can reuse custom event properties in any message in the journey, which can help remind your audience about items they left in their shopping cart, or that an event that they’re interested in is happening soon.

When personalizing messages or templates for a custom event-triggered automation or journey, you can use anything in the custom event’s properties object.

Example custom event:
{
   "occurred": "{{event_time}}",
   "user": {
      "named_user_id": "user"
   },
   "body": {
        "name": "purchase",
        "subscribe": true,
        "properties": {
            "customer_name": "user",
            "total": 73,
            "cost_units": "USD",
            "products": [
                {
                    "qty": 4,
                    "item": "MLB regulation baseball",
                    "per": 12,
                    "total": 48
                },
                {
                    "qty": 1,
                    "item": "Louisville Slugger",
                    "per": 25
                    "total": 25
                }
            ]
        }
    }
}

Because custom event properties can include arrays, objects, and arrays of objects, you might want to loop through complex custom event properties using {{#each}}. Following the example above, we could confirm products in a customer’s recent order by looping through the products array.

Reference an array of products from a custom event:
{{#each products}}
{{qty}}x {{item}} = {{this.total}}
{{/#each}}
Total: {{total}} {{cost_units}}

Personalization Using an Uploaded Audience

When you upload a list of users, or provide an audience in a create-and-send APIUsed to simultaneously register and send a notification to email, sms, or open channels; synonymous with the Upload Users feature. request, you can include additional properties that you want to use to personalize messages — any column name or property that isn’t prefaced with ua_.

Like attributes, you will use {{column_name}} to personalize a message from a value in your list or {{property_name}} in the audience of a /create-and-send payload.

If you want to personalize your message using both attributes and information from an uploaded audience, you should make sure that the properties in your uploaded audience are unique from your attributes. If an attribute has the same name as a property in an uploaded audience, Airship will try to use the value in the uploaded audience.

Create-and-send request with personalization:
POST /api/create-and-send HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3;
Content-Type: application/json

{
    "audience": {
        "create_and_send": [
            {
                "ua_msisdn": "15551234567",
                "ua_sender": "12345",
                "ua_opted_in": "2020-04-29T10:34:22",
                "name": "New Customer, Esq.",
                "from_city": "City",
                "from_state": "OR"
            }
        ]
    },
    "device_types": [
        "SMS"
    ],
    "notification": {
        "sms": {
            "alert": "Hi {{name}}! I hear you're from {{from_city}}, {{from_state}}!",
            "expiry": 172800
        }
    }
}

Personalizing Message Actions

You can personalize Message ActionsA configurable behavior that occurs when a user interacts with your message, e.g., opening a web page. using 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. , taking advantage of information specific to your audience to personalize your audience’s experience when they interact with your message.

Use properties from a custom event, attributes, or an uploaded list to personalize adaptive linksA mobile wallet pass link that supports templates for both Google Pay and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for the user. , send your audience to their own, specific deep link, or send users to their accounts with web links.

Like messages, you can personalize actions using information from:

 Note

If two personalization variables use the same name, Airship generally attempts to use the most recent variable. In general, this means that Airship will use a property from an custom event or uploaded audience rather than an attribute with the same name, but you may want to make sure your variables use unique names to prevent confusion.

You should set a default value when personalizing message actions to ensure that personalized actions resolve correctly, even if the value you use to personalize the action does not exist.

Personalized Share Text Example
I'm a big fan of {{$def product_name "stuff" }} from This Cool Company.

Go to {{$def product_url "https://www.mysite.com"}} to get your own!

Message Center Actions

When creating a Message Center message or template using the WYSIWYG editor, you can assign an action that occurs when a user taps a button in the message. You can also use 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. to personalize the actions.

Adaptive Link

Adaptive Link opens a mobile wallet pass. Select an Adaptive LinkA mobile wallet pass link that supports templates for both Google Pay and Apple Wallet. When a user taps the link, Airship determines the user’s platform and generates the right pass for the user. from the list.

  • Adaptive links must be configured before they will appear in the actions list. See: Adaptive Links Tutorial.
  • Only adaptive links created in the dashboard will appear in the actions list.
Deep Link

Deep Link opens a screen in your app or website. Select a deep link from the list.

Share Share prompts the user to share your message with apps, social media accounts, and other services. Enter the text you want to accompany the share, including any promotional information, shortened links, hashtags, etc.
Web Page Web Page opens a web page or any valid-device level URL such as App Store or app protocol links. The web page opens in the device’s default browser. Enter a URL.
App Rating Open the system prompt for an App rating.

Click Set a Tag to add or remove tags when a user taps the button.

Personalizing Messages Using the WYSIWYG Editor

Airship’s drag-and-drop WYSIWYG editor helps you compose vibrant HTML message center messages, landing pages, and emails.

When personalizing messages in the WYSIWYG editor, you must define merge fields in before you can use them to personalize blocks of content — unless you write your own custom HTML blocks. (You can personalize custom HTML blocks using 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. like you would any other message.)

The WYSIWYG editor supports three types of merge fields:

  • Standard merge fields (with the type set to None) apply to text blocks; you insert the merge field into a block of content and Airship replaces the merge field with the appropriate value when you send your message.

  • Conditional merge fields apply to rows of content in your template. When you send a message, Airship evaluates the condition and determines whether or not to insert a row of content.

  • Looping merge fields apply to rows of content in your template. When you send a message, Airship evaluates the condition and repeats the row for each variable in the loop.

 Tip

You can also take advantage of looping (#each), conditional if/else statements, and other advanced 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. inside custom HTML blocks. However, you cannot apply conditional or looping logic to block-level elements in your template without defining merge fields in the WYSIWYG editor first.

Additional Resources