Surveys (beta)

Surveys are a great way to collect qualitative feedback from your users. Qualitative feedback enables you to gain more insight into your users' and how they view their experience with your product.

With PostHog, you can target surveys based on page URL, selectors, feature flag, and user properties. Then, you can analyze the results right in PostHog too!

Setting up surveys

Setting up surveys is easy, and there are two ways to do it. The first option will enable you to get started quickly with a pre-built survey, while the second option involves creating your own UI components.

Option 1 (recommended)

1. Make sure you've enabled the surveys app in your project's apps.

2. You must have the opt_in_site_apps option enabled in your PostHog initialization code and posthog-js version 1.67.1+ or the JavaScript snippet that includes getActiveMatchingSurveys and getSurveys.

posthog.init("<ph_project_api_key>", { 
    "api_host": "<ph_instance_address>",
    "opt_in_site_apps": true 
})

3. That's it! Now you can go create a survey in PostHog.

Option 2 (custom UI component)

1. Make sure you're up to date on PostHog's JavaScript web library. Surveys requires version 1.67.1, or later.

2. After creating your survey on PostHog app, call posthog.getSurveys() and get a list of all surveys back if you wish to do your own matching, or posthog.getActiveMatchingSurveys() to get a list of active matching surveys that should display for the current user client.

2.5. Make sure you filter for surveys that are of the type "api".

posthog.getActiveMatchingSurveys((surveys) => {
    // do something with surveys
    // handleSurveys(surveys.filter(survey => survey.type === 'api'))
})

Note: You'll need to handle whether a user has seen a survey already or not manually if you're using this option. The survey app uses localStorage to keep track of this, which you can implement similarly in your code. Note: If you're using a URL or selector targeting option, you'll need to poll with posthog.getActiveMatchingSurveys() to get the most updated survey results.

3. In order for survey responses to be recorded, you'll need to send in a "survey sent" capture call event with the survey's name, ID, and any properties you'd want.

posthog.capture("survey sent", {
    $survey_id: {survey.id} // required
    $survey_response: {survey_response} // required
    $survey_name: {survey.name} // optional
})

Surveys that are shown should be captured with a "survey shown" event and those that are dismissed, with a "survey dismissed" event similar to the above.

PostHog currently supports surveys with either a single text input, or a link to another page (such as a form, or scheduling platform), so be sure to use the syntax above in order to track results. We'll be adding more survey types soon!

Creating a survey

To create a new survey, go to the Surveys page in PostHog and click "New survey". You'll be prompted to enter a name for your survey, optional description, and what type of survey you'd like to create.

On the right side of the page, you'll see a preview of what your survey will look like, along with appearance customization options.

Survey targeting

When you create a survey, it'll save as a draft until you're ready to launch it. You can target your survey to specific users based on:

1. Page URL contains. You can target a survey to a specific page URL, or a page URL that contains a specific string. For example, you can target a survey to https://posthog.com/docs or https://posthog.com/docs/* with the string "/docs".
2. Selector. You can target a survey based on whether a specific element appears on your page with either class name or ID. For example, you can target a survey with #my-button or .my-button.
3. Linked feature flag. You can target a survey to users who have a specific feature flag enabled. For example, you're rolling out a new feature flag "new-landing-page" and want to gather feedback only from users who have that flag enabled.
4. User/group properties. You can target a survey to users who have a specific user or group property. For example, you can target a survey to users who have a property is_paying set to true.

All targeting properties behave in a "AND" manner, meaning that a survey will only be shown to a user if all of the above conditions are met.

Survey events

Survey responses are stored as PostHog events. We provide an easy way for you to view the responses on the survey page, but you can also view them in any manner you'd like with the PostHog UI.

We have "survey shown", "survey dismissed", and "survey sent" events. All three events will contain the $survey_id and $survey_name properties, and "survey sent" will also contain the $survey_response property.