NPS surveys are potentially shown to your users once you install Vitally.js, our Javascript library. Here's how to do just that!

Step 1: Install the Javascript snippet and identify the logged-in user + account

Step-by-step details on how to install our Javascript snippet and use the Javascript API to identify each user & account can be found here as well as in the NPS configuration page in your account.

Best practices when using Vitally.js for NPS

  • Identify the date the user started an account with your product via the createdAt trait. If you send us this trait, we'll use it when determining if a user is 'old' enough to see an NPS survey (see the configuration options for more details).
  • You should call Vitally.user and Vitally.account in each session, but you only need to do so once. If you have already installed Vitally.js to track your users and their product usage, you do not need to do so again for NPS.
  • You can only use Vitally.track on paid plans - Vitally.track is an API that allows you to track interactions a user has with your product. It is only supported on paid plans with access to product analytics. If you try to use it on our "Free NPS" plan, we will discard your tracks.

Step 2: Collect NPS feedback from users

Once you've installed Vitally.js and have identified the logged-in user and account, call Vitally.nps('survey') to potentially show the survey to the logged-in user. The survey will only be shown if the user matches the criteria of your configuration while the add-on is enabled.

Vitally.nps('survey') also optionally takes a second argument of options that lets you further customize the survey displayed to users.

  • productName
    • Valid types: string 
    • When specified and you do not overwrite our default question, we'll inject this value into the question "👋 there! Quick question - how likely are you to recommend {productName} to others?"
  • delay 
    • Valid types: number
    • Specifies the amount of time in milliseconds we'll wait to show a survey to a user that should see it. This defaults to 5000ms (5 seconds). Increase or decrease based on the initial app experience your users have.
  • primaryColor 
    • Valid types: string
    • Specifies the color to use in buttons. Defaults to a purple color: #6457DC
  • npsQuestion 
    • Valid types: string OR a function that returns a string. Function is given the productName as a parameter (see below).
    • Overwrites our default question: "👋 there! Quick question - how likely are you to recommend {productName} to others?"
  • followUpTitle 
    • Valid types: string OR a function that returns a string. Function is given the productName and score as a parameter (see below).
    • Overwrites the title displayed to users after they submit a score. Defaults to "Thank you for your feedback 🙏"
  • followUpSubtitle 
    • Valid types: string OR a function that returns a string. Function is given the productName and score as a parameter (see below).
    • Overwrites the sentence displayed below followUpTitle. Defaults to "Mind letting us know why you chose a {score}?"
  • thanksTitle 
    • Valid types: string OR a function that returns a string. Function is given the productName, score, and feedback as a parameter (see below).
    • Overwrites the title displayed to users that submit text feedback. Defaults to the succinct "Thanks!"
  • thanksSubtitle 
    • Valid types: string OR a function that returns a string. Function is given the productName, score, and feedback as a parameter (see below).
    • Overwrites the sentence displayed below thanksTitle. Defaults to "We sincerely appreciate your feedback."
  • minLabel
    • Valid types: string Or a function that returns a string. Function is given the productName as a parameter (see below).
    • Overwrites the text display below "0"
  • maxLabel
    • Valid types: string Or a function that returns a string. Function is given the productName as a parameter (see below).
    • Overwrites the text display below "10"
  • placeholderText
    • Valid types: string Or a function that returns a string. Function is given the productName and score as parameters (see below).
    • Overwrites the placeholder text in the feedback box
  • submitText
    • Valid types: string Or a function that returns a string. Function is given the productName and score as parameters (see below).
    • Overwrites the text of the button to submit feedback
  • dismissText
    • Valid types: string Or a function that returns a string. Function is given the productName and score as parameters (see below).
    • Overwrites the text of the button to dismiss the feedback modal

Putting this all together, if you want to overwrite all options (with static strings), you'd make an API call like this:

Vitally.nps('survey', {
  productName: 'Pied Piper', 
  delay: 1000,
  primaryColor: '#000000',
  npsQuestion: 'Hey yo! You like Pied Piper?',
  followUpTitle: 'Solid feedback my dude!',
  followUpSubtitle: 'Mind elaborating a bit though?',
  thanksTitle: 'You are amazing!',
  thanksSubtitle: 'Bye for now'
});

For more advanced configuration, you can specify functions for arguments and dynamically change the copy users see based on their feedback:

Vitally.nps('survey', {
  productName: 'Pied Piper', 
  delay: 1000,
  primaryColor: '#000000',
  npsQuestion: ({ productName }) => `Hey yo! You like ${productName}?`,
  followUpTitle: ({ productName, score }) => {
    return score < 7 ? `Oh no! What can we do better?`: `Solid feedback my dude!`;
  },
  followUpSubtitle: ({ productName, score }) => {
    return score < 7 ? `How can we get that score up?`: `Mind elaborating a bit though?`;
  },
  thanksTitle: ({ productName, score, feedback }) => {
    return score < 7 ? `Thanks. We'll do better - promise!`: `You are amazing!`;
  },
  thanksSubtitle: ({ productName, score, feedback }) => {
    return score < 7 ? `Until next time.`: `Bye for now.`;
  },
  minLabel: 'No chance',
  maxLabel: 'Definitely!',
  placeholderText: ({ productName, score }) => {
    return score <= 7 ? 'I wish it could...' : 'I love it because...';
  },
  submitText: 'Submit my response',
  dismissText: 'Let me get back to work'
});

Testing the survey
Since Vitally.nps('survey') obeys your NPS configuration, testing the survey display could get a bit annoying. To force display the survey, replace survey with show.

Vitally.nps('show', {
  productName: 'Pied Piper', 
  delay: 0
});

Important: Don't ship with show though - use survey in production. Otherwise, you'll be annoying your users a good bit :)

show still sends submitted responses to your Vitally account though. If you'd rather that not happen (i.e. you only want to see what the survey experience is like), replace show with test.

Vitally.nps('test', {
  productName: 'Pied Piper', 
  delay: 0
});

To summarize:

  • Vitally.nps('survey') - Displays a survey to users only if your configuration says we should. Use this in production.
  • Vitally.nps('show') - Force displays a survey to users and skips your configuration. Do not use this in production. Only use if you want to test the survey experience AND see the response display in your Vitally account.
  • Vitally.nps('test') - Force displays a survey to users and skips your configuration. Do not use this in production. Only use if you want to test the survey experience WITHOUT seeing the response in your Vitally account.