SeggWat LogoSeggWat
BlogDashboard

NPS Widget

Solicit Net Promoter Score (0–10) surveys with banner, modal, or inline display and server-configured trigger rules

Overview

The NPS widget solicits a Net Promoter Score — the 0–10 "how likely are you to recommend" survey — at meaningful moments in your product. Unlike the feedback or helpful widgets, NPS is triggered, not self-serve: the widget only appears when a configured trigger fires.

Three display modes are supported:

  • Banner — bottom slide-in (default, highest response rate)
  • Modal — centered overlay with backdrop
  • Inline — mounted inside a container you specify

Trigger rules, cooldown, sample rate, and per-locale copy are configured per project in the dashboard and fetched by the widget at load time. Your customers only copy-paste the install snippet once.

Quick Start

Add the script where the widget should be available:

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-nps.js"
        data-project-key="your-project-key"
        data-mode="banner"></script>

The widget fetches trigger config from /api/v1/projects/{project_key}/nps-config. It won't appear until:

  1. enabled is true in the dashboard config, AND
  2. A trigger rule matches (URL pattern, custom event, or time-on-page), AND
  3. The visitor is past the cooldown window (default 90 days), AND
  4. The sample-rate roll passes (default 100%)

Configuration Options

Required Attributes

data-project-keystringrequired

Your unique project identifier from the SeggWat dashboard.

Optional Attributes

data-modestringdefault:"banner"

Display mode. Valid values: banner, modal, inline.

  • banner — fixed bottom slide-in, mobile-friendly, dismissible
  • modal — centered overlay with backdrop (click to dismiss)
  • inline — mounted into data-container, no backdrop

Example:

html
data-mode="modal"
data-containerstring

CSS selector for the container to mount the widget into. Only used when data-mode="inline".

Example:

html
data-container="#nps-slot"
data-product-namestring

Injected into the default question text ("recommend us" becomes "recommend <product>"). Ignored when a per-locale copy override is set in the dashboard.

data-cooldown-daysnumber

Override the server-configured cooldown. Useful for dev / QA. 0 disables the cooldown entirely.

data-languagestringdefault:"auto-detect"

Language code for the widget UI.

Supported: en, de, sv. Falls back to English if unsupported. Auto-detects from the browser when not specified.

data-show-powered-bybooleandefault:"true"

Show or hide the "Powered by SeggWat" branding in the footer. Set to false, 0, or no to hide.

data-versionstring

Track responses against specific application versions (e.g. 1.2.3, v2.0.0-beta). Stored on the linked Rating row for correlation with releases.

data-api-urlstringdefault:"auto-detect"

Override the API endpoint. Useful for self-hosted or staging environments.

Trigger Rules (configured in dashboard)

The widget evaluates three trigger kinds on boot. Any matching rule fires the prompt (logical OR). Configure them under Project Settings → NPS Widget.

URL path patterns

Glob-style patterns matched against window.location.pathname:

  • * matches any sequence within a single path segment
  • ** matches across segments
/dashboard
/billing/**
/account/*/settings

Custom event names

Names the widget listens for. Fire them from your own code after meaningful milestones:

javascript
window.SeggwatNps.trigger("onboarding_done");
window.SeggwatNps.trigger("purchase_completed");

Time-on-page

Shows the widget N seconds after page load if other conditions hold. Leave blank to disable.

Examples

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-nps.js"
        data-project-key="your-project-key"></script>
html
<script src="https://seggwat.com/static/widgets/v1/seggwat-nps.js"
        data-project-key="your-project-key"
        data-mode="modal"
        data-product-name="Acme Billing"></script>

Inline in a specific container

html
<div id="nps-slot"></div>

<script src="https://seggwat.com/static/widgets/v1/seggwat-nps.js"
        data-project-key="your-project-key"
        data-mode="inline"
        data-container="#nps-slot"></script>

