Dynamic content enables editors to compose a single message that is dynamically personalized for each user who receives it. It is supported in Email, SMS, and Push Notification messaging.

Dynamic content enables editors to upload a CSV file with personalized content. Next, editors can set up the message to automatically extract and display data from the CSV file based on the attributes of each message recipient.

Common use cases include translation/localization, customized content based on user preferences, or customized content based on user country or location.

Detailed Benefits of Dynamic Content

Dynamic Content in OneSignal opens up new avenues for personalized, efficient, and language-sensitive communication. By understanding and utilizing this feature, businesses can significantly enhance their engagement with diverse customer segments.

• Ideal for Multi-language Communication: Easily manage and send multilingual content, catering to a global audience. Dynamic content is designed for use when sending to many languages at once.
• Segment-Specific Content: Send a single email tailored to multiple segments, each receiving content relevant to their interests or behaviors.
• No Direct Access Needed for Content Editors: Content editors can create personalized messages without needing direct access to OneSignal, streamlining workflow when working with domain experts or translators.

Using Dynamic Content

The Dynamic Content feature can be found when creating a new message within the Email, Push, and SMS editor.

You can click the Dynamic Content button to see instructions on how to upload personalized content. To add Dynamic Content to a message, you must upload a CSV file containing content to be displayed according to your recipient's User Property or Data Tag values. Then, reference that content using Liquid Syntax.

To send a message with Dynamic content, follow these steps:

1. Create a new message
2. Select an Editor if sending an email.
3. Select Dynamic Content.
4. Download a Template to format the spreadsheet.
5. Substitute your content
6. Save and upload your CSV
7. Copy the boilerplate liquid syntax provided in the dynamic content sidebar wherever you want to display your content: {{dynamic_content.file_name.section_name[user_property]}}
   1. replace file_name with the name of your CSV file. Remember to choose a file with no spaces in the name.
   2. replace section_name with the name of the row in the CSV you want to display.
   3. replace [user_property] with the User Property or Data Tag you want to display.

      📘

      For example, convert the boiler plate liquid syntax

      From{{dynamic_content.file_name.section_name[user_property]}}

      To{{dynamic_content.event_translation.paragraph_1[user.language]}}

Creating a file with your Dynamic Content

We provide two dynamic content templates to make it easy to get started:

1. Multi-language campaigns and
2. General content personalization.

You can download a template and open it in a spreadsheet editor. Ensure your editor is set to load and save files in UTF-8 encoding.

You can edit this template with either a data tag or a user property and the content you want to substitute.

📘

For general Content Personalization, we would recommend using a Data Tag; For example, you might want to display different content based on a {{plan_type}}, {{industry}}, or {{persona}}.

Each row represents content that you will reference with a specific identifier. Give a unique identifier to each row to ensure it does not include spaces or unique characters.

In this example, where user property is the user.language or the language_code, each column represents the value of that user property. Rows are values of a property or data tags that you will use to determine which content to display to each recipient.

When ready, upload the template to your message.

Referencing your uploaded Dynamic Content in a Message

OneSignal provides a boilerplate liquid syntax within the Dynamic Content side panel. For the custom data to display properly in your message, you must substitute and reference the columns and rows within the CSV.

{{dynamic_content.file_name.section_name[user_property]}}

Substitute the values in the provided liquid with the values you uploaded, so the message populates your user's custom data at email send time (e.g., convert {{dynamic_content.file_name.section_name[user_property]}} to {{dynamic_content.event_translation.paragraph_1[user.language]}}.)

Replace these values:

• file_name: The filename of the CSV
• section_name: The value of the row you want to display.
• [user_property]: The column associated with the user property you want to display.

For example, your substituted liquid syntax might look like: {{dynamic_content.event_translation.paragraph_1[user.language]}}

Add a fallback property

When substituting content, there's always a chance that a subscription is missing a value for a Data Tag, or does not have a language set. In that case, you could specify a fallback property.

