Embedding UserSound

Anonymous vs logged-in users

UserSound gives you the option to pass additional information about your customers to track their activity across multiple UserSound sessions.

Identifying users

If you have a logged-in experience, you can identify respondents so UserSound can track their behaviour across multiple surveys and tie responses together in your dashboard and in your own analysis tools.

A respondent is identified when UserSound receives either a user ID (user_id) or an email address. You do not need both — one is enough.

For direct survey links, append query parameters to the URL — see Identifying respondents via link.

For embeds and in-app experiences, add a context object to your script to pass identification fields.

Pass user_id in context to identify logged-in users in an embedded survey.
email, user_name, first_name, and last_name are optional fields you can pass alongside an identifier.
If neither a user ID nor an email is provided, the respondent is treated as anonymous.

You can view all responses from an identified user by clicking View profile on the project dashboard. From the profile view you can see all responses that user has submitted across multiple UserSounds.

Completed states

Identified users can only complete one UserSound per project to prevent them from answering the same survey repeatedly.

Widget behaviour on completion

Once an identified user has completed a UserSound, the next time they refresh the page the widget will no longer appear.

Custom button behaviour on completion

If you have a custom button embed and a user clicks the button who has already completed the survey (survey status = complete), they will see the completed survey state screen.

JavaScript



<script src="https://cdn.jsdelivr.net/npm/@usersound/usersound-sdk/dist/usersound.browser.min.js"></script>

<script>
  UserSound.init({
    baseUrl: "https://usersound.com",
    projectId: "your-project-uuid", // IMPORTANT: replace with your actual project ID
    context: {
      user_id: "user.id", // IMPORTANT: replace with your user ID variable
      email: "user.email",
      user_name: "user.user_name",
      first_name: "user.first_name",
      last_name: "user.last_name",
    },
  });

  UserSound.create({});
</script>

Anonymous users

You can use UserSound on a website or app that does not have logged-in users. Simply remove or leave the additional context fields empty.

Completed states

When an anonymous user completes a UserSound survey, their local storage is updated on their device to say they have completed this UserSound before.

Widget behaviour on completion

When the user refreshes the page they will no longer see the widget.

Custom button behaviour on completion

Similarly to the logged-in experience, if you want to hide the UserSound success state on subsequent sessions, you will need to check against their local storage to see if they are in a complete state for that UserSound.

Note: if a user clears their local storage or uses a different device, the survey will be reset.

JavaScript



<script src="https://cdn.jsdelivr.net/npm/@usersound/usersound-sdk/dist/usersound.browser.min.js"></script>

<script>
  UserSound.init({
    baseUrl: "https://usersound.com",
    projectId: "your-project-uuid", // IMPORTANT: replace with your actual project ID
  });

  UserSound.create({});
</script>

UserSound states

There are three states a UserSound respondent can be in. These states can be checked from the UserSound dashboard.

State	Description
`draft`	A user has begun a session with UserSound but has not sent any messages.
`in_process`	A user has sent at least one voice or text message to UserSound, but has not completed all questions.
`complete`	A user has answered all of the questions and UserSound has closed the interview.

Embedding design

UserSound has pre-set customisations for how you can embed your survey.

Go to your project
Click Setup
Open Embed settings (currently labelled Widget settings in the dashboard)
Select how you want to display your UserSound (widget, custom button, and more)

If you have installed the quickstart snippet you don't need to make any changes to deploy a change—simply customise from the project settings section in the UserSound dashboard.

The default embedded option is the floating widget. You can see the configuration options in the setup dashboard such as:

Widget color
Placement (bottom left, bottom right)
Pop-up message
Widget icon

Turning off the widget

Go to your project dashboard
Click Unpublish

This will hide anywhere your widget is embedded.

Custom CSS overrides (coming soon)

Adding your own custom CSS styling to the widget is coming soon.

Custom button

You can initiate a UserSound survey with your own custom elements.

Go to your project
Click Setup
Open Embed settings (currently labelled Widget settings in the dashboard)
Select Custom button

In your code, create the custom element your user will engage with, then update your snippet to attach UserSound to that element (see the examples on the right).

We wrap the init method with a function to ensure all other content on the page is loaded before identifying your custom button element. Clicking the button will now open a full-screen survey popup on desktop and mobile.

Turning off the custom button UserSound

Go to your project dashboard
Click Unpublish

Users who click the custom button will now see the unpublished screen for your survey. If you don't want them to see this screen, you will need to show or hide your custom button based on the published_status.

HTML



<button id="feedback-btn">Complete survey</button>