Documentation

Installation

Direct Include

<script src="https://your-domain.com/packages/script/dist/index.js"></script>

Build from Source

git clone https://github.com/your-username/simple-nps
cd simple-nps/packages/script
npm install
npm run build

The built file will be in packages/script/dist/index.js.

Configuration

Configure the script by setting window.simpleNpsConfig before calling initSimpleNps():

window.simpleNpsConfig = {
  // Google Analytics 4 Measurement ID (optional)
  gaId: "G-YOUR-MEASUREMENT-ID",

  // Internationalization settings
  i18n: {
    en: {
      intro: "How likely are you to recommend us to a friend or colleague?",
      followUp: {
        detractor: "Sorry to hear that. What could we improve?",
        passive: "Thanks for the feedback. What would make this better?",
        promoter: "Great! What do you love most about our service?"
      },
      placeholder: "Tell us more...",
      submit: "Submit",
      thankYou: "Thank you for your feedback!"
    }
  },

  // Default language (defaults to 'en')
  defaultLanguage: "en",

  // Custom styling (optional)
  customCSS: "
    .simple-nps-container {
      /* Your custom styles */
    }
  "
};

Internationalization

The script supports multiple languages. Add language objects to the i18n configuration:

window.simpleNpsConfig = {
  i18n: {
    en: {
      intro: "How likely are you to recommend us?",
      followUp: {
        detractor: "What could we improve?",
        passive: "What would make this better?",
        promoter: "What do you love most?"
      },
      placeholder: "Tell us more...",
      submit: "Submit",
      thankYou: "Thank you for your feedback!"
    },
    es: {
      intro: "¿Qué probabilidad hay de que nos recomiendes?",
      followUp: {
        detractor: "¿Qué podríamos mejorar?",
        passive: "¿Qué haría que esto fuera mejor?",
        promoter: "¿Qué es lo que más te gusta?"
      },
      placeholder: "Cuéntanos más...",
      submit: "Enviar",
      thankYou: "¡Gracias por tu comentario!"
    },
    fr: {
      intro: "Quelle est la probabilité que vous nous recommandiez?",
      followUp: {
        detractor: "Que pourrions-nous améliorer?",
        passive: "Qu'est-ce qui rendrait cela meilleur?",
        promoter: "Qu'aimez-vous le plus?"
      },
      placeholder: "Dites-nous en plus...",
      submit: "Soumettre",
      thankYou: "Merci pour vos commentaires!"
    }
  },
  defaultLanguage: "en"
};

The script will use the browser's language if available, otherwise fall back to the default language.

Analytics Integration

The script integrates with Google Analytics 4 to track NPS events:

Automatic Events

• nps_score_selected - When user selects a score (0-10)
• nps_feedback_submitted - When user submits feedback text
• nps_dismissed - When user closes the NPS

Event Parameters

// Example: nps_score_selected event
gtag('event', 'nps_score_selected', {
  'score': 9,
  'category': 'promoter', // 'detractor', 'passive', or 'promoter'
  'custom_parameter_1': 'value'
});

No GA Script Loading

The script does not load Google Analytics itself. This makes it perfect for GTM integration where analytics is already handled.

Customization

CSS Styling

The script includes default styles, but you can override them:

/* Target the container */
.Simple-nps {
  font-family: 'Your Custom Font';
  border-radius: 12px;
}

/* Style the score buttons */
.simple-nps-container .score-button {
  background-color: #your-color;
  border-radius: 8px;
}

/* Style the selected score */
.simple-nps-container .score-button.selected {
  background-color: #selected-color;
}

/* Style the feedback textarea */
.simple-nps-container .feedback-textarea {
  border: 2px solid #your-border-color;
}

Positioning

The script uses absolute positioning by default. Key CSS classes:

• .simple-nps-container - Main container
• .simple-nps-overlay - Background overlay
• .simple-nps-content - Content container
• .simple-nps-score-buttons - Score button container
• .simple-nps-score-button - Individual score buttons

API Reference

initSimpleNps()

Initializes and shows the NPS script.

// Basic usage
initSimpleNps();

// The function does not take parameters -
// use window.simpleNpsConfig for configuration

Configuration Object

Google Tag Manager Integration

Step 1: Upload the Script

Upload the built script from packages/script/dist/index.js to your website and note the URL.

Step 2: Create GTM Variables

Create variables in GTM for configuration:

• GA Measurement ID - Your Google Analytics 4 ID
• NPS Trigger Condition - When to show the script

Step 3: Create Custom HTML Tag

<script>
window.simpleNpsConfig = {
  gaId: "{{GA Measurement ID}}", // GTM variable
  i18n: {
    en: {
      intro: "How likely are you to recommend us?",
      followUp: {
        detractor: "What could we improve?",
        passive: "What would make this better?",
        promoter: "What do you love most?"
      },
      placeholder: "Tell us more...",
      submit: "Submit",
      thankYou: "Thank you for your feedback!"
    }
  }
};

// Show the NPS
initSimpleNps();
</script>

Step 4: Configure Triggers

Set up triggers based on your needs:

• Page View - Show on specific pages
• Timer - Show after user spends time on site
• Scroll Depth - Show after user scrolls
• Custom Event - Show based on user actions

Best Practices

• Don't show the NPS immediately - wait for user engagement
• Use frequency capping to avoid annoying users
• Consider mobile vs desktop display preferences
• Test thoroughly before deploying to production