The Web Ratings
Getting Started

Your First Rating

Complete walkthrough from zero to first rating in 15 minutes

This guide walks you through everything—from signing up to seeing your first rating in the dashboard. Perfect for first-time users.

Time to complete: ~15 minutes

Prerequisites

Before we start, you'll need:

  1. A web app or website (even a local HTML file works!)
  2. A TheWebRatings account - Sign up FREE (takes 2 minutes)
  3. Your API key - Get it from your dashboard

Step 1: Get Your API Key

  1. Go to thewebratings.com/dashboard
  2. Enter your email and verify with the OTP sent to your inbox
  3. Complete onboarding (profile setup + add your app)
  4. Navigate to Dashboard → Settings → API Keys
  5. Generate and copy your API key

Keep this key safe! API keys are shown only once. It connects the widget to your account. Don't commit it to public repos.

Step 2: Create Your Test HTML File

Create a new file called test-feedback.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My First Rating - TheWebRatings</title>
  
  <!-- Load TheWebRatings widget -->
  <script src="https://cdn.thewebratings.com/twr.min.js"></script>
  
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 600px;
      margin: 50px auto;
      padding: 20px;
    }
    button {
      background: #3b82f6;
      color: white;
      border: none;
      padding: 12px 24px;
      font-size: 16px;
      border-radius: 8px;
      cursor: pointer;
    }
    button:hover {
      background: #2563eb;
    }
  </style>
</head>
<body>
  <h1>🌟 Welcome to My App</h1>
  <p>Try leaving a review using the button below:</p>
  
  <button onclick="openFeedback()">Leave a Review</button>

  <script>
    // Step 1: Initialize the widget with your API key (failsafe)
    (function () {
      if (!window.TheWebRatings || typeof TheWebRatings.init !== 'function') {
        console.error('TheWebRatings script not loaded. Check the <script src=\"https://cdn.thewebratings.com/twr.min.js\"> tag.');
        return;
      }

      TheWebRatings.init({
        apiKey: 'your-api-key-here',  // ← Replace with your actual API key
        debug: true  // Shows helpful logs in console
      });
    })();

    // Step 2: Function to open the review widget
    function openFeedback() {
      // Replace with your email for testing
      const testEmail = '[email protected]';
      const testName = 'Test User';
      
      TheWebRatings.open(testEmail, testName);
    }
  </script>
</body>
</html>

