Auto-Prompt

Auto-prompt automatically opens the review bottom sheet after a user has visited your app across multiple sessions. No button click or custom trigger code required — the widget opens itself when the time is right.

How It Works

The widget counts distinct sessions (visits separated by 30+ minutes of inactivity)
After the configured threshold (default: 3 sessions), the widget opens automatically
It waits until the page has been visible for 5 seconds to avoid accidental triggers
The bottom sheet slides up with stars visible — no intermediate "Would you like to review?" popup

The user sees the star rating immediately. One tap and they're in the flow.

Default Behavior (Zero Config)

Auto-prompt is enabled by default. If you just load the script and call init(), it works automatically:

<script src="https://cdn.thewebratings.com/twr.min.js"></script>
<script>
  TheWebRatings.init({ apiKey: 'your-api-key' });
  // Auto-prompt fires after 3 sessions — no additional code needed
</script>

Initialize in authenticated pages only

Because auto-prompt is enabled by default, initializing the widget on public pages will show the review prompt to anonymous visitors. Always initialize the widget in your authenticated area (dashboard, member portal, admin panel) where users are logged in. See Quick Install for setup guidance.

Behavior	Default
Enabled	`true`
Session threshold	3 sessions
Visibility delay	5 seconds
Max dismissals before permanent stop	3

Configuration

Customize auto-prompt behavior via the autoPrompt option in init():

TheWebRatings.init({
  apiKey: 'your-api-key',
  autoPrompt: {
    enabled: true,       // Set to false to disable auto-prompt entirely
    sessions: 5,         // Number of sessions before first prompt (default: 3)
    delay: 10,           // Seconds of page visibility before trigger (default: 5)
    maxDismissals: 2     // Dismissals before permanent stop (default: 3)
  }
});

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Toggle auto-prompt on/off
`sessions`	`number`	`3`	Session threshold before first prompt
`delay`	`number`	`5`	Seconds the page must be visible before triggering
`maxDismissals`	`number`	`3`	After this many dismissals, auto-prompt stops permanently

To disable auto-prompt entirely:

TheWebRatings.init({
  apiKey: 'your-api-key',
  autoPrompt: { enabled: false }
});

Session Counting

A "session" is a distinct visit separated by at least 30 minutes of inactivity. This mirrors the standard analytics session definition and prevents a single long browsing session from inflating the count.

On every page load:

Read the stored session state from localStorage
If more than 30 minutes since last seen, increment the session counter
Update the timestamp
Evaluate trigger rules

Trigger Rules

Auto-prompt fires when all of these conditions are true:

sessions >= threshold (default 3)
User has not already submitted a review
User has not dismissed within the current backoff window
Page has been visible for the configured delay (default 5 seconds)
No other bottom sheet or modal is currently open
Auto-prompt hasn't already fired this page load

Backoff on Dismissal

When a user dismisses the auto-prompted widget, the system backs off before trying again:

Dismiss count	Next prompt after
1	4 more sessions
2	8 more sessions
3+	Never auto-prompts again

What counts as dismissal

Tapping the close (X) button
Tapping the backdrop overlay
Dragging the sheet down to close

What does NOT count as dismissal

Starting the review flow (tapping a star) then abandoning
Completing a review (sets reviewed = true instead, permanently stops auto-prompt)

Interaction with Manual `.open()`

Auto-prompt and manual .open() are fully independent:

Calling .open() manually does not affect session count or prompt state
Closing a manually-opened widget does not count as a dismissal
.open() works even if the user has permanently opted out of auto-prompt

You can always have a "Leave a Review" button in your UI alongside auto-prompt.

User Identification

When auto-prompt fires, the widget opens without pre-filled email/name. If the widget can auto-detect the user (from forms, localStorage, cookies, globals, or URL params), it uses that data. Otherwise, the user is asked to enter their email during the review flow.

Events

Auto-prompt emits an event when the user dismisses the auto-prompted widget:

TheWebRatings.on('auto-prompt:dismissed', (data) => {
  console.log('User dismissed auto-prompt');
});

Debug Helpers

When debug: true is set, the widget logs auto-prompt activity to the console. You can also inspect and reset state programmatically:

// View current auto-prompt state
TheWebRatings.getAutoPromptState();
// → { v: 1, sessions: 3, lastSeen: 1711900800000, prompted: false, dismissed: false, reviewed: false, dismissCount: 0, dismissedAtSession: null }

// Reset auto-prompt state (useful for testing)
TheWebRatings.resetAutoPromptState();

Edge Cases

localStorage unavailable (private browsing, strict privacy settings): Auto-prompt silently disables. Manual .open() still works.
User clears localStorage: Session count resets. User gets re-prompted after the threshold number of fresh sessions.
Multiple widgets on the same page: Each uses its own storage key. Only one auto-prompt fires per page load — the first to evaluate. Others detect the open overlay and defer.

Auto-Prompt

On this page