Installing & configuring NPS

An overview of how to install Vitally's NPS and ensure the right users are polled at the right time

NPS Overview

About In-App NPS Surveys

Install NPS to show NPS surveys to specific users, analyze NPS scores across accounts, and set up alerts for accounts with dissatisfied users or low scores.

If you're uncertain on whether you want to use in-app NPS, email NPS, or how to use them together please watch the video at the top of this documentation NPS with Vitally.

Enabling NPS

How To	How to Visual
How to Enable in-app NPS Navigate to your Settings (⚙️) by selecting your Account Logo on the top left Under Organization Settings select NPS (or get there via Quick Jump CMD+J) Turn the toggle on to Enable Vitally’s In-App NPS surveys Continue to the Configuration steps below

Configuring NPS

How to configure NPS

How to Visual

How to configure NPS Navigate to your Settings (⚙️) by selecting your Account Logo on the top left Under Organization Settings select NPS (or get there via Quick Jump CMD+J) Select the Configuration tab Review and complete each configuration option How long (in days) must the user have had an account with your product before they are surveyed? How many sessions should a user have had with your product before they are shown the NPS survey? What is the maximum number of consecutive sessions to show the survey until the user responds? Once the survey is submitted OR last dismissed, how many months should pass before the user sees a new survey? Should a user be required to match a set of Playbook trigger rules in order for the survey to show? No - show to all users that meet the above conditions Yes - only show to users that 1) meet the above conditions and 2) are enrolled in a Playbook with a 'Show NPS Survey' action Below we dive deeper into each question to make sure you're configuring this correctly.

NPS Configuration Questions

Digging deeper into NPS Configuration	Explanation
How long (in days) must the user have had an account with your product before they are surveyed?	'Age' of the user (in days) Specify a non-zero number if you'd like to only survey users who've used your product for a minimum amount of time. Important: By default, we compare each user against the first time Vitally saw them use your product. Therefore, if you are installing Vitally for the first time and set a value of 7 here, it implies that it will be 7 days before any user is eligible to receive a survey. However, you can tell us when a user started using your product by sending a createdAt user trait when you identify the user (using the Vitally.js library). If you send us a createdAt trait, we'll use that value when determining if a user should see a survey.
How many sessions should a user have had with your product before they are shown the NPS survey?	Minimum sessions Specify a non-zero number if you'd like to only survey users who have logged a minimum number of sessions in your product. Sessions are unique per day - i.e., a user has a maximum of 1 session on any given day. Therefore, if you specify 5 here, a user must use your product over 5 unique days before becoming eligible to receive a survey. Important: Unlike the 'age' option, there's no way to tell us how many sessions a user has had with your product programmatically. If you're installing Vitally for the first time, you can specify 0 here and set the createdAt user trait documented above to start collecting NPS survey responses immediately.
What is the maximum number of consecutive sessions to show the survey until the user responds?	Consecutive sessions to show a survey How many consecutive sessions a user should be shown a survey only if the survey is dismissed in each session. If you specify a value of 3 here, that means we'll show the survey to the user for (up to) 3 consecutive sessions. If they dismiss the survey each time, then we'll stop showing the survey from their 4th session onward. Remember that sessions are unique per day. So if a user dismisses the survey at 10:00 AM on Tuesday, we won't show the user another survey until 10:00 AM on Wednesday (at the earliest).
Once the survey is submitted OR last dismissed, how many months should pass before the user sees a new survey?	'Wait time' before showing a new survey After a survey is submitted OR the user last dismisses a survey, this setting allows you to define the number of months to wait before showing another survey to that user.
Should a user be required to match a set of Playbook rules in order for the survey to show?	Only show surveys to users matching a Playbook's rules Playbooks give you the ability to perform automated actions on customers or users that meet certain conditions. By default, we'll show the NPS survey to all users that meet the configuration requirements, but you can filter that dataset even further using Playbooks. The possibilities are truly endless, but here are a few examples you may want to consider: Only show the survey to users who belong to subscribed, paying customers, excluding those on trial periods. Only show the survey to users who belong to subscribed customers who are set to renew within 2 weeks. Only show the survey to users who belong to 'Enterprise' segment customers. Read the section below to find more information: Limit audience for NPS surveys

Installing the NPS script

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 & 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 NPS is enabled.

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

Option	Valid Types	Details
productName	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	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	string	Specifies the color to use in buttons. Defaults to a purple color: #6457D
npsQuestion	string or a function that returns a string	If you provide a function, it 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	string or a function that returns a string	If you provide a function, it 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	string or a function that returns a string	If you provide a function, it 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	string or a function that returns a string	If you provide a function, it 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	string or a function that returns a string	If you provide a function, it 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	string or a function that returns a string	If you provide a function, it is given the productName as a parameter (see below). Overwrites the text display below "0"
maxLabel	string or a function that returns a string	If you provide a function, it is given the productName as a parameter (see below). Overwrites the text display below "10"
placeholderText	string or a function that returns a string	If you provide a function, it is given the productName and score as a parameter (see below). Overwrites the placeholder text in the feedback box
submitText	string or a function that returns a string	If you provide a function, it is given the productName and score as a parameter (see below). Overwrites the text of the button to submit feedback
dismissText	string or a function that returns a string	If you provide a function, it is given the productName and score as a parameter (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'
});