Replace these values:

  • your-api-key-here → Your actual API key from the dashboard
  • [email protected] → Your real email (you'll receive an OTP)

Step 3: Open Your Test File

  1. Save the file
  2. Open it in your browser (double-click or drag to browser)
  3. Open the browser console (F12 or Right-click → Inspect → Console)

You should see:

✓ TheWebRatings initialized successfully

If you see errors instead, jump to Troubleshooting below.

Step 4: Submit Your First Rating

  1. Click the "Leave a Review" button → The review widget slides up from the bottom of the screen

  2. Select a star rating (e.g., 5 stars ⭐⭐⭐⭐⭐) → Automatically advances to the review text step

  3. Optionally add a written review (e.g., "This is amazing!") → Minimum 20 characters required to enable the submit button

  4. Click "Submit Review"

  5. Check your email for the OTP (one-time password)

    • Subject: "Your verification code for TheWebRatings"
    • Code looks like: 123456

  6. Enter the OTP in the widget → Your rating is now submitted!

  7. Success screen shown inside the widget → Click "Done" to close. 🎉

Step 5: Verify in Dashboard

  1. Go to your TheWebRatings dashboard
  2. Navigate to Ratings or Reviews
  3. You should see your rating! with:
    • Star rating (5 stars)
    • Written review ("This is amazing!")
    • Timestamp (just now)
    • User email (your test email)

If you see it → Congratulations! You're all set up! 🚀

What Just Happened? (Behind the Scenes)

Here's the flow that occurred:

1. User clicks button
   ↓
2. open() called with email & name
   ↓
3. Bottom sheet slides up → checks for existing review
   ↓
4. No existing review → Star rating step shown
   ↓
5. User picks stars → Review text step shown
   ↓
6. User submits → Widget checks if user exists in TWR database
   ↓
7. User doesn't exist → Widget creates new user & sends OTP
   ↓
8. User enters OTP → Widget verifies it
   ↓
9. User is authenticated → Rating is submitted
   ↓
10. Inline success screen shown → Rating appears in your dashboard

The next time this user submits a new rating, OTP is skipped—the widget remembers them via localStorage. However, editing or deleting an existing review will still require OTP verification.

Listen to Submission Events (Optional)

Want to do something when a rating is submitted? Add event listeners:

<script>
  (function () {
    if (!window.TheWebRatings || typeof TheWebRatings.init !== 'function') {
      console.error('TheWebRatings script not loaded. Check the <script src=\"https://cdn.thewebratings.com/twr.min.js\"> tag.');
      return;
    }

    TheWebRatings.init({
      apiKey: 'your-api-key-here',
      debug: true
    });

    // Listen for successful submission
    TheWebRatings.on('rating:submitted', (data) => {
      console.log('Rating submitted!', data.ratingId, data.rating);
      // Example: Show a thank you message
      alert(`Thank you for your ${data.rating}-star rating!`);
    });
  })();

  function openFeedback() {
    TheWebRatings.open('[email protected]', 'Test User');
  }
</script>

Learn more: Event Handlers Guide

Integrate with Your Real App

Now that you've tested it, integrate it into your actual app.

Initialize only for logged-in users

Do not add the widget to your public pages or root layout. Initialize it in your authenticated area (dashboard, member portal, admin panel) — this ensures the auto-prompt only fires for logged-in users.

For Static Sites

Add the script and initialization to your authenticated pages (e.g., dashboard), and replace the hardcoded email/name with dynamic values:

function openFeedback() {
  // Get currently logged-in user from your app
  const user = getCurrentUser();  // Your function

  TheWebRatings.open(user.email, user.name);
}

For React Apps

Initialize in a component that only renders for authenticated users (e.g., a dashboard layout):

import { useEffect } from 'react';

function Dashboard() {
  const user = useAuth();  // Your auth hook

  useEffect(() => {
    TheWebRatings.init({
      apiKey: process.env.REACT_APP_TWR_API_KEY,
      debug: false
    });
  }, []);

  const handleFeedback = () => {
    TheWebRatings.open(user.email, user.name);
  };

  return (
    <button onClick={handleFeedback}>
      Leave a Review
    </button>
  );
}

More framework examples: React, Vue, Angular

Troubleshooting

Widget doesn't load / TheWebRatings is undefined

Possible causes:

  • Script tag is in wrong location
  • Network error blocking CDN
  • Ad blocker blocking script

Fix:

  1. Check browser console for errors
  2. Try disabling ad blockers
  3. Verify the script URL is correct (e.g. https://cdn.thewebratings.com/twr.min.js or your CDN)
  4. Make sure script loads before you call init()

"Invalid API key" error

Fix:

  1. Double-check your API key in the dashboard under Settings → API Keys
  2. Make sure there are no extra spaces or quotes
  3. Regenerate the key if you've lost it (keys are shown only once)

Widget doesn't slide up when button is clicked

Possible causes:

  • init() wasn't called
  • JavaScript error preventing execution
  • Email/name parameters missing

Fix:

  1. Open browser console and check for errors
  2. Verify TheWebRatings.init() was called
  3. Ensure open(email, name) has both parameters

OTP email not received

Possible causes:

  • Email in spam folder
  • Typo in email address
  • Email server delay

Fix:

  1. Check spam/junk folder
  2. Verify email address is correct (no typos)
  3. Wait 60 seconds—widget will show "Resend OTP" option
  4. Try with a different email (Gmail, Outlook, etc.)

Rating doesn't appear in dashboard

Possible causes:

  • OTP was not verified
  • Network error during submission

Fix:

  1. Confirm you completed the OTP verification step
  2. Check browser console for rating:submitted event
  3. Try refreshing the dashboard

Widget appears but submission fails

Check the browser console for errors. The widget does not emit a separate error event; on network failure it stores the review locally and shows the success screen. Use rating:submitted to confirm when a rating was successfully sent to the server.

Common error types:

  • network - Check internet connection
  • authentication - OTP not verified or expired
  • validation - Missing required fields
  • rate_limit - Too many submissions (wait 60 seconds)
  • server - Backend issue (rare, contact support)

Next Steps

🎉 Congrats on your first rating! Now explore:

Need Help?

We typically respond within 24 hours. Happy rating!

Quick Install

Get TheWebRatings running in your app in under 5 minutes

Features

Complete list of TheWebRatings features and capabilities

On this page

PrerequisitesStep 1: Get Your API KeyStep 2: Create Your Test HTML FileStep 3: Open Your Test FileStep 4: Submit Your First RatingStep 5: Verify in DashboardWhat Just Happened? (Behind the Scenes)Listen to Submission Events (Optional)Integrate with Your Real AppFor Static SitesFor React AppsTroubleshootingWidget doesn't load / TheWebRatings is undefined"Invalid API key" errorWidget doesn't slide up when button is clickedOTP email not receivedRating doesn't appear in dashboardWidget appears but submission failsNext StepsNeed Help?