Implementing custom surveys

Note: This is not required for popover surveys.

If you're using PostHog's survey API to create a custom survey UI, there are 2 steps to integrating with PostHog:

Step 1: Fetch active surveys

To fetch the surveys currently enabled for a user, call posthog.getActiveMatchingSurveys(callback, forceReload).

Alternatively, if you wish to do survey targeting yourself, you can call posthog.getSurveys(callback, forceReload) to return a list of all surveys from PostHog.

Surveys are cached by default in the posthog-js library, so you can pass true to forceReload to force a new surveys api call from PostHog.

Both methods return a callback with an array of surveys:

JSON

// Example surveys response:
[{
  "id": "your_survey_id",
  "name": "Your survey name",
  "description": "Metadata describing your survey",
  "type": "api", // can be either "api" or "popover"
  "linked_flag_key": null, //Linked feature flag key, if any.
  "targeting_flag_key": "your_survey_targeting_flag_key",
  "questions": [
    {
      "type": "single_choice",
      "choices": [
        "Yes",
        "No"
      ],
      "question": "Are you enjoying PostHog?"
    }
  ],
  "conditions": null,
  "start_date": "2023-09-19T13:10:49.505000Z",
  "end_date": null
}]

Thus you can use show your user a survey using code like this:

Web

posthog.getActiveMatchingSurveys((surveys) => {
    // Make sure you filter for surveys that are of type `"api"`. 
    // This prevents accidentally showing popover surveys to your users.
    const filteredSurveys = surveys.filter(survey => survey.type === 'api');
    if (filteredSurveys.length > 0) {
        // show the survey using your custom UI
        showSurvey(filteredSurveys[0]);
    }
})

Important: posthog.getActiveMatchingSurveys() will always return an active survey if the user meets the targeting conditions, even if they have already seen, dismissed or responded to the survey.

Note: If you're using a URL or selector targeting options, you'll need to poll posthog.getActiveMatchingSurveys() to get the most updated results.

Step 2: Capture survey events

To show survey results in PostHog, you need to capture user interactions with your surveys using the following 3 events:

Web

// 1. When a user is shown a survey
posthog.capture("survey shown", {
    $survey_id: survey.id // required
})

// 2. When a user has dismissed a survey
posthog.capture("survey dismissed", {
    $survey_id: survey.id // required
})

// 3. When a user has responded to a survey
posthog.capture("survey sent", {
    $survey_id: survey.id, // required
    $survey_response: survey_response // required. `survey_response` must be a text value.
    // Convert numbers to text e.g. 8 should be converted "8".
    // For multiple choice select surveys, `survey_response` must be an array of values with the selected choices.
    // e.g., $survey_response: ["response_1", "response_2"]
})

Multiple question surveys

If you have a survey with multiple questions, you can capture the responses to each question using the following syntax:

Web

posthog.capture("survey sent", {
    $survey_id: survey.id, // required
    $survey_response: survey_response,
    $survey_response_1: survey_response_1,
    $survey_response_2: survey_response_2
})

If you want to make the most of PostHog's automatic survey analysis and results visualizations page, you'll need to capture survey responses in the above formats.

Step 1: Fetch active surveys

Step 2: Capture survey events

Multiple question surveys

Questions?

Was this page useful?

Viewing survey results