A web embed survey opens on your own website or web app, so visitors answer it without going to a separate survey page.
After the code is installed, you can change who sees the survey, where it appears and how often it opens, all from Simplesat.
How it works
The survey appears when the visitor and page match your rules and Frequency allows it, after the delay you set. Each answer is saved as soon as the visitor gives it, even if they don't finish the survey.
If your site passes the visitor's email address, Simplesat identifies the visitor. A matching customer ID can also identify an existing customer. Other visitors are anonymous. Whether a visitor is identified changes who sees the survey, how often it appears and whether it asks for contact details.
Install a web embed survey
You'll need the Manage surveys permission, which the Owner and Admin roles have.
Open Admin → Surveys and open the survey.
If the survey already uses another delivery method, choose Change delivery method from its three-dot menu, then Remove current delivery method.
Click Publish and choose Web-embed.
Set the sending audience, visibility, delay and frequency, then click Save.
Click Get embed code, then Copy survey code.
Paste the code into the pages where the survey should appear.
Replace the example details with each signed-in user's details. If you aren't identifying visitors, remove the example customer details.
Warning: If you leave [email protected] and Tester McTestface in the code, all visitors are treated as one customer and responses are attributed to Tester McTestface. The customer information question won't appear, and One time frequency can prevent everyone after the first visitor from seeing the survey.
If your site is a single-page app, you want the survey to open from a button, or you want to pass more customer or ticket details, your developer can follow Developer setup below.
Developer setup
This section is for whoever edits your site's code, for installs that need more than pasting the copied code as it is.
The code has two parts. The loader script adds Simplesat's survey app to your page but shows nothing on its own. The survey call, simplesat.survey({ ... }), asks Simplesat for the survey and shows it. It names the survey by its token and passes along what your site knows about the visitor. Nothing is sent to Simplesat until a survey call with a token runs.
Keep id="simplesat-web-embed" on the loader tag exactly as copied. With any other id, the survey never loads.
Install the survey in a single-page app
In a single-page app, the load event fires only once, when the app first loads, and the copied code's load listener runs with it. It doesn't run again when the visitor moves to another view. Split the code in two instead:
Put the loader script tag once in the app's main HTML page, so it loads with the app. Many frameworks don't run a
<script>tag written inside a component.Call
window.simplesat.survey({ ... })from the component or route where the survey belongs. It takes the same fields as the copied code.
A survey call made before the loader has finished loading does nothing and shows no error. When the loader is ready, it fires a survey-loaded event on its own script tag. The call only works from just after that event, which is why this code waits with setTimeout before calling:
const script = document.getElementById('simplesat-web-embed')
script.addEventListener('survey-loaded', function () {
setTimeout(function () {
window.simplesat.survey({ survey_token: 'your-survey-token' })
}, 0)
})Open the survey when someone clicks a button
To open the survey from a button or link instead of when the page loads, keep the loader tag. Then replace the load listener in the copied code with a click listener on your own element:
const myButton = document.querySelector('#my-button')
myButton.addEventListener('click', function () {
simplesat.survey({ survey_token: 'your-survey-token' })
})Your button or link needs the id that the selector looks for, which is my-button in this example.
The delay counts from the click, so with a delay of 0 the survey opens as soon as the visitor clicks. Frequency applies to clicks too, so if you want the survey to open on every click, set Frequency to Persistent.
Pass customer and ticket details to the survey
Fill these values from the signed-in user, so each response arrives with the visitor identified.
Field | What it does |
| Required. Names the survey. The copied code already has it. |
| Identifies the visitor. Creates a customer in your workspace, or updates the customer who already has that email address. The response is attributed to that customer. |
| The customer's name. |
| The customer's company. |
| Stored as the customer's external ID. Without an email address, it identifies the visitor only if it matches a customer already in your workspace, and it never creates a customer. |
| Your own customer fields, as labels with text values. Stored on the customer when the call identifies the visitor. |
| On a survey offered in several languages, the language to show the survey in, if that language is active on the survey. |
| Identifies what's being rated, such as a ticket, an order or a booking. Answers on one survey that carry the same ID belong to one response. Without an ID, each page load gets an ID of its own, so a visitor who answers on two page loads leaves two responses. |
| Your own fields about what's being rated. Stored on the response as ticket fields. |
Choose who sees the survey
To show the survey only to some visitors, add rules under Sending audience on Publish. If you don't add any, every visitor can see it.
Rules go in two groups, Meet ALL of the following rules and Meet ANY of the following rules. A visitor has to match every rule in the first group and at least one rule in the second. You can build rules on Customer name, Customer email, Customer Id, Company, Tags, Ticket Id, and the customer and ticket attributes your workspace already uses.
Customer rules use the identified visitor's customer record, including its existing tags and attributes, plus any details supplied by your site. For anonymous visitors, they can only use details supplied by your site. Ticket rules always use the details supplied with the survey.
You can view matching customers and download the list as a CSV. If your site doesn't supply a customer detail needed by a rule, use Import customers to add it.
Choose which pages the survey appears on
To keep the survey to certain pages, add Visibility rules on Publish. Without them, the survey can open on any page that carries the code.
Each rule compares Current page URL with a value you type, using is, is not, contains or does not contain, and the survey opens only where every rule passes. The page URL is the full address in the browser, including anything after ? or #, and an is rule has to match all of it exactly. If your links add tracking parameters or anchors, use contains.
When and how often the survey appears
Delay sets how many seconds to wait before showing the survey. Set it to 0 to show the survey without a delay.
You decide how often one visitor sees it with Frequency:
Setting | What happens |
One time | The visitor sees the survey once. |
Persistent | The survey shows every time the code loads. |
Ongoing: send every | The survey can appear again after the interval you choose. |
Simplesat keeps an identified visitor's views on their customer record, so the count holds on any browser or device. A visitor who leaves before the delay has passed hasn't seen the survey yet.
Anonymous visitors are tracked with a cookie in their browser that lasts a year. They'll see the survey again in another browser, or after clearing their cookies.
Collect the visitor's name and email address
If the survey call doesn't identify a visitor, the survey can ask them for a name and an email address. The settings are on Configure, under Capture customer information from anonymous surveys.
Show question if customer info isn't already associated with the answer adds a customer information question after the first question. Visitors can enter an email address, with an optional name, or choose Skip. Responses without contact details appear as Anonymous.
Require the question and hide all anonymous responses removes Skip. Responses stay hidden until the visitor provides an email address. Hidden responses don't appear in your feedback or trigger integrations, but they still count toward your monthly response allowance. Turning off the customer information question also turns off this requirement.
To collect ratings with no contact details at all, leave both settings off.
Allow file uploads from anonymous respondents, in the same block, decides whether an anonymous visitor sees a file upload question.
Connect responses to a helpdesk ticket
If you use a helpdesk, Simplesat can sync each response with it. Under Connected service on Publish, choose one of your workspace's authenticated integrations, and pass the ticket's ID in ticket.id. You set what the sync does, such as updating ticket details or adding a private note, in that integration's own settings.
Appearance and position
The survey appears along the bottom of the browser window, regardless of where you add the code. There are no position or size controls in the survey settings.
The survey uses its assigned brand's accent color and font. In the brand's Web-embed survey settings, you can change the Background color. On Pro and above, you can use Custom CSS to change the survey's position or size. This CSS applies to the whole page and can affect other elements on your website.
Only a positive rating plays a confetti animation across the page. The confirmation message closes by itself after 10 seconds, unless the visitor's pointer is on it.
Test the embed before it goes live
Add the copied code to a test page on your site or localhost. You can also save it in an .html file and open it in a browser.
While you test, set Frequency to Persistent, and set it back before you go live. Under One time, the survey stops appearing to you once you've seen it. Under Ongoing, it stops until the interval passes.
Heads up: Answers you give through the embed code are saved as real responses, attributed to whatever email address the code passes.
Preview in the survey editor checks something different. It opens the survey on the hosted survey page with a test email address and shows the questions and the confirmation message. It doesn't run the embed code, so visibility, delay, frequency and the customer information question don't apply there.
Troubleshooting
The survey isn't appearing on my site
Check these in order:
Frequency. With One time, a visitor sees the survey once. With Ongoing, they must wait for the interval you chose. To test, switch to Persistent for now, remove any fixed example email from the code, and use a fresh browser profile. Restore your usual Frequency setting afterward.
Visibility. Every rule has to pass for the current page.
Sending audience. The visitor has to match the rules.
The survey. Make sure the token in the survey call belongs to this survey and that the survey's delivery method is Web-embed. A closed or archived survey doesn't open. If Lock responses from being updated is on, the survey won't open again for a
ticket.idwhose response is locked.Delay. The survey waits the number of seconds you've set before it opens.
For your developer: Make sure the loader tag still has id="simplesat-web-embed" and the browser console shows no error. In your browser's developer tools, the request whose address ends in /web-embed/ answers "allowed": false whenever Simplesat declines to show the survey, with a plain-language reason that points to the page address, the audience rules, the delivery window (frequency), a closed survey, or a survey that isn't an active web embed. "The survey is expired" means Lock responses from being updated is on and the response for that ticket.id is locked.
I'm seeing ratings that nobody submitted
A rating is saved when the visitor clicks it, before the next question. A visitor who rates and then closes the survey leaves a rating with no comment. To keep ratings from visitors you can't identify out of your feedback, turn on Require the question and hide all anonymous responses.
I have several responses from the same customer
Without ticket.id, each page load gets an ID of its own, so every page load where the visitor answers creates a new response. Pass an ID for what's being rated.
All my responses show the same customer
The code still has [email protected] and Tester McTestface, or another fixed email address. Replace them with the signed-in user's details.
I don't see the customer information question
The question needs two things: Show question if customer info isn't already associated with the answer turned on, and an anonymous visitor. The copied code includes a test email address, and that's enough to stop the question. Take the address out of the code to see the question while you test.
My survey shows on pages it shouldn't
Visibility rules apply on every page that carries the code. If the code is in a site-wide template, add a visibility rule for the pages the survey belongs on, or move the code to just those pages.
I'm getting junk submissions on my embedded survey
A web embed survey isn't screened for spam. On a page anyone can reach without signing in, like your help center or a public page of your website, anyone who loads the page can submit a response, bots included.
Installing the survey behind a sign-in, on pages only your customers reach, cuts this down the most. Sending audience and Visibility rules narrow who sees the survey and where. Frequency only limits repeat responses from one browser, and it doesn't stop a client that doesn't keep cookies. Require the question and hide all anonymous responses hides anonymous responses rather than stopping them, and hidden responses still count toward your plan's monthly responses. You can delete responses that have already arrived from the Feedback page.
My survey worked and then stopped, and I didn't change anything
If the code has the example email or another fixed address, every visitor is the same customer, and under One time the survey opens only once in total. Replace the address with the signed-in user's details. If that's not the problem, contact us with the survey name and a page where the survey should appear.
FAQ
What's the difference between a web embed survey and a feedback widget?
A web embed survey collects new feedback from visitors to your site. A feedback widget shows feedback you've already collected.
What's the difference between a web embed and an external email embed?
A web embed survey opens in your site or app, and the visitor answers it there. An external email embed puts the survey's rating choices or a link into an email, a signature or a template, and a click opens the hosted survey page.
Do I need new code for every survey I create?
Each survey has its own token, and one survey call shows one survey, so each survey needs its own survey call. The loader script is the same for every survey.
Can I use t_ and tm_ parameters with a web embed survey?
Not as URL parameters. Ticket fields go in ticket.custom_attributes, and customer fields go in customer.custom_attributes. The survey call has no team member fields.
Can I ask for contact details only on low ratings?
No. The question comes right after the survey's first question, for every visitor it applies to.
Where do web embed responses show up?
In your feedback and reports, under the survey that collected them, just like responses from any other delivery method.
Does a web embed survey have a live or paused status?
No. It collects responses wherever the code runs. To stop it, close the survey, archive it, or remove the code from your site.