Programmatic API

Overview

The Popsee widget exposes a global window.Popsee object that allows you to show and hide surveys programmatically. This is useful when you want to:

• Trigger a survey after a specific user action (button click, form submission, etc.)
• Show a survey in response to a custom event in your app
• Build custom triggering logic beyond the built-in targeting rules
• Create demo or preview experiences

API Reference

Survey Object Structure

The survey object passed to Popsee.show() should have the following structure:

{
  id: 'survey-123',           // Unique identifier
  name: 'Customer Feedback',  // Survey name (for your reference)
  status: 'active',           // Survey status
  settings: {},               // Optional settings object
  targeting: {},              // Optional targeting rules (ignored when using show())
  questions: [
    {
      id: 'q1',
      type: 'multiple_choice',
      text: 'How did you hear about us?',
      options: [
        { id: 'opt1', text: 'Search engine' },
        { id: 'opt2', text: 'Social media' },
        { id: 'opt3', text: 'Friend referral' },
        { id: 'opt4', text: 'Other' }
      ]
    },
    {
      id: 'q2',
      type: 'text',
      text: 'Any additional feedback?'
    }
  ]
}

Question Types

Popsee supports several question types:

{
  id: 'q1',
  type: 'multiple_choice',
  text: 'What is your role?',
  options: [
    { id: 'opt1', text: 'Developer' },
    { id: 'opt2', text: 'Designer' },
    { id: 'opt3', text: 'Product Manager' }
  ]
}

{
  id: 'q2',
  type: 'text',
  text: 'What feature would you like to see next?'
}

{
  id: 'q3',
  type: 'nps',
  text: 'How likely are you to recommend us?'
}

{
  id: 'q4',
  type: 'yes_no',
  text: 'Did you find what you were looking for?'
}

{
  id: 'q5',
  type: 'rating',
  text: 'Rate your experience',
  settings: { maxRating: 5 }
}

Usage Examples

// Show a simple survey
window.Popsee.show({
  id: 'feedback-survey',
  name: 'Quick Feedback',
  status: 'active',
  settings: {},
  targeting: {},
  questions: [
    {
      id: 'q1',
      type: 'nps',
      text: 'How likely are you to recommend us to a friend?'
    }
  ]
});

<button id="feedback-btn">Give Feedback</button>

<script>
  document.getElementById('feedback-btn').addEventListener('click', function() {
    window.Popsee.show({
      id: 'button-survey',
      name: 'Feedback Survey',
      status: 'active',
      settings: {},
      targeting: {},
      questions: [
        {
          id: 'q1',
          type: 'text',
          text: 'What can we improve?'
        }
      ]
    });
  });
</script>

// Show survey after successful checkout
async function handleCheckout() {
  const result = await processPayment();

  if (result.success) {
    // Show post-purchase survey
    window.Popsee.show({
      id: 'post-purchase',
      name: 'Post-Purchase Survey',
      status: 'active',
      settings: {},
      targeting: {},
      questions: [
        {
          id: 'q1',
          type: 'rating',
          text: 'How was your checkout experience?',
          settings: { maxRating: 5 }
        },
        {
          id: 'q2',
          type: 'text',
          text: 'Any suggestions for improvement?'
        }
      ]
    });
  }
}

// Hide the survey after 30 seconds if not completed
setTimeout(function() {
  window.Popsee.hide();
}, 30000);

// Or hide when user navigates away (SPA)
router.on('routeChange', function() {
  window.Popsee.hide();
});

Waiting for the Script to Load

If you need to call the API immediately after page load, make sure the Popsee script has loaded first:

// Option 1: Check if Popsee exists
function showSurvey() {
  if (window.Popsee) {
    window.Popsee.show(surveyConfig);
  } else {
    // Retry after a short delay
    setTimeout(showSurvey, 100);
  }
}

// Option 2: Use the script's onload event
const script = document.createElement('script');
script.src = 'https://popsee.com/popsee.js';
script.setAttribute('data-api-key', 'YOUR_API_KEY');
script.onload = function() {
  // Popsee is now available
  window.Popsee.show(surveyConfig);
};
document.body.appendChild(script);