Installing Popsee

Add Popsee to your website with a single script tag. No build step required.

Quick Start

Add this script tag to your website, just before the closing </body> tag:

<script src="https://popsee.com/popsee.js" data-api-key="YOUR_API_KEY"></script>

Replace YOUR_API_KEY with the API key from your survey's Embed tab.

Understanding Your API Key

Your API key is unique to your account, not per survey.

All surveys (Popsees) in your account share the same API key. You only need to add the script once per website.

To find your embed code:

Log in to your Popsee dashboard
Click on any survey
Go to the Embed tab
Copy the complete script tag with your API key included

Your API key starts with pk_ and works for all surveys in your account.

How Multiple Surveys Work

When you have multiple active surveys, Popsee uses targeting rules to determine which one to show:

Domain Prefix check - Each survey should have a Domain Prefix set (e.g., https://mysite.com). Only surveys matching the current URL will be considered.
Targeting rules - URL patterns, device type, time on page, scroll depth, and custom parameter conditions are evaluated.
First match wins - The first survey that passes all targeting checks will be shown to the visitor.
Survey fatigue protection - If a survey was recently shown to a visitor, no other surveys will appear for 24 hours.

Always set a Domain Prefix!

Without a Domain Prefix, a survey can appear on any website using your API key. This is a common cause of the wrong survey appearing.

Custom Parameters

Pass up to 10 custom data-* attributes to track and segment responses. Use any attribute name you want - they'll all be captured and available for filtering in the dashboard.

Common Parameters

data-user-id Your internal user identifier

data-email User's email address

data-plan Subscription tier (free, pro, enterprise)

data-company Company or organization name

data-role User role (admin, member, viewer)

data-source Traffic source or campaign

data-page-type Page category (pricing, docs, checkout)

data-signed-in Whether user is logged in (true/false)

<script
  src="https://popsee.com/popsee.js"
  data-api-key="YOUR_API_KEY"
  data-user-id="user_12345"
  data-email="customer@example.com"
  data-plan="pro"
  data-company="Acme Inc"
></script>

What You Can Do With Custom Parameters

Filter responses - View responses from specific user segments
Set targeting rules - Show surveys only to users matching certain criteria
Export with data - All parameters are included in CSV exports
Webhook payloads - Parameters are sent with webhook notifications

Dynamic Parameters

If your user data is dynamic (from your backend or JavaScript), you can set the attributes programmatically:

<script>
  (function() {
    var script = document.createElement('script');
    script.src = 'https://popsee.com/popsee.js';
    script.setAttribute('data-api-key', 'YOUR_API_KEY');

    // Set dynamic parameters
    script.setAttribute('data-user-id', currentUser.id);
    script.setAttribute('data-email', currentUser.email);
    script.setAttribute('data-plan', currentUser.plan);

    document.body.appendChild(script);
  })();
</script>

Installation Options

Email Your Developer

Not technical? No problem. Just forward your embed code to your developer or web team and they'll know what to do. You can find your embed code in any survey's Embed tab.

Go to Dashboard to copy your embed code →

React / Next.js

// In your layout or _app.js
import Script from 'next/script';

export default function Layout({ children }) {
  const user = useUser(); // Your auth hook

  return (
    <>
      {children}
      <Script
        src="https://popsee.com/popsee.js"
        data-api-key="YOUR_API_KEY"
        data-user-id={user?.id}
        data-email={user?.email}
        strategy="lazyOnload"
      />
    </>
  );
}

Vue / Nuxt

// In nuxt.config.js
export default {
  head: {
    script: [
      {
        src: 'https://popsee.com/popsee.js',
        'data-api-key': 'YOUR_API_KEY',
        defer: true
      }
    ]
  }
}

// Or dynamically in a component
mounted() {
  const script = document.createElement('script');
  script.src = 'https://popsee.com/popsee.js';
  script.setAttribute('data-api-key', 'YOUR_API_KEY');
  script.setAttribute('data-user-id', this.user.id);
  document.body.appendChild(script);
}

WordPress

// Add to functions.php
function add_popsee_script() {
  ?>
  <script
    src="https://popsee.com/popsee.js"
    data-api-key="YOUR_API_KEY"
  ></script>
  <?php
}
add_action('wp_footer', 'add_popsee_script');

Google Tag Manager

You can deploy Popsee through GTM using a Custom HTML tag:

In GTM, go to Tags → New
Click Tag Configuration and choose Custom HTML
Paste the following code:

<script src="https://popsee.com/popsee.js" data-api-key="YOUR_API_KEY"></script>

Click Triggering and select All Pages (or a custom trigger)
Name your tag (e.g., "Popsee Survey Widget") and click Save
Preview your changes, then Publish when ready

Using GTM Variables for Dynamic Parameters

You can use GTM variables (like Data Layer variables) to pass user data:

<script>
  (function() {
    var script = document.createElement('script');
    script.src = 'https://popsee.com/popsee.js';
    script.setAttribute('data-api-key', 'YOUR_API_KEY');

    // Use GTM variables (replace with your variable names)
    var userId = {{User ID}};
    var userEmail = {{User Email}};
    var userPlan = {{User Plan}};

    if (userId) script.setAttribute('data-user-id', userId);
    if (userEmail) script.setAttribute('data-email', userEmail);
    if (userPlan) script.setAttribute('data-plan', userPlan);

    document.body.appendChild(script);
  })();
</script>

Note: Replace {{User ID}}, etc. with your actual GTM variable names.

Verify Installation

After adding the script, verify it's working:

Open your website in a browser
Open the browser's Developer Tools (F12 or right-click → Inspect)
Go to the Network tab and filter by "popsee"
Refresh the page - you should see the script loading
Check the Console tab for any errors

If your survey has targeting rules configured, the widget will only appear when those conditions are met.

Troubleshooting

Survey not appearing?

Check that you have an active survey in your dashboard
Verify your API key is correct
Check if targeting rules are preventing display
Clear localStorage if you've already seen the survey

Script not loading?

Ensure the script tag is before </body>
Check for Content Security Policy (CSP) restrictions
Verify your network isn't blocking the request

Style conflicts?

Popsee renders inside a Shadow DOM for style isolation. If you're still seeing conflicts, please contact support.