Documentation

Quick Start

<div id="star-rating" 
     data-site-id="your-site.com" 
     data-auth-code="your-auth-code"
     data-item-id="product-123"
     data-schema-type="Product"
     data-title="Product Name"
     data-lang="en"></div>

<script>
  window.STAR_RATING_CONFIG = {
    apiUrl: 'https://star-rating.payloadic.com'
  };
</script>
<script src="https://star-rating.payloadic.com/star-rating-widget-standalone.js"></script>

Required Attributes

data-site-id: Unique identifier for your site (e.g., "your-site.com"). Must match the site_id configured in the system.
data-auth-code: Authentication code for your site. Provided when you register your site.

Optional Attributes

data-item-id: Unique identifier for the item (e.g., "product-123", "article-456", "/page-1"). Can be a slug, ID, or path. Defaults to window.location.pathname.
data-schema-type: Schema.org type for JSON-LD structured data. Defaults to "Product".; Allowed values: Any Schema.org type that supports aggregateRating. Common types include:
data-title: Title for JSON-LD structured data. Defaults to document.title.
data-api-url: API endpoint URL. Can also be set via window.STAR_RATING_CONFIG.apiUrl.
data-lang or data-language: Language code for widget text (e.g., "en", "pl"). Defaults to "en".; Supported languages:

Global Configuration

You can configure the widget globally using window.STAR_RATING_CONFIG:

<script>
  window.STAR_RATING_CONFIG = {
    apiUrl: 'https://star-rating.payloadic.com',
    language: 'en' // or 'pl' for Polish
  };
</script>

JSON-LD Structured Data

The widget automatically injects JSON-LD structured data into the page <head> for SEO purposes. This allows search engines like Google to display star ratings in search results.

The JSON-LD is generated automatically when:

The widget loads and fetches the current rating
A user submits a new vote

Example generated JSON-LD:

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "Product Name",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "ratingCount": "10",
    "bestRating": "5",
    "worstRating": "1"
  }
}

Custom Events

The widget dispatches a custom event when a user votes:

document.addEventListener('starRatingVoted', (event) => {
  console.log('Vote submitted:', event.detail);
  // event.detail contains: { score, siteId, itemId }
});

Security & Origin Validation

The widget validates that it's being used on an authorized domain:

Each site has a configured URL that must match the current page origin
Localhost is allowed for development purposes
Votes are rejected if the origin doesn't match the configured site URL
Server-side validation also enforces origin checks via database RLS policies

Examples

Product Rating

<div id="star-rating" 
     data-site-id="myshop.com" 
     data-auth-code="my-auth-code"
     data-item-id="product-123"
     data-schema-type="Product"
     data-title="Amazing Product"
     data-lang="en"></div>

Article Rating

<div id="star-rating" 
     data-site-id="myblog.com" 
     data-auth-code="my-auth-code"
     data-item-id="article-456"
     data-schema-type="Article"
     data-title="How to Code"></div>

Restaurant Rating

<div id="star-rating" 
     data-site-id="restaurant.com" 
     data-auth-code="my-auth-code"
     data-item-id="restaurant-789"
     data-schema-type="Restaurant"
     data-title="Italian Bistro"></div>

Product Rating (Polish)

<div id="star-rating" 
     data-site-id="myshop.com" 
     data-auth-code="my-auth-code"
     data-item-id="product-123"
     data-schema-type="Product"
     data-title="Amazing Product"
     data-lang="pl"></div>

Ready to get started?

Check out the demo page to see the widget in action.

Back to Home