Widget Setup: Domain and URL Rules
Before using the API methods to open or customize the widget, configure the domains and URLs where it’s allowed to appear. The system will then check the current browser tab against your configuration.
Note: The widget will only appear on the domains and URLs you configure. If the page matches your setup, the widget loads automatically; otherwise - it stays hidden. This ensures that widget is shown only on relevant websites
1. Domain-Only Configuration
A domain-only setting means the widget will appear only on the exact domain you configure (e.g., app.hubspot.com), but not on other subdomains. The system supports configuration entries with domain names only, without full URLs.
Entries without http:// or https:// are treated as domain-only.
Domain-only entries match the exact domain specified, not other subdomains.
The system generates all possible hostname combinations for the given URL to check for matches.
For Example:
app.hubspot.com → triggers on https://app.hubspot.com/accounts.
The widget is not Triggered on https://help.hubspot.com/accounts (different subdomain)
2. Full URL Configuration
The widget will only appear on pages that start with the exact URL path you configure (including subdomain, path, queries, and fragments), and won’t trigger on other pages.
Entries with http:// or https:// are treated as full URLs.
When a full URL is configured (e.g.,
"https://app.hubspot.com/help-center"), the system will only allow access to pages that start with the specified path.Path matching are prefix-based.
Query parameters and hash fragments are considered part of the path.
For full URLs, the system requires an exact match of the hostname, including the subdomain.
For Example:
Configured: ["https://app.hubspot.com/help-center"] (with http/https prefix)
Widget Triggered: https://app.hubspot.com/help-center
https://app.hubspot.com/help-center/my-page
Widget Not Triggered: https://app.hubspot.com/accounts
https://help.hubspot.com/help-center (different subdomain)
3. Full URL with No Path
The widget will show on any page within that exact domain, but not on other subdomains or different domains.
Specify a URL with protocol and domain only (no specific page), e.g.,
https://app.hubspot.com.The widget can appear on any page within that domain.
The system checks all possible variations of the domain to determine a match.
For Example:
Configured: ["https://app.hubspot.com"] (with http/https prefix, no path)
https://app.hubspot.com triggers on all pages within app.hubspot.com, but not on help.hubspot.com.
Widget Triggered: https://app.hubspot.com/accounts
https://app.hubspot.com/help-center/my-page
Widget Not Triggered: https://help.hubspot.com/accounts (different subdomain)
https://guidde.com/accounts (different domain)
4. Subdomain Handling
You can choose whether the widget works only on a specific subdomain or across an entire domain and all its subdomains
When a specific domain is configured (e.g.,
app.hubspot.com), the widget will appear only on that exact domain.When a parent domain is configured (e.g.,
hubspot.com), the widget will appear on all subdomains.The system automatically checks all variations of the current URL to find a match.
For Example:
Configured: ["hubspot.com"]
Widget Triggered: https://app.hubspot.com
https://help.hubspot.com, https://hubspot.com
Configured: ["app.hubspot.com"]
Widget Triggered: https://app.hubspot.com, https://app.hubspot.com/accounts
Widget Not Triggered: https://help.hubspot.com (different subdomain)
5. Mixed Configurations
Mixed configurations let you combine domain-only and full URL entries. The widget will show up if any of them match the page you’re on.
You can configure both domain-only and full URL entries.
The widget will appear if any configured entry matches the current page.
The system checks all entries before deciding not to show the widget.
6. Query Parameters
Query parameters count as part of the page path. To match, the current page must include the same parameters in the same order.
Query parameters (e.g.,
?param=value) are treated as part of the page path.Exact match required for configured parameters.
For a full URL with query parameters, the current page must start with the same parameters to match.
The order of parameters matters..
For Example:
Configured: ["https://app.hubspot.com/help-center?param=value"]
Widget Triggered:
https://app.hubspot.com/help-center?param=value
https://app.hubspot.com/help-center?param=value¶m2=value
Widget Not Triggered:
https://app.hubspot.com/help-center (missing query parameter)
https://app.hubspot.com/help-center?param=different (different value)
7. Hash Fragments
Hash fragments must match the configured value exactly; the widget appears only if the page starts with the same hash.
Hash fragments (e.g.,
#section) are treated as part of the page path.For a full URL with a hash, the page must start with the same hash to match.
For Example:
Configured: ["https://app.hubspot.com/help-center#section"]
Widget Triggered:
https://app.hubspot.com/help-center#section
https://app.hubspot.com/help-center#section/subsection
Widget Not Triggered:
https://app.hubspot.com/help-center (missing hash)
https://app.hubspot.com/help-center#different (different hash)
8. Complex URL Component Combinations
The widget matches the full URL, including path, query parameters, and hash - using prefix logic; any difference in these components can prevent it from appearing.
The system treats the path, query parameters, and hash fragments as a single combined path.
For Example:
Configured:
["https://app.guidde.com/playbooks/ovVUM9x27RChA2oRaMvbSG?activePage=1#section"]
Widget Triggered:
https://app.guidde.com/playbooks/ovVUM9x27RChA2oRaMvbSG?activePage=1#section
https://app.guidde.com/playbooks/ovVUM9x27RChA2oRaMvbSG?activePage=1#section/subsection
Widget Not Triggered:
https://app.guidde.com/playbooks/ovVUM9x27RChA2oRaMvbSG?activePage=2#section (different query value)
9. Port Numbers
Port numbers are treated as part of the hostname and must match exactly; the widget won’t appear on URLs with a different or missing port.
Port numbers are considered part of the hostname and must match exactly.
URLs with ports do not use subdomain matching.
The port must be explicitly configured for the widget to appear.
For Example:
Configured: ["localhost:3000"]
Widget Triggered: https://localhost:3000/dashboard
Widget Not Triggered: https://localhost:3001/dashboard (different port) https://localhost/dashboard (no port)
10. IP Addresses
The widget will only appear on the exact IP address you configure; it won’t show on other IPs, ports, or subdomains.
IP addresses (IPv4 or IPv6) are treated as exact matches and do not support subdomains.
IP addresses must match exactly (no variations or subdomains).
For Example:
Widget Triggered:
https://192.168.1.1/dashboardWidget Not Triggered:
https://192.168.1.2/dashboard(different IP)https://192.168.1.1:8080/dashboard(different port, unless configured)
11. Root Path Handling
Setting the root path (/) lets the widget appear on any page within the domain, but not on other subdomains.
The root path acts as a prefix, matching all sub-paths.
Other subdomains are not included.
For Example:
Configured: ["https://app.hubspot.com/"]
Widget Triggered:
https://app.hubspot.com/
https://app.hubspot.com/help-center
https://app.hubspot.com/accounts
Widget Not Triggered: https://help.hubspot.com/ (different subdomain)
Widget Triggering Behavior
The widget appears only on allowed pages.
If a page doesn’t match, the widget stays hidden.
The initial page check happens when the page loads; once shown, the widget remains visible even if the URL changes.
Once the widget is configured and triggered based on your allowed domains/URLs, you can use the Broadcast API to control its behavior.