Creating and Configuring a Widget Survey

Build a survey that appears directly on your website, targeted and triggered by rules you control.

Who this is for: Developers, Admins, Product and CX teams running in-context feedback programs

Overview

A widget survey shows itself in-page on your website — as a side drawer, a centered overlay, or a corner card — instead of being emailed or shared as a link. It's powered by a website installation (the snippet connecting Unwrap to your site) and targeted entirely from its own Audience tab, where you configure when it appears (When), who it appears to (Who), and how it looks and how often (How).

Like every Unwrap survey, responses flow back into your Unwrap data layer and are analyzed alongside your other feedback once the survey is connected to a View.

Prerequisites

• An active Unwrap account with admin or survey admin access

• A website installation already set up, with its snippet live on your site — most organizations only need one

• At least one View set up in your organization, if you want responses analyzed alongside your other feedback

How It Works

Unwrap evaluates your Audience tab live, in the visitor's browser, using the installation's snippet. A widget survey needs at least one When trigger before it can go active; Who is optional (narrows the audience, or leave empty to reach everyone who matches); How controls its appearance and frequency. If more than one live widget survey on the same installation could match a visitor, Unwrap resolves the conflict for you — see Website Installations → How competing surveys are resolved.

Getting Started

Step 1: Create the survey

1. Navigate to Surveys from the left navigation and click Create New Survey.

2. Enter a survey name (internal only) and an optional description, then click Create.

Step 2: Add your questions

1. On the Settings tab, add your questions: Rating (1–10), Open-Ended Text, Single Choice, Multiple Choice, Yes/No, or Matrix Table.

2. Toggle Allow AI Follow Up on open-text questions. This matters even more for widget surveys than email — a visitor interrupted mid-browse responds better to one or two questions than a long form, and follow-ups only fire when a response needs more depth.

3. Reorder or delete questions using the drag handle or up/down arrows.

4. Personalize question text with {parameter_name} syntax, matched to a key you've pushed with UnwrapSurveyWidget.setAttributes(). See Website Installations → Widget JavaScript API reference.

Step 3: Design the respondent experience

Click the Design tab. Unlike email or URL surveys, this tab's options depend on what you pick in Step 4's How section — a side drawer, centered overlay, and corner card each have their own layout considerations. See Survey Design Page.

Step 4: Configure the Audience tab

Open the survey's Audience tab:

• When — choose a trigger: Page viewed (with URL match and timing), Element clicked (CSS selector), or Custom event (UnwrapSurveyWidget.track('event_name')).

• Who — optionally narrow the audience with conditions on metadata, query parameters, cookies, or other visitor signals.

• How — choose the appearance (side drawer, centered overlay, or corner card), an optional sampling rate, and whether to wait for repeat visits.

• If your organization has more than one installation, choose which one this survey belongs to.

See The Audience Tab: When, Who & How for the full reference.

Step 5: Connect your survey to a View

Connect from the survey's Recipients-equivalent flow, or from the View's Integrations tab. See Adding Surveys to Views.

Step 6: Activate

Toggle the survey to Active on the Settings tab. It becomes eligible to show as soon as a visitor matches its Audience tab configuration — there's no email queue and nothing further to deploy.

Configuration Options

There's no subject line, test email, or recipient list for a widget survey — those concepts are specific to email delivery.

Best Practices

• Keep it to one or two questions. A widget survey interrupts the visitor's flow; let AI follow-ups add depth instead of adding more questions.

• Anchor When to a specific moment rather than every page, unless you're intentionally building a general, sitewide fallback survey.

• Preview the design for each How option you plan to use — a side drawer, centered overlay, and corner card render differently, and the Design tab reflects whichever one you've picked.

• Give each brand or property its own installation if they have separate websites, so branding, targeting, and responses stay cleanly separated.

• Test with GTM Preview (or a test cookie/query parameter) before setting the survey Active.

Limitations

• The widget is web-only; there's no native mobile SDK yet.

• A widget survey needs at least one When trigger before you can activate it.

• A dismissal is stored in session storage, so it persists for that browser session (surviving navigation and refreshes) but resets in a new tab or window.

• There's no protection against the same visitor submitting a response more than once — unlike email surveys, there's no per-recipient link to enforce a single submission.

FAQ

Q: Do I need a separate widget survey for every page or moment I want feedback on? A: Yes, generally — create one widget survey per use case, each with its own Audience tab, rather than trying to make a single survey cover multiple unrelated triggers.

Q: Can I show this same survey on more than one website? A: A widget survey belongs to one installation at a time. If you need it on a second website, create a separate installation and a corresponding survey there — see Website Installations.

Q: How is this different from a URL survey? A: A widget survey appears automatically in-page based on targeting rules you configure; a URL survey is a link you distribute yourself, with nothing embedded on your site. See Creating and Configuring a URL Survey.