Dynamic Text Replacement

1. When should I use Dynamic Text Replacement?

You should use Dynamic Text Replacement (DTR) when you want to customize the content of your popups based on custom variables or cart attributes. For example, when you want to address customers by their name, or display the total value of their current cart in the popup.

2. How do I setup OptiMonk to use Dynamic Text Replacement on my site?

OptiMonk gathers the data used for DTR through a JavaScript code that is inserted on your site. You define the custom variables you want to use with DTR and their value within this code, and then insert the code on your site.

3. How does OptiMonk gather the data used for Dynamic Text Replacement?

The value of your custom variables can be set through various methods, and the data can be acquired from different sources, including your database.

Please refer to this article for information on how to configure OptiMonk to gather data from the custom variables you want to use with DTR:


If you’d like to use cart content data with DTR, such as total value or number of items, please read section 3 of this article on Ecommerce Segmentation:


4. How do I use placeholders to customize my popups with Dynamic Text Replacement?

DTR can be used with any of our templates, including custom HTML templates. After defining the custom variables or cart content data in the JavaScript code, you have to put placeholders in the text of your popup. The placeholders you use must follow a specific format to enable the system to recognize them, and replace them with the values of your custom variables:

        [[type:variable|default value]]

The system will interpret the information between the double square brackets, ‘[[‘ and ‘]]’.

First, the type must be defined. This can either be cart or attribute, depending on whether you would like to use cart data or a custom variable, respectively.

Following the type is a colon, ‘:’, and the name of the variable. The name of the variable must match the one you set in the JavaScript code. It can't contain any special characters, and it’s case-sensitive, meaning uppercase and lowercase letters are interpreted as different characters.

The last part is optional: Following the type is a vertical bar ‘|’ and the text you would like to use as a default value. This default value will be displayed in the event the custom variable is not set, and doesn't return a value to the system.

The following placeholders are available for using cart data:

  • Total value of cart: [[cart:total]]
  • Number of: [[cart:number_of_items]]
  • Number of types of: [[cart:number_of_item_kinds]]

Please note:

  • Placeholders can't contain any typos. If your placeholder can't be interpreted by the system, the entire placeholder will show up on the popup.
  • The custom variable name must match the name you set up in JavaScript exactly.

5. An example of a custom popup using Dynamic Text Replacement

Let’s look at an example of how to customize a popup with DTR including using the optional entry for default value. One of the best uses of DTR is to address your visitors by name. You’d like to address all your visitors by name, but you might not have this data for all visitors.

The solution is to use the default value to create a campaign which displays the text 'Dear Visitor' for non-registered users, and displays their first name if they are registered.

The first step is to define the custom variable firstname in your JavaScript, and then implement that code to extract the visitor's first name from your database. Please refer to the link to the article on custom variables above. Next, you’ll have to put a placeholder in the text of your popup. This is what the placeholder for our example looks like. We’re using attribute for the type, firstname as the name of our custom variable and Visitor as the default value.

Dear [[attribute:firstname|Visitor]]!

The below screenshot shows what this looks like in the popup editor in your OptiMonk dashboard.

When the visitor is a registered user and their first name is available, the popup will look like this:

When the visitor is not registered or logged in, the system will display the default value we provided in the placeholder.

However, when you haven't specified a default value in the placeholder, and the data is not available, no text will be displayed.

As you can see above, it’s important to define a default value in the event the popup may be displayed to a visitor and the data defined in your custom variable is not available. Otherwise, it may appear that some text or content is missing from your popup.

Using Dynamic Text Replacement will customize your messages for specific visitors. By providing a default value you can make sure your popups continue to be effective for all visitors.

6. Dynamic Country Replacement (DCR)

Dynamic Country Replacement (DCR) allows you to display the country of your website visitors, creating targeted offers that engage your visitors.

You can use DCR with any new or current templates, including custom HTML campaigns. To use DCR in one of your campaigns, all you need to do is to place a special string into the text of popup.

[[attribute: predefined variables]]

Additionally, you can specify the language that is displayed. Here are the predefined variables which you can use with DCR to control the display language:

To use Hungarian as the display language for DCR in your popup, use the following string:


To use English as the display language for DCR in your popup, use the following string:


To use German as the display language for DCR in your popup, use the following string:




Have more questions? Submit a request