Install the Novella Website widget

This guide shows how to add the Novella Website widget to your site so you can collect feedback and see privacy-conscious traffic context alongside survey responses.

What You Can Do with This Widget

Once installed, the Website widget can:

  • Show feedback buttons and targeted surveys on your site
  • Compare sentiment across journey pages, campaigns, UTM parameters, and referrers
  • Record pageviews and route changes for privacy-conscious traffic context
  • Personalize surveys using respondent details you already have
  • Wait for consent before loading, if your site requires it

Before You Start

  • Make sure you have a Novella workspace with an active Website widget.
  • Copy the public workspace key from the Novella installation screen. This key is safe to use in browser code.
  • Make sure you have access to your website template or tag manager.
  • Do not place server secrets or Tinybird ingestion tokens in the snippet.

Install the Widget

  1. Copy the script below.
  2. Replace YOUR_WORKSPACE_KEY with your public Novella workspace key.
  3. Add the script once on every page where the widget should appear, either immediately before </body> or in <head> with defer.

<script defer src="https://surveys.novellahq.com/widgets/1.0/novella.js" data-workspace="YOUR_WORKSPACE_KEY"></script>

Once loaded, the script retrieves your active widget settings and evaluates their URL, trigger, priority, and frequency rules in the visitor's browser.

Add Optional Respondent Information

If your website or tag manager knows the visitor, you can pass optional personalization values:

<script defer src="https://surveys.novellahq.com/widgets/1.0/novella.js" data-workspace="YOUR_WORKSPACE_KEY" data-firstname="{{ first_name }}" data-lastname="{{ last_name }}" data-email="{{ email }}" data-company="{{ company_name }}"></script>

  • data-workspace (Required): Public key used to retrieve your active widgets.
  • data-firstname (Optional): Respondent's first name.
  • data-lastname (Optional): Respondent's last name.
  • data-email (Optional): Respondent's email address.
  • data-company (Optional): Respondent's company name.
  • data-autoload (Optional): Set to "false" to wait for consent before loading.
  • data-analytics (Optional): Set to "false" to disable website pageviews.

Personalization is included in an encrypted, short-lived widget token. It is not placed directly in the survey iframe URL or traffic event payload. Unresolved template placeholders are ignored.

If your consent manager must authorize feedback or analytics before the widget starts, set data-autoload="false":

<script defer src="https://surveys.novellahq.com/widgets/1.0/novella.js" data-workspace="YOUR_WORKSPACE_KEY" data-autoload="false"></script> <script> function onNovellaConsentGranted() { window.NovellaWebsiteWidget?.load(); } </script>

Call load() once consent is granted. No widget configuration or Novella website pageview is sent before that call.

Show Surveys Without Website Pageviews

To keep feedback surveys enabled while disabling Novella's lightweight website analytics, set data-analytics="false":

<script defer src="https://surveys.novellahq.com/widgets/1.0/novella.js" data-workspace="YOUR_WORKSPACE_KEY" data-analytics="false"></script>

Survey interaction events are still recorded after a respondent opens a survey.

What Traffic Information Is Collected

When website analytics is enabled, the runtime records an initial pageview and distinct client-side route changes. Novella stores:

  • A page URL without its query string or fragment
  • An origin-only referrer
  • Allowlisted UTM campaign fields
  • The type of a recognized advertising click ID, but not its value
  • Pseudonymous visitor, session, and event identifiers
  • The workspace and widget associated with the pageview

When a visitor submits feedback, Novella can relate that sentiment to the page, referrer, and campaign context using shared visitor and session identifiers. Novella does not use IP addresses or user-agent strings to join traffic to survey sentiment.

Content Security Policy

If your site uses Content Security Policy, merge these sources into your existing directives:

script-src https://surveys.novellahq.com/widgets/1.0/novella.js

connect-src https://surveys.novellahq.com/api/widgets/

frame-src https://surveys.novellahq.com

Do not replace your complete CSP with this example. Your existing application will likely require additional sources.

Single-Page Applications

The widget detects navigation through history.pushState, history.replaceState, and browser back/forward navigation. It re-evaluates URL rules and records each distinct SPA URL once during the current page runtime.

If your application changes content without updating browser history, call:

window.NovellaWebsiteWidget?.refresh();

Verify the Installation

  1. Open a page that matches an active widget's URL rules.
  2. In browser developer tools, confirm that novella.js loads successfully.
  3. Confirm that /api/widgets/config returns a successful response.
  4. If website analytics is enabled, confirm that /api/widgets/track returns a successful response.
  5. Open the feedback button and submit a test response.
  6. Verify the response and its page, campaign, and referrer context in Novella.

Test consent-controlled installations both before and after consent is granted.

Troubleshooting

The widget does not appear

  • Confirm data-workspace contains the correct public workspace key.
  • Confirm the widget is active and its URL rules match the complete page URL.
  • Check its dismissal, impression, and completion-frequency rules.
  • Confirm the current HTTPS hostname matches the customer's configured primary domain or one of its subdomains.
  • Look for CSP errors blocking the script, API, or frame.

Configuration returns 403

The current origin is not authorized for the workspace, or the customer does not have a valid primary domain. Use HTTPS and verify the domain in Novella.

The button appears, but the survey does not open

Check whether frame-src permits https://surveys.novellahq.com. Widget frames use a dedicated, token-protected embed endpoint rather than the public standalone survey URL.

Pageviews are missing

  • Confirm data-analytics is not set to "false".
  • If data-autoload="false", confirm your consent callback calls load().
  • Check whether /api/widgets/track is blocked by CSP, an extension, or a network privacy tool.
  • Confirm the Tinybird website_events datasource and server-side ingestion credentials are configured.

Personalization is missing

Inspect the rendered script element, not the unprocessed template, to verify that your application or tag manager resolved the personalization placeholders. Empty, invalid, and unresolved values are intentionally discarded.

Updating or Removing the Widget

Widget presentation, survey selection, triggers, URL rules, and frequency are managed in Novella and normally do not require snippet changes. To remove the widget and website analytics entirely, remove the script element from your site or tag manager.

Made with ProductLift
© 2026 Novella - Every customer has a story Status Privacy policy Terms of service Contact us Blog