Installation
Add the widget script to your HTML <head>:
<script src="https://cdn.obvlo.com/widgets/obvlo-widget.js"></script>
Basic usage
Place the custom element anywhere in your page body:
<obvlo-dynamic-content host-id="your-host-id"></obvlo-dynamic-content>
Configuration attributes
When the widget initialises it resolves its configuration by merging several sources in priority order. A value set by a higher-priority source always wins over a lower-priority one.
| Priority | Source | Description |
|---|
| 1 — highest | HTML attributes | Values you set directly on the <obvlo-dynamic-content> element. |
| 2 | Named embedded config | The embedded config from your host profile whose ID matches the config-id attribute, if provided. |
| 3 | Default embedded config | The first embedded config defined in your host profile, used when no config-id is supplied. |
| 4 — lowest | Attribute defaults | The default values documented for each attribute below. |
Your host profile contains the full list of embedded configs in the embeddedConfigs field. Use the Get Host Profile endpoint to inspect the configs available for a given host-id.
Required
host-id Required
Type: string
The unique identifier for your host profile. This links the widget to your content in the Obvlo system.
profile-id and destination-id are accepted aliases — all three map to the same property.
<obvlo-dynamic-content host-id="abc123"></obvlo-dynamic-content>
<!-- OR -->
<obvlo-dynamic-content profile-id="abc123"></obvlo-dynamic-content>
<!-- OR -->
<obvlo-dynamic-content destination-id="abc123"></obvlo-dynamic-content>
Display mode
drawer
Type: boolean — Default: false
Controls whether the widget appears as an overlay drawer or renders inline.
| Value | Behaviour |
|---|
| (omitted) | Widget displays inline within the page |
drawer (present) | Widget opens as an overlay drawer on top of page content |
<!-- Overlay drawer mode -->
<obvlo-dynamic-content host-id="abc123" drawer></obvlo-dynamic-content>
<!-- Inline mode (default) -->
<obvlo-dynamic-content host-id="abc123"></obvlo-dynamic-content>
drawer-delay-ms
Type: number — Default: 0
Delay in milliseconds before automatically opening the drawer. Only applies when drawer is present.
<!-- Open drawer after 2 seconds -->
<obvlo-dynamic-content
host-id="abc123"
drawer
drawer-delay-ms="2000">
</obvlo-dynamic-content>
Layout
config-id
Type: string
Select a specific embedded configuration from your host profile. When omitted, the first configuration in the profile is used.
<obvlo-dynamic-content
host-id="abc123"
config-id="summer-config">
</obvlo-dynamic-content>
Content filtering
guide-id
Type: string
Display a specific guide when the widget loads. Users can still navigate to other content.
<obvlo-dynamic-content
host-id="abc123"
guide-id="best-restaurants">
</obvlo-dynamic-content>
neighbourhood-id
Type: string
Display a specific neighbourhood/geographic area when the widget loads.
Only one of guide-id or neighbourhood-id should be used at a time. If both are provided, guide-id takes precedence.
guide-type
Type: string
Filter the menu to show only guides of a specific type.
| Value | Description |
|---|
guide | Standard guides only |
neighbourhood | Neighbourhood guides only |
featured | Featured guides only |
Grid display
grid-rows
Type: number — Default: 1
Number of rows to display in grid views on desktop and tablet devices.
grid-rows-mobile
Type: number — Default: 6
Number of rows to display in grid views on mobile devices.
Feature toggles
disable-just-for-you
Type: boolean — Default: false
Hides the “Just For You” personalised guide from the guide menu.
Content personalisation remains fully functional when this attribute is set — only the menu entry is hidden. Useful for kiosk or focused experiences where the personalisation prompt would be distracting.
hide-travel
Type: boolean — Default: false
Hides travel-related content categories from the widget.
Localisation
lang
Type: string
Sets the initial display language for the widget. Must be a full language code supported by your host profile.
Format: language-DIALECT — for example en-GB, es-ES, fr-FR
<!-- Display in Spanish (Spain) -->
<obvlo-dynamic-content host-id="abc123" lang="es-ES"></obvlo-dynamic-content>
<!-- Display in Portuguese (Brazil) -->
<obvlo-dynamic-content host-id="abc123" lang="pt-BR"></obvlo-dynamic-content>
| Code | Language |
|---|
en-GB | English (UK) — default |
en-US | English (US) |
es-ES | Spanish (Spain) |
fr-FR | French (France) |
de-DE | German (Germany) |
it-IT | Italian (Italy) |
pt-PT | Portuguese (Portugal) |
pt-BR | Portuguese (Brazil) |
zh-CN | Chinese (Simplified) |
ja-JP | Japanese |
ar-SA | Arabic (Saudi Arabia) |
Analytics
uid
Type: string
Custom user identifier for analytics tracking. When omitted, a random UUID is generated and persisted automatically in browser storage.
Use this attribute to correlate widget events with your own user sessions. The value should be unique per user and is passed through to Google Tag Manager events.
Examples
<!DOCTYPE html>
<html>
<head>
<title>My Travel Site</title>
<script src="https://cdn.obvlo.com/widgets/obvlo-widget.js"></script>
</head>
<body>
<h1>Explore Our Destination</h1>
<obvlo-dynamic-content host-id="abc123"></obvlo-dynamic-content>
</body>
</html>
Drawer mode with delay
<obvlo-dynamic-content
host-id="abc123"
drawer
drawer-delay-ms="3000">
</obvlo-dynamic-content>
Kiosk mode
No personalisation prompt, travel content hidden, neighbourhood guides only:
<obvlo-dynamic-content
host-id="abc123"
disable-just-for-you
hide-travel
guide-type="neighbourhood"
grid-rows="4">
</obvlo-dynamic-content>
Browser support
- Chrome / Edge — latest 2 versions
- Firefox — latest 2 versions
- Safari — latest 2 versions
- Mobile: iOS Safari, Chrome for Android
Responsive behaviour
The widget automatically adjusts its layout based on container width:
| Breakpoint | Width |
|---|
| X-Large | ≥ 1200px |
| Large | 992px – 1199px |
| Medium | 768px – 991px |
| Small | < 768px |
Troubleshooting
- Verify the script tag is loading correctly (check the browser console for errors).
- Confirm
host-id is correct and the profile is active.
- Check that the element is not hidden by CSS.
Content not loading
- Verify your host profile is properly configured in the Obvlo admin portal.
- Check the browser console for API errors.
- Confirm your host profile has Typesense API keys configured.
Getting help
