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 set up 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:

Custom Variables

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:

Ecommerce Cart 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 the 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 that 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 Campaign 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 the popup:

[[attribute: predefined variables]]

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

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:


This is how the Campaign will look like in the editor:


In this example, we have set the display language of the visitor's country as English. Let's say we have a visitor from Germany, they will see the following popup:


7. Things to keep in mind when using Dynamic text replacement

  • You must pay attention that there is no typo in the used characters. In case you have any typos, the used text will show up instead of the text replacement. 
  • The name of the variable must match the name used in your JavaScript code. It cannot contain any special characters, and it also differentiates between upper case and lower case letters.

That's it! If you have any further questions or need any help, just let us know at support@optimonk.com and we would be more than happy to assist you :) 

Have more questions? Submit a request