Dynamic Keyword Insertion

Last Updated: 2025-03-29

Dynamic Keyword Insertion allows you to personalize content on your website by replacing placeholders with dynamic values. This feature is particularly useful for creating personalized experiences based on URL parameters, geolocation data, and other variables.

How It Works

Stellar uses a simple templating syntax with double curly braces to identify and replace keywords with dynamic values.

Basic Syntax

{{variable_name}}

When Stellar encounters this syntax in your content, it will look for a matching variable in the __stellar.variables object and replace the placeholder with its value.

Using Fallback Values

You can specify a fallback value that will be used if the variable is not defined:

{{variable_name||fallback value}}

If variable_name is not defined in the __stellar.variables object, the text "fallback value" will be displayed instead.

Available Variables

Stellar currently supports two main types of dynamic variables:

1. URL Parameters

Any parameter in your URL's query string is automatically available as a variable. For example, if your URL contains ?product=shoes&color=blue, you can use{{product}} and {{color}} in your content.

UTM Parameters

UTM parameters are a special case of URL parameters that are commonly used for tracking marketing campaigns. For example, if your URL contains ?utm_source=facebook&utm_campaign=summer, you can use {{utm_source}} and {{utm_campaign}} in your content.

2. Geolocation Data

Stellar automatically fetches geolocation data for your visitors and makes it available as variables. This data is fetched from a third-party service and cached in the browser for performance.

The following geolocation variables are available:

• {{country}} - Country name (e.g., "United States")
• {{countryCode}} - Two-letter country code (e.g., "US")
• {{city}} - City name (e.g., "San Francisco")
• {{currency}} - Local currency name (e.g., "US Dollar")
• {{currencyCode}} - Currency code (e.g., "USD")

Example Usage

URL Parameter Example

<h1>Browse our {{category||products}}</h1>

If the URL contains ?category=shoes, this will display: "Browse our shoes"
If the category parameter is not present, it will display: "Browse our products"

Geolocation Example

<div class="shipping-notice">
  <p>Shipping to {{cityName||your city}}, {{countryName||your country}}</p>
  <p>Estimated delivery: 3-5 business days</p>
</div>

This will display the visitor's city and country if available, or fall back to generic text.

Combined Example

<div class="promo-banner">
  <h2>{{utm_campaign||Special}} Offer for customers in {{countryName||your country}}!</h2>
  <p>Use code {{promo_code||WELCOME10}} at checkout</p>
</div>

Best Practices

• Always provide fallback values for important content
• Keep variable names simple and descriptive
• Test your dynamic content with different variable values
• Be mindful of privacy - geolocation data is approximate and should be used responsibly
• Consider the user experience when geolocation data is not available or when users block location tracking

Troubleshooting

If your variables are not being replaced correctly, check the following:

• Ensure the Stellar snippet is properly installed on your page
• Verify that the variable exists in the __stellar.variables object (you can check this in your browser's console)
• Check for syntax errors in your template (e.g., missing or mismatched curly braces)
• For geolocation variables, be aware that they may take a moment to load, especially on the first visit to your site
• If geolocation data fails to load, fallback values will be used