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 pass down their user ID to identify the user. This is useful because it lets you track their behaviour over multiple different UserSound surveys and also for your own analysis when using tools outside of UserSound.

Add an additional context object to your script to identify the user.

If the user_id field is left empty, the user will be treated as anonymous and all other optional context will be discarded.
email, user_name, first_name, and last_name are all optional context fields that you can pass in alongside a user ID.

You can view all responses of an identified user by clicking on View profile on the project dashboard. From there you can see all of the responses that user has had 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>