Dev / QA (bypass cooldown)

html
<script src="https://seggwat.com/static/widgets/v1/seggwat-nps.js"
        data-project-key="your-project-key"
        data-cooldown-days="0"></script>

JavaScript API

The widget exposes window.SeggwatNps for programmatic control:

Identify the user

javascript
SeggwatNps.setUser("user_12345");

User IDs should be opaque — max 255 chars, alphanumeric + hyphens + underscores only. Never send PII.

Fire a custom event trigger

javascript
SeggwatNps.trigger("onboarding_done");

Dispatches a seggwat:nps:<name> event on window. If event_names in the project config matches, the widget shows (subject to cooldown + sample rate).

Show / hide manually

javascript
SeggwatNps.show();                 // respects cooldown
SeggwatNps.show({ force: true });  // bypass cooldown (dev only)
SeggwatNps.hide();

Inspect state

javascript
SeggwatNps.hasAnswered();  // boolean — inside cooldown window?
SeggwatNps.config;         // server-provided trigger config, read-only

Reset local state

Clears this visitor's cooldown / sample-roll stored in localStorage. Does not delete server-side data.

javascript
SeggwatNps.reset();

How It Works

  1. Script loads, auto-detects its base URL, bootstraps seggwat-core.js if not already present.
  2. Fetches the project's NpsTriggerConfig from GET /api/v1/projects/{project_key}/nps-config.
  3. If enabled: true, evaluates triggers (URL match, listens for event names, arms time-on-page timer).
  4. On fire: checks localStorage cooldown + caches-sticky sample-rate roll. If both pass, displays the prompt in the configured mode.
  5. User picks 0–10 → sees band-contextual follow-up ("What's missing?" / "How could we improve?" / "What did you love?") → submits or skips.
  6. Submission POSTs to /api/v1/nps/submit with score + optional comment.
  7. Server atomically writes: Rating (0–10), optional Feedback (verbatim, source: Nps), and an NpsResponse sidecar linking them.

API Endpoints

Submit a response

POST /api/v1/nps/submit

Payload:

json
{
  "project_key": "uuid",
  "score": 9,
  "comment": "Great product, smooth onboarding.",
  "path": "/dashboard",
  "version": "1.2.3",
  "submitted_by": "user_12345",
  "locale": "en"
}

Response (201 Created):

json
{
  "rating_id": "...",
  "feedback_id": "...",
  "nps_response_id": "...",
  "band": "promoter"
}

feedback_id is only present when the comment field was non-empty.

Fetch the widget config

GET /api/v1/projects/{project_key}/nps-config

Public, no auth. Returns the project's trigger rules + copy overrides so the widget can self-configure on load. Returns the default disabled config if no config has been saved.

Data Model

Each submission creates three correlated rows:

  • Rating — the 0–10 score, aggregated into NpsStats (score, promoters, passives, detractors, distribution). Same entity your other rating widgets produce, tagged with type: "nps".
  • Feedback — the free-text comment (when provided), with source: "Nps" and an auto-classified type (detractor → Bug, passive → Other, promoter → Praise). Flows through the regular feedback triage pipeline.
  • NpsResponse sidecar — links the two, denormalizes score and band for fast band-filtered queries, and carries NPS-specific fields (locale, responded_at).

This mirrors how the App Store review integration ingests data, so dashboards and the feedback triage queues look consistent across sources.

Best Practices

Use Cases

Post-Onboarding

Fire SeggwatNps.trigger("onboarding_done") after the user finishes setup. Catches strong impressions before the initial enthusiasm fades.

Post-Purchase

Trigger after a successful checkout. Links scores to revenue events for segmentation.

Feature Milestone

Fire after the user completes a meaningful workflow — their 10th report generated, their first team invite, etc.

Quarterly Pulse

Use URL patterns + a low sample rate to gently pulse-check the whole user base on the main dashboard.

Troubleshooting

Navigation