There are two ways to define defaults in Using Liquid Syntax that apply in this case

1. Setting a variable at the top of your message

This is the recommended option for emails or content with multiple substitutions.

{% assign lang = user.language | default: "en" %} 
~~~
{{dynamic_content.event_translation.header[lang]}}

2. Referencing the default value specifically for each substitution.

{{dynamic_content.event_translation.header[user.language] | default: dynamic_content.event_translation.header.en}}

Example of Dynamic Content for a multi-language email

For a multi-language message, your template will include some language codes. You can add language codes matching your user's language properly.

We recommend using the user propertyuser.language, so that when one subscription has a language change, all other subscriptions that belong to that user will reflect those changes.

In this example,event_translation is the filename for the CSV uploaded to the email. section_1 and section_2 refer to the content of the row. [user.language] property refers to the column that would display according to the User's language code.

• {{dynamic_content.event_translation.section_1[user.language]}}
• {{dynamic_content.event_translation.section_2[user.language]}}

Draft the dynamic content

Draft the content of your email in a spreadsheet and export it as a CSV. This multi-language message, where the content of event_translation.csv is translated into 5 languages. The content was originally written in English for the event invitation and then was shared with translators to draft the content for each language.

Notice that each section of the email has its own identifier (e.g., header, date, button_1, etc).

Editing your email design

Build out the design of your email and substitute all text that needs to be rendered from your dynamic content. Once you replace the boilerplate liquid syntax with your CSV file and dynamic content properties, your liquid syntax should be like the examples below. Please note these examples refer to the CSV example shown above.

{{dynamic_content.event_translation.header[user.language]}}

{{dynamic_content.event_translation.date[user.language]}}

{{dynamic_content.event_translation.button_1[user.language]}}

{{dynamic_content.event_translation.body_1[user.language]}}

You can update button URLs, and even swap out the unsubscribe language, by editing the "Text to display".

Also, you can substitute content anywhere liquid syntax is accepted, such as the Subject line or Preheader.

Test and preview the emails before sending

To view your email and how it will be sent to your customers, you'll want to set up a segment of test emails and send out a message to that segment.

Create a CSV of test users

Create the CSV file of test recipients, and add at minimum email, and language.

Make sure the language follows the language_code format.

📘

Most inboxes allow you to add a + then a value, to send a different email to the same inbox. [email protected] format is used to create many test users that will send the different test emails to the same inbox.

Upload your test segment

To upload your test segment, go to the Subscriptions or Segments page and select Upload/Import Users

Note: The identifier should be the first column. Any column after the first is treated as a user property or data tag that will be added or updated for that identifier.

• After adding the file to the CSV import tool, you can create a segment during the import process. Select "Create Segment" to generate a recipient list and choose your target audience for the message.

View the rendered emails in your inbox

After you have sent the emails to your test segment, check your email inbox to view the rendered emails.

Usage Considerations

When to Use Dynamic Content vs. Custom Data

• Use Dynamic Data when composing messages that encompass diverse languages or varied content types tailored to user-specific data
• Custom Data can be used when aiming to personalize specific data elements within a message in a single language

Size Limits for Dynamic Content

• The size limit for dynamic content is 200kb

Updating and Editing Templates

• To replace values in a template, you can download the CSV you imported into the Dynamic Content drawer and re-upload to make changes.
• The content is disconnected when you make a campaign from a template or save a template from a campaign. Editing the new CSV won't edit the old one.

Handling Non-Alphanumeric Characters

When your CSV contains non-alphanumeric characters in section names or user properties, you should use hash notation versus alphanumeric and dot notation to display their values in Liquid syntax.

For example, using Hash notation with non-alphanumeric characters.

Hash Notation: {{ dynamic_content.file_name["!the_row!"]["&the_column&"] }}

However, for section names and properties with alphanumeric characters, use dot notation:

Dot Notation: {{ dynamic_content.file_name.the_row.the_column }}