Overview of URL Templating
URL templating lets you personalize URL fields by inserting variables from the user or account object. This is most often used for Action URLs and text hyperlinks. It can also be used in other URL‑bearing fields where supported (see Component Support).
To control where Candu content appears inside your app, use URL Targeting. URL Templating and Targeting serve different purposes.
Component Support
You can use URL templates and user property variables with these components and fields:
Buttons (Action URL)
Action Cards (Action URL)
Hyperlinks
iFrames (src)
Videos (source URL)
Images (source URL)
If a component is not listed here, assume templating is not supported on its URL fields.
Variables
Insert values from the user or account object with double curly braces:
https://example.com/profile?user={{user.id}}
For more example of variables, see our guide on using variables in content.
Variable Interactions
Variable picker modal
There are three ways variables can be used in Candu:
Inline Rich Text
Insert variables directly into content, like greeting a user by name.
Example: “Welcome back, {{user.firstName}}”
This is not URL templating, it’s text interpolation.
Hyperlinks in Rich Text
Add variables to a link you insert in the text editor
UX is similar to inline text variables.
Limited to variables only, no URL property access.
Toolbox URLs (Action URLs, iFrame src, Video src, Image src)
Insert variables and URL-based properties (like url.pathname[1], url.search.selectedService).
⚠️ Only toolbox URLs support full URL anatomy variables. Inline and hyperlink variables are limited to user/account traits.
Hashes
You can pass variables in the URL hash for client‑side apps:
https://example.com/#userId={{user.id}}
URL Anatomy Reference
When templating URLs, you can pull values from different parts of the current page URL.
Example URL Breakdown:
For the URL: https://production.canduhosted.com/app/integrations?openIntegrationInfoModal=true&selectedService=segment
url.protocol # "https:"
url.hostname # "production.canduhosted.com"
url.hostname[0] # "production"
url.hostname[1] # "canduhosted"
url.hostname[2] # "com"
url.pathname # "/app/integrations"
url.pathname[1] # "integrations"
url.search # "openIntegrationInfoModal=true&selectedService=segment"
url.search.openIntegrationInfoModal # "true"
url.search.selectedService # "segment"
Domains
Templated URLs work on both your test and production domains. Verify your links in the correct environment before publishing.
Action button URL (basic)
Action on click/tap with a templated URL
Adding a fallback
Example: https://{{user.region|us}}.companyname.com
If you want to provide a default value in case the User Trait is not available, use a pipe (|) followed by the fallback value:
Inspecting variables on an action
Review the variables applied to an action, including field‑level fallbacks.
Action inspector showing variable list
Fallbacks and Defensive Design
Templated links depend on data. Plan for cases where a variable is missing or not yet loaded.
Prefer upstream defaults
Set safe defaults in your user or account payload. For example, provide account.id: "unknown" when the real value is not available.
This avoids generating malformed URLs like:
https://.candu.ai ❌ broken
and instead produces a valid fallback:
https://unknown.candu.ai ✅ safe
Leave routing logic to your application where possible
When a variable may be missing, don’t rely on a personalized link that could fail. Instead, point to a general destination and let your application handle the routing.
For example: /dashboard ✅ safe
instead of /dashboard?account={{account.id}} ❌ may fail if account.id is missing
Guard the action in your app
If your app requires an ID, redirect users to a chooser screen or show an inline message that asks them to complete setup, then return them to the intended page.
Control visibility until data is ready
If your flow depends on a variable, don’t show an action until the required data is available. You can use Candu segmentation or conditional content to guarantee variables are present before the action appears.
This avoids showing a disabled or confusing button and keeps the experience smooth.
Test media sources with real and fallback values
For Images, Videos, and iFrames, make sure the templated URL works whether the variable resolves or not. Provide a safe default in the variable itself or ensure the destination handles missing values gracefully (for example, showing a placeholder image or a help page).
Avoid sensitive identifiers in URLs
Do not place emails or other sensitive values into query strings unless your security model permits it. Prefer opaque IDs.
Best Practices for URL Templating
Test templated links in your test domain first. Validate edge cases and missing data.
Keep query strings short and stable. Do not rely on parameters that the target app frequently changes.
Troubleshooting URL Templating
Variables are not resolving
Confirm the variable names match your schema, for example user.email, account.id. Verify the user and account data is being passed to Candu in the current environment.
The link opens a blank page
Check that the target app supports the URL structure, especially when using hash fragments. Verify you are using the correct domain for the environment.
Works in test but not in production
Ensure the production SDK is installed and passing the same variables. Look for environment differences in routing or variable availability.