Skip to main content
Once your widget is configured and active, embedding it on your website takes just a few minutes. The Compass embed script handles everything — loading the widget UI, managing chat sessions, and capturing visitor attribution data.

​
Prerequisites

Before you can embed your widget, make sure:
  • Your widget has been saved in the widget editor
  • Your widget status is set to Active
Widgets in Draft or Inactive status will not load on any website, even if the embed code is installed correctly. Always check the widget status if your embed isn’t working.

​
Getting the embed code

1

Open the Embed tab

In the widget editor, click the Embed tab. You’ll see your unique embed code snippet ready to copy.
2

Copy the embed code

Click the Copy button to copy the script tag to your clipboard. The embed code looks like this:
<script src="https://app.roserx.health/embed.js" data-widget="YOUR_WIDGET_ID"></script>
Your actual widget ID is pre-filled in the code — you don’t need to replace anything manually.
3

Paste the code into your website

Add the script tag to your website’s HTML, just before the closing </body> tag:
<html>
  <head>
    <!-- Your existing head content -->
  </head>
  <body>
    <!-- Your website content -->

    <!-- Compass Widget -->
    <script src="https://app.roserx.health/embed.js" data-widget="YOUR_WIDGET_ID"></script>
  </body>
</html>
The widget button will appear on your website automatically once the page loads.
Most website builders and CMS platforms (WordPress, Webflow, Squarespace, etc.) have a dedicated area for adding custom scripts. Look for “Custom Code”, “Footer Scripts”, or “Code Injection” in your platform’s settings.

​
Domain restrictions

Domain restrictions let you control exactly which websites are allowed to load your widget. This prevents unauthorised sites from embedding your widget and ensures it only appears where you intend.

​
How to configure domain restrictions

  1. In the widget editor, navigate to the Embed tab.
  2. Toggle Domain Restrictions to enable them.
  3. Add each domain where you want the widget to appear (e.g. www.example.com, docs.example.com).

​
How domain matching works

  • Subdomains are matched automatically — adding example.com allows www.example.com, docs.example.com, and any other subdomain.
  • Each domain entry is matched against the hosting page’s URL.
  • You can add localhost with a port number (e.g. localhost:3000) for local development and testing.
If domain restrictions are enabled but no domains are added, the widget will not load on any website. Always add at least one domain after enabling restrictions.
Add localhost to your allowed domains during development to test the widget locally before deploying to production.

​
How the embed script works

When a visitor loads a page containing your embed code, the Compass script automatically:
  1. Loads the widget UI — Renders the launch button and chat interface based on your widget configuration.
  2. Handles chat communication — Manages the real-time connection between the visitor and your Compass agent.
  3. Persists sessions — Stores session data in the visitor’s browser using localStorage, so conversations continue seamlessly across page loads.
  4. Captures attribution data — Records marketing parameters to help you understand where your visitors are coming from.

​
Session persistence

Visitor sessions are automatically persisted using the browser’s localStorage. This means:
  • Conversation history is maintained as visitors navigate between pages on your site.
  • Returning visitors see their previous conversations when they reopen the widget.
  • Sessions are scoped to the domain where the widget is embedded.
If a visitor clears their browser data or uses a private/incognito window, their session history will not be available.

​
Marketing attribution

The embed script automatically captures visitor attribution data, giving you insight into how visitors find your widget. The following parameters are tracked:
ParameterDescription
UTM parametersutm_source, utm_medium, utm_campaign, utm_term, utm_content
Referrer URLThe page or site that referred the visitor to your website
Click IDsgclid (Google Ads), msclkid (Microsoft Ads), fbclid (Meta/Facebook Ads)
This data is associated with the visitor’s chat session and can be viewed in the Chat Logs section of the dashboard.
Attribution data is captured on the first page load and associated with the visitor’s session. No additional configuration is required — it works automatically.

​
Troubleshooting

  • Confirm the widget status is set to Active in the Compass dashboard.
  • Check that the embed code is placed before the closing </body> tag.
  • If domain restrictions are enabled, verify that your website’s domain is in the allowed list.
  • Open your browser’s developer console and check for any error messages.
  • Verify that an agent is assigned to the widget and the agent’s status is Active.
  • Check your browser’s network tab for failed API requests.
  • Ensure your website doesn’t have a Content Security Policy (CSP) blocking connections to app.roserx.health.
  • Make sure domain restrictions include your local development address (e.g. localhost:3000).
  • If you’re using a framework with hot reloading, try a full page refresh.