Quick Install

Get your first rating widget up and running in 2 steps. No build tools, no npm packages — just copy, paste, and go.

The widget auto-prompts users to leave a review after 3 visits. No trigger code needed.

Initialize only for logged-in users

The widget collects reviews from authenticated users. Do not initialize it in your public HTML, root layout, or landing pages — this will cause the auto-prompt to show on your public website to anonymous visitors.

Instead, initialize the widget inside your authenticated area — such as a dashboard layout, member portal, or admin panel — where you know the user is logged in.

Step 1: Add the Script Tag

Add this single line to your authenticated layout (e.g., dashboard HTML, member area template):

<script src="https://cdn.thewebratings.com/twr.min.js"></script>

Step 2: Initialize

Add your API key and initialize the widget inside your authenticated area. Get your FREE API key (takes 2 minutes).

<script>
  (function () {
    if (!window.TheWebRatings || typeof TheWebRatings.init !== 'function') {
      console.error('TheWebRatings script not loaded.');
      return;
    }

    TheWebRatings.init({
      apiKey: 'your-api-key-here'
    });
  })();
</script>

That's it. The widget will automatically prompt logged-in users to leave a review after they've visited your app 3 times. No buttons, no trigger code, no additional setup.

How Auto-Prompt Works

After init(), the widget silently tracks user sessions in localStorage. Once a user crosses the session threshold, the review bottom sheet slides up automatically — stars visible, ready to tap.

What happens	Detail
Session counting	A "session" = a visit separated by 30+ minutes of inactivity
Default threshold	3 sessions before first prompt
Visibility delay	Waits 5 seconds of active page visibility before triggering
Smart backoff	If dismissed: waits 4 more sessions. Dismissed again: 8 more. Third dismissal: stops permanently
Review complete	Once a user submits a review, auto-prompt never fires again for that user
No stacking	Won't open if another modal/sheet is already visible
Independent of `.open()`	Manual triggers and auto-prompt don't interfere with each other

The user sees the star rating immediately — no "Would you like to leave a review?" gate. The stars are the prompt.

Configure or Disable

TheWebRatings.init({
  apiKey: 'your-api-key',
  autoPrompt: {
    enabled: true,       // set false to disable entirely
    sessions: 5,         // sessions before first prompt (default: 3)
    delay: 10,           // seconds of page visibility (default: 5)
    maxDismissals: 2     // permanent stop after N dismissals (default: 3)
  }
});

See the full Auto-Prompt guide for details on backoff logic, events, and debug helpers.

Optional: Add a Manual Trigger Button

If you also want a button users can click anytime, add open():

<button onclick="TheWebRatings.open('[email protected]', 'John Doe')">
  Leave a Review
</button>

Manual triggers never affect auto-prompt state — calling .open() won't reset the session counter or count as a dismissal.

Complete Working Example

This example represents an authenticated page (e.g., your dashboard or member area) — not a public landing page:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Dashboard - My App</title>
  <script src="https://cdn.thewebratings.com/twr.min.js"></script>
</head>
<body>
  <h1>Welcome back, John!</h1>

  <!-- Optional: manual trigger button -->
  <button onclick="TheWebRatings.open('[email protected]', 'John Doe')">
    Leave a Review
  </button>

  <script>
    (function () {
      if (!window.TheWebRatings || typeof TheWebRatings.init !== 'function') {
        console.error('TheWebRatings script not loaded.');
        return;
      }

      TheWebRatings.init({
        apiKey: 'your-api-key-here',
        debug: true  // Optional: shows helpful console logs
      });

      // Auto-prompt is already active — after 3 sessions,
      // the review widget will open automatically for logged-in users.
    })();
  </script>
</body>
</html>

Whether auto-prompted or manually triggered, the flow is the same:

Bottom sheet slides up and checks for an existing review
User selects a star rating (1-5 stars) — advances automatically
User enters a nickname and writes a review (20-1000 characters)
Widget verifies the user (sends OTP to email if first time)
Rating is submitted to your dashboard
Success screen shown inside the widget

All of this is handled by the widget — no additional code needed.

User Identification

When you call open(email, name), the user is identified explicitly. When auto-prompt fires without a prior open() call, the widget tries to auto-detect the user from:

HTML forms (email/name inputs on the page)
localStorage (common keys like user, userData, auth)
Cookies (user_email, auth_email)
Global variables (window.user, window.currentUser)
URL parameters (?email=...)

If no user is detected, the widget asks for their email during the review flow.

Anonymous reviews are not allowed — this prevents spam and ensures authentic reviews.

Next Steps

Complete First Rating Guide - Full walkthrough from dashboard to first rating
Auto-Prompt - Deep dive into session tracking, backoff, events, and debug tools
Event Handlers - Listen to submission success, track analytics
Configuration Options - Customize colors, features, and auto-prompt
Framework Integration - React, Vue, Next.js, and more

Troubleshooting

Widget doesn't appear?

Check browser console for errors
Verify TheWebRatings is defined (not undefined)
Confirm your API key is correct

"Invalid API key" error?

Double-check your API key from the dashboard
Make sure there are no extra spaces or quotes

OTP email not received?

Check spam folder
Verify email address is correct
Wait 60 seconds for retry option

Need more help? Email [email protected]