Personalization

Templates help you create messages quickly and provide a mechanism to personalize your messages for your audience. The way in which you personalize messages or create templates varies by channel and, in some cases, your audience.

Personalizing Messages

Templates provide a way to script and re-create messages quickly. When you create a template, you set a design and message that you can resend. You create templates and personalize messages differently depending on the type of message you want to send.

You can create templates for push notifications, in-app messages, and email notifications.

Merge Fields

You can use merge fields in templates — variables in your message that you want to populate with audience information, personalizing the message for each recipient.

You add merge fields when you create a template, and you populate the fields at send time, uploading ("merging") the data in an audience list.

Message Templates and the Personalization API

Push templates are intended for non-email channels and support push notifications and in-app messages. The setup is very much like a standard message. You can create push templates using the dashboard or the /personalization API, but you can only send a message with a push template using the API.

Email templates are specifically for email, and they support all the features of an email message, including a full HTML message. You can create and use email templates through the dashboard.

Inline Lists and Templates

When sending a message to SMS, email, or open channels, you have the option to Upload Users as a CSV list. When you upload a list in this way, you can include additional merge data in your list, creating a sort of "inline" or single-use template.

Column titles in your list (or the create-and-send audience object in the API) that are not prefaced with ua_ are considered merge fields. You can reuse these column titles as variables in your message using {{column_title}} when you send a message this way.

Dynamic Content for Inline Lists

When writing a message using an inline list or the /create-and-send API, you can insert conditional logic to personalize messages for each audience member based on the information in your inline list — like a single-use template. Airship evaluates the conditions you include in your message to determine the content to send to each member of your audience.

Dynamic Content uses the following syntax:

{{#eq merge_field "string value"}}
    text appears when merge field contains "string value"!
{{/eq}}

Logical Operators and Basic Syntax

Use the following logical conditions to determine the message contents you want to send to each member of your audience.

{{#if}} — If condition
Renders message text if the condition is not false, empty, or 0.
{{#if movies}}
   You might like Indiana Jones.
{{else}}
   Maybe you'd enjoy a book instead.
{{/if}}
{{#eq}} — Equal to
Renders message text if a merge field contains a particular string value. In this example, the message is different if the merge field category contains the value Accessories.
{{#eq category "Accessories"}}
   Enjoy up to $25 off!
{{else}}
   Get up to $75 off!
{{/eq}}
{{#neq}} - Not equal to
Renders message text if a merge field does not contain a string value.
{{#neq things "thing 1"}}You must be thing 2!{{/neq}}
{{#and}} — And
Renders message text if all conditions are true.
{{#and (eq genre "action") (eq era "80s") }}
   You will definitely like Indiana Jones!
{{/and}}
{{#or}} — Or
Renders message text if any of the conditions are true.
{{#or (eq movies "action") (eq era "80s") }}
   You might like Indiana Jones!
{{/or}}
{{#not}} — Not
Renders message text if the merge field is empty or 0.
{{#not movies}}You might be interested in our new TV shows!{{/not}}`
{{else}} - Else
An alternative to a condition. Renders message text if the previous conditions fail and any conditions included with the else statement pass. When used without parameters, else renders a message if all previous conditions fail. Your message can have multiple else statements for any operation. For example, the following statement has else statement with a parameter and an else statement without:
{{#eq var_name "value"}}Money has value
{{else eq var_name “pizzaz”}}You have pizzaz
{{else}}I don't know what to tell you{{/eq}}
{{unless}} - Unless
Renders message text if the condition is false. This is a negative condition; you might want to use unless when you only really need the else statement for a condition. In the example below, the message text renders if the condition not_a_movie_watcher is empty or false.
 {{unless not_a_movie_watcher}}You'll probably like Indiana Jones.{{/unless}}

Comparison Operators

These operators compare two values — numbers or length (when comparing string values or arrays) and display text based on the result.

  • {{#lt}} — less than
  • {{#gt}} - greater than
  • {{#lte}} — less than or equal to
  • {{#gte}} — greater than or equal to

The following example displays text if "quantity" is less than 2.

{{#lt quantity 2}}You have <2 items in your cart{{/lt}}

Object and Array Notation

You can use standard dot notation to access properties in objects or an item/index in an array.

Use the array index to access an item at a particular location in an array. For example, if your message includes an array of objects called suggestedProducts for each member of your audience, you can access the first suggested product with suggestedProducts.0 (array index 0).

 Note

Array indexes start at 0.

If you want to reference a key called image belonging to the first suggested product in the array, you would use suggestedProducts.1.image.

Use {{#with}} to set the context to a particular object. This can help you access nested keys without having to repeat the parent object's path. For example, if you wanted to print a user's shipping information from an object called shippingAddress, you might use the with helper like this:

{{#with shippingAddress}} shipped to {{yourStreet}}, {{yourState}}, {{yourPostCode}}{{/with}}

Object and Array Notation for CSV Uploads

When you Upload Users to send a message, you can include complex arrays and objects in your CSV using object notation to represent object properties in the header. When referencing an array index, you must wrap the array index in brackets. Your CSV should include headers for each item in the array and each property in the object that you want to reference in your message.

For example, if you want to use an array of objects called items for each member of your uploaded audience, your CSV will include items.[#] for each item in the array. If each object in the array had name, image, and url properties, you would add items.[0].name, items.[0].image, items.[0].url to your CSV, and reference additional objects in the array by incrementing the index (e.g. items.[1] and so on).

 Note

Array indexes start at 0

If you wanted to personalize an email to members of your audience based on their addresses and the names of items they're interested in, you might format your CSV as follows:

ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[1].name
someone@sample.com,2018-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,Bleach Alternative
else@sample.com,2018-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,Shovel

Looping Through Dynamic Content

Looping operators help you traverse and display text from an array or object in your message. For example, you can show a user all the items in their shopping cart, including quantity, description, and price.

{{#each}} — Loop through an items in an array or keys in an object. Specify the array or object that you want to perform an operation against. Within the loop, you can specify the information you want to display, including a reference for the current array index or object key.

This example displays a user's shopping cart items:

Are you still interested in {{#each cart}}{{this.qty}}x {{this.product}} for {{this.price}}{{/each}}?
  • {{@index}} — Reference the current array index in the loop.
  • {{@key}} — Reference a property in the object in the loop.
  • {{this}} — Reference the content in the loop. Use dot notation to reference a key in the object, like {{this.price}} to access a key in the current object called "price".

Resources