Initial setup

There are two ways to set up surveys:

1. Get started quickly with a pre-built survey
2. Create your own UI components

Option 1 (recommended): Pre-built survey

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 components

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!