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'
});

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