Step 3: Test 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: Do not ship with show - use survey in production

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.

Using Segment alongside Vitally's NPS Javascript

If you use Segment to track and send your users and accounts to other tools, Vitally provides a 'shortcut' way to reuse your Segment logic alongside our NPS Javascript.

To do so, you still need to follow most of the steps described here. However, do not worry about identifying the user and account via the Vitally.user and Vitally.account APIs. Instead, when calling Vitally.nps('survey'), in the second argument that supports additional options, specify an autoLoadSegment option and set to true.

Vitally.nps('survey', {
  productName: 'Pied Piper', 
  autoLoadSegment: true,
  delay: 1000
});

Doing this will listen for calls to Segment's analytics.identify and analytics.group APIs. When detected, the NPS survey will automatically use the user and account tracked via Segment.

Putting this all together, an entire example snippet to add to your HTML that uses Segment's user and account would look something like this:

<script type="text/javascript" src="https://cdn.vitally.io/vitally.js/v1/vitally.js" defer></script>
<script type="text/javascript">
  !function(n,t,r){for(var i=n[t]=n[t]||[],o=function(r){i[r]=i[r]||function(){for(var n=[],t=0;t<arguments.length;t++)n[t]=arguments[t];return i.push([r,n])}},u=0,c=["init","user","account","track","nps"];u<c.length;u++){o(c[u])}}(window,"Vitally");
  Vitally.init('YOUR_TOKEN_HERE');
  Vitally.nps('survey', {
    productName: 'Pied Piper', 
    autoLoadSegment: true,
    delay: 1000
  });
</script>

Limit audience for NPS surveys

In addition to setting the default configuration for your NPS Surveys above to establish a cadence, you can limit the audience of your Vitally NPS surveys to show only to specific users using a Playbook!

Step 1: Create a playbook that targets users that match your desired conditions

How to create a user playbook

How-to-Visual

Navigate to your Settings (⚙️) by selecting your Account Logo on the top left Under Customer Management, select Playbooks (or get there via Quick Jump CMD+J) Select the New Playbook button and choose a User level playbook Add playbook trigger rules to target only the desired users who should receive NPS surveys For example, let's say you only wanted to survey users where the role trait equals admin. Create a trigger rule where role is admin (see screenshot to the right) Add the Show an NPS survey action to your playbook to show matching users Vitally's NPS surveys.

Step 2: Configure your NPS settings to only show surveys to users matching playbooks

How to

How-to-visual

Navigate to your Settings (⚙️) by selecting your Account Logo on the top left Under Organization Settings, select NPS (or get there via Quick Jump CMD+J) Select the Configuration tab Scroll to the bottom section asking "Should a user be required to match a set of Playbook rules in order for the survey to show?" Choose the option "Yes - only show to users that 1) meet the above conditions and 2) are enrolled in a Playbook with a 'Show NPS Survey' action"

Email NPS (new!)

You can now send an email NPS out using Conversations, by simply embedding it into your conversations using the '/' command! You can do this in a one-off conversation or via Playbook automation. Regardless of where you start, you use the same '/' command to embed the email NPS.

🚨 The biggest thing to keep in mind is if you're creating multiple playbooks that all include an email NPS action - you could potentially send too many email NPS surveys. Be careful and ensure that all your playbooks are working together, not against each other.

A few things to keep in mind when using Email NPS if you're using in-app NPS:

• Email NPS triggered via playbooks does not respect the configuration for in-app NPS (i.e., if they meet the playbook rules we will send the email NPS regardless of when they last saw or submitted in-app NPS)

• An Email NPS response will respect your configuration of "Once the survey is submitted OR last dismissed, how many months should pass before the user sees a new survey?" (i.e., if someone responds to an email NPS survey we will reset the counter and not show them an in-app NPS message for whatever months you have set).

If you're uncertain on whether you want to use in-app NPS, email NPS, or how to use them together please watch the video at the top of this documentation NPS with Vitally.

How To	How to Visual
How to add Email NPS to an email conversation: When in a conversation, whether manually starting one or from a playbook, use a backslash '/' You'll see a dropdown of commands available. Here, select NPS Survey Once selected, the NPS survey should populate Add other text, variables, and other commands if you wish!

NPS FAQ

Q: What are the URLs needed for a Content Security Policy (CSP)?

connect-src:
  https://app.vitally.io
  
font-src:
  https://use.typekit.net

script-src:
  https://cdn.vitally.io

style-src:
  https://use.typekit.net
  https://p.typekit.net

Q: Can I customize the email NPS? A: You are not able to customize this.

Q: Can I customize the in-app NPS? A: There are a few things you can customize like the question asked. More on what you can customize here under Installing the NPS script

Q: To use the Email NPS, do I have to use the In-App NPS surveys? A: You do not! You can exclusively use the Email NPS.