Ratings and Reviews initialization

The Ratings and Reviews initializer connects the drop-in to Adobe Commerce GraphQL and loads the store’s review settings. It also applies custom labels and data models. Wait for initialization to finish before rendering Review or Pagination, which read these settings.

Configuration options

Pass label and data model customizations to initialize with these options:

Option	Type	Req?	Description
langDefinitions	LangDefinitions	No	Changes dictionary labels to translate the text or match your storefront’s wording. See Dictionary.
models	Models	No	Adds or changes fields in the review data. See Customize data models.

The configuration type also accepts isProductReviewsEnabled and allowGuestsToWriteProductReviews. Set these review settings in the Admin rather than in code. The initializer replaces code-based values with the settings loaded from Commerce.

Default initializer

The initializer from the Ratings and Reviews quick start sets the endpoint, loads labels from a placeholders sheet, and initializes the drop-in. Use it as the starting point for customizations:

scripts/initializers/ratings-reviews.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize, setEndpoint } from '@dropins/storefront-ratings-reviews/api.js';
import { initializeDropin } from './index.js';
import { CORE_FETCH_GRAPHQL, fetchPlaceholders } from '../commerce.js';

// Loads label overrides from the placeholders/ratings-reviews.json sheet.
const labels = await fetchPlaceholders('placeholders/ratings-reviews.json');

await initializeDropin(async () => {
  // Reviews and review settings come from Commerce GraphQL, not Catalog Service.
  setEndpoint(CORE_FETCH_GRAPHQL);

  return initializers.mountImmediately(initialize, {
    langDefinitions: {
      default: { ...labels },
    },
  });
})();

• fetchPlaceholders loads label overrides from placeholders/ratings-reviews.json.
• setEndpoint configures Commerce GraphQL before the drop-in requests review settings.
• mountImmediately waits for initialization to finish, so the settings are ready before the block renders its containers.

Endpoint and headers

Call setEndpoint before initialize. CORE_FETCH_GRAPHQL supplies the Commerce GraphQL endpoint and store headers for the storeConfig and reviews queries.

Use the Commerce GraphQL endpoint, not the Catalog Service endpoint. Other drop-ins load average ratings for catalog pages from Catalog Service. The Ratings and Reviews drop-in does not request those averages.

Review settings

During initialization, the drop-in requests the store’s review settings and saves them in its configuration. Later initialization calls on the same page reuse a successful request:

Setting	GraphQL source	Effect
isProductReviewsEnabled	storeConfig.product_reviews_enabled	When false, Review and Pagination render nothing. The Product Reviews block from the quick start also stays hidden. WriteReview does not check this setting, so check it before showing the form.
allowGuestsToWriteProductReviews	storeConfig.allow_guests_to_write_product_reviews	When false, signed-out shoppers see a sign-in prompt in WriteReview instead of the form. This setting does not restrict access to approved reviews.

• Defaults: Both settings default to false.
• Failed request: The drop-in logs [Ratings Reviews] Failed to fetch store config: in the browser console and sets both settings to false, so reviews stay hidden.
• Retry: A later initialization call requests the settings again. Reloading the page also runs initialization again.

After initialization finishes, read the saved settings in your block with config.getConfig():

blocks/product-reviews/product-reviews.js

import { config } from '@dropins/storefront-ratings-reviews/api.js';

// Returns false until initialization has loaded the store settings.
const { isProductReviewsEnabled } = config.getConfig();

Language definitions

Use langDefinitions to translate labels or match your storefront’s wording. Include only the keys to change. The drop-in uses your values for those keys and keeps the default English labels for the rest.

This example changes the review list heading:

scripts/initializers/ratings-reviews.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize, setEndpoint } from '@dropins/storefront-ratings-reviews/api.js';
import { initializeDropin } from './index.js';
import { CORE_FETCH_GRAPHQL } from '../commerce.js';

await initializeDropin(async () => {
  // Configure Commerce GraphQL before initialization loads the review settings.
  setEndpoint(CORE_FETCH_GRAPHQL);

  return initializers.mountImmediately(initialize, {
    langDefinitions: {
      // Default labels apply to every locale unless a locale entry overrides them.
      default: {
        Review: {
          title: 'Customer reviews',
        },
      },
    },
  });
})();

• default supplies labels for every locale unless a locale-specific entry overrides them.
• Review.title changes the heading to Customer reviews when the Review container has no totalCount value.

Tip

For every available key, see the Ratings and Reviews dictionary.

Customize data models

Use the models option to add or change fields in the review data that containers and slots receive. A transformer is a function that converts query data into model fields.

Each transformer receives the raw GraphQL object. Return only the fields to add or change. The drop-in combines them with its default model, keeping the other default fields.

Model	Transformer receives	Default fields
ProductReviewModel	One raw review from reviews.items	nickname, summary, text, rating, createdAt
ProductReviewsModel	The raw reviews response	items, pageInfo

The reviews query already requests each review’s ratings_breakdown, which lists the score for each rating category, such as Quality or Price. The default model does not keep this field. This example adds it to every review as ratingsBreakdown:

scripts/initializers/ratings-reviews.js

import { initializers } from '@dropins/tools/initializer.js';
import { initialize, setEndpoint } from '@dropins/storefront-ratings-reviews/api.js';
import { initializeDropin } from './index.js';
import { CORE_FETCH_GRAPHQL } from '../commerce.js';

await initializeDropin(async () => {
  // Configure Commerce GraphQL before initialization loads the review settings.
  setEndpoint(CORE_FETCH_GRAPHQL);

  return initializers.mountImmediately(initialize, {
    models: {
      ProductReviewModel: {
        // review is the raw GraphQL review object.
        transformer: (review) => ({
          // Each entry has a category name and a value, for example { name: 'Quality', value: '4' }.
          ratingsBreakdown: review.ratings_breakdown ?? [],
        }),
      },
    },
  });
})();

• review.ratings_breakdown contains the category names and scores from GraphQL.
• ratingsBreakdown is the new model field. The ?? [] fallback supplies an empty array when the query field is missing or null.

Read the new field in the ReviewItem slot through context.review.ratingsBreakdown. See Review slots.

A transformer can read only the fields that the query requests. For each review, the reviews query requests nickname, summary, text, average_rating, created_at, and ratings_breakdown. For the page, it requests current_page, page_size, and total_pages.

Configuration types

Both langDefinitions and models are optional.

langDefinitions

Maps locale identifiers to dictionaries of labels. Labels in default apply to every locale. Labels for the current locale take precedence over them.

langDefinitions?: {
  [locale: string]: {
    [key: string]: string | object;
  };
};

models

Maps model names to model customizations. Each customization accepts a transformer function, as shown in Customize data models.

models?: {
  ProductReviewModel?: Model<ProductReviewModel>;
  ProductReviewsModel?: Model<ProductReviewsModel>;
};

For the ProductReviewModel and ProductReviewsModel shapes, see Functions.