Skip to main content
Skip table of contents

Working with Structured Data

Audience: Technical - Deep

Technical depth: ★★★★★

This article explains what structured data Emplifi generates and identifies related structured data you may already have. We also identify available configurations, and discuss how to combine your structured data with Emplifi’s.

Structured data Emplifi generates

Emplifi widgets support the schema.org AggregateRating vocabulary. An aggregate rating is a reflection of all the reviews collected for a product. Emplifi generates AggregateRating data in microdata or JSON-LD formats, based on your configurations.

Example: Aggregate rating details on a PDP, generated by a Emplifi widget.

image-20240513-110439.png

AggregateRating examples

In these examples, the ratingValue represents the average star ratings of all collected reviews for a product, and the reviewCount is the total number of reviews collected.

JSON-LD AggregateRating example

JS 
<script type="application/ld+json">
    {
        "@context": "https://schema.org",
        "@type": "Product",
        "name": "Purple Hat",
        "aggregateRating": {
            "@type": "AggregateRating",
            "ratingValue": "4.7",
            "reviewCount": "1581"
        }
    }
</script>

If needed, you can change the @type from Product to another value. For more, see Changing the JSON-LD object type.

Microdata AggregateRating example

HTML 
<div itemprop="aggregateRating" itemscope itemtype="https://schema.org/AggregateRating">
    <span itemprop="itemReviewed">Purple Hat</span> is rated
    <span itemprop="ratingValue">4.7</span> stars
    <span itemprop="reviewCount">1581</span> reviews.
</div>

Structured data you generate

Whether your PDPs already have structured data, or have nothing at all, Emplifi’s structured data is intended to fit into your overall structured data strategy.

If you already have structured data on your PDPs, pay close attention to the steps necessary for combining JSON-LD and combining microdata.

What if you don’t have product structured data?

If you don’t have any structured data already, and plan to receive Emplifi’s aggregate rating data in JSON-LD format, no other action is required.

If you don’t have any structured data already, and plan to receive Emplifi’s aggregate rating data in microdata format, you’ll need to add the surrounding product context. Including broader product information is important so that search engines have context for the rating and review content.

In microdata format, product markup looks something like this:

HTML 
<div itemscope itemtype="https://schema.org/Product">
    <span itemprop="name">Purple Hat</span>
    <img itemprop="image" src="../purple_hat.jpg" alt="Purple Hat">
    <span itemprop="description">This purple hat will keep you warm, cozy, and stylish!</span>
</div>

Note the presence of these required attributes: itemprop, itemscope, and itemtype. The product data should include the product name, price, and description, among other details.

For additional assistance on adding product microdata, consult an SEO expert. Google also provides structured data guidelines for products.

After you have added your product microdata, you must ensure that you insert Emplifi’s microdata within the Product context. For more, see Combining Emplifi microdata with your microdata.

Structured data configuration options

Emplifi can generate AggregateRating data in microdata or JSON-LD format.

To adjust the structured data that Emplifi provides on your site, contact your Emplifi Customer Success Manager. You must choose between receiving AggregateRating data in JSON-LD or microdata format, not both.

Select one of these possible configurations:

  • Disable AggregateRating structured data entirely.

  • JSON-LD:

    • Enable AggregateRating JSON-LD markup without the @id key.

    • Enable AggregateRating JSON-LD markup with the @id key.

  • Microdata:

    • Enable AggregateRating microdata markup.

Combining structured data

Emplifi’s structured data is intended to fit into your overall structured data strategy. Your PDPs should include structured data markup for your product name, price, and description, among other details. Including broader product information is important so that search engines have context for the rating and review content.

Combining Emplifi JSON-LD with your JSON-LD

If your site already uses JSON-LD for your product data, you can use the @id key to ensure that your JSON-LD and Emplifi’s JSON-LD combine correctly. This helps search engines treat your product data—including ratings and reviews—as a coherent whole.

Steps:

  1. Include the @id key in the product details JSON-LD markup on your PDPs.

  2. Set the @id value in your product JSON-LD markup to the window.location.href value.

  3. Contact your Emplifi Customer Success Manager to have the JSON-LD @id key turned on for your site.

The @id value you use must match the value Emplifi uses in its JSON-LD @id key. To create the match, Emplifi collects the URL from the window.location.href JavaScript object. Emplifi’s testing has shown that the value of @id must match the page URL in order for rating and review details to show in the SERP. As more information becomes available, Emplifi may update how we select and implement the @id key value.

JSON-LD example

Here is JSON-LD markup for a product on a website:

JSON 
{
    "@context": "https://schema.org",
    "@type": "Product",
    "@id": "https://www.example.com/index.php/amazingthing321.html",
    "name": "Amazing Thing 321",
    "image": "https://www.example.com/images/amazingthing321.png",
    "description": "You’ve never seen a product like this before.",
    "sku": "1234567"
}

The corresponding Emplifi JSON-LD markup looks something like this:

JSON 
{
    "@context": "https://schema.org/",
    "@type": "Product",
    "name": "Amazing Thing 321",
    "@id": "https://www.example.com/index.php/amazingthing321.html",
    "url": "https://www.example.com/index.php/amazingthing321.html",
    "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "4.8",
        "reviewCount": "749"
    }
}

For more information about the @id key, see Node Identifiers in the JSON-LD specification.

Combining Emplifi microdata with your microdata

To combine your Product microdata with Emplifi microdata, you must nest the Emplifi review widgets inside your existing Product microdata itemscope, as shown in the schema.org AggregateRating examples. If you PDPs don’t have product microdata, see What if you don’t have product structured data?

For instance, your Product markup might include the item name, product image, offer details, and a description, all enclosed alongside the aggregate rating within a div like this one: <div itemscope itemtype="https://schema.org/Product">

As you look through your Product Detail Pages, make sure the following are true:

  • Your page contains Product schema microdata markup.

  • In the hierarchy of your document object model (DOM), the EmplifiReviewContent div is inside the div that contains the Product schema.

Nested microdata examples

If we bring Product and AggregateRating elements together, we are describing content that might appear on a Product Detail Page. This example shows a Product with nested AggregateRating data.

HTML 
<div> <!-- Product schema markup -->
    <span> <!-- Product name --> </span>
    <img/> <!-- Product image -->

    <div> <!-- AggregateRating schema markup --> </div>

    <div> <!-- Product offer information --> </div>
    <span> <!-- Product description information --> </span>
</div>

Example with all div, img, and span tags filled in:

HTML 
<div itemscope="" itemtype="https://schema.org/Product">
    <span itemprop="name">Purple Hat</span>
    <img itemprop="image" src="../purple_hat.jpg" alt="Purple Hat" />

    <!-- Aggregate rating start-->
    <div itemprop="aggregateRating" itemscope="" itemtype="https://schema.org/AggregateRating">
        Rated <span itemprop="ratingValue">4</span>/5
        based on <span itemprop="reviewCount">11</span> customer reviews
    </div>
    <!-- Aggregate rating end-->

    <div itemprop="offers" itemscope="" itemtype="https://schema.org/Offer">
        <span itemprop="priceCurrency" content="USD">$</span>
        <span itemprop="price" content="1000.00">1,000.00</span>
        <link itemprop="availability" href="https://schema.org/InStock">
        In stock
    </div>
    Product description:
    <span itemprop="description">This purple hat will keep you warm, cozy, and stylish!</span>
</div>

Here are a couple of additional examples of how to properly nest aggregate rating content:

HTML 
<div itemscope itemtype="https://schema.org/Product">
    <span itemprop="brand">ACME</span> 
    <span itemprop="name">Executive Anvil</span>
    <img itemprop="image" src="/search/docs/data-types/markup/anvil_executive.jpg" />
    <span itemprop="aggregateRating" itemscope itemtype="https://schema.org/AggregateRating">
        Average rating: <span itemprop="ratingValue">4.4</span>, based on
        <span itemprop="ratingCount">89</span> reviews
    </span>
    <span itemprop="offers" itemscope itemtype="https://schema.org/AggregateOffer">
        from $<span itemprop="lowPrice">119.99</span> to
        $<span itemprop="highPrice">199.99</span>
        <meta itemprop="priceCurrency" content="USD" />
    </span>
</div>
HTML 
<div itemtype="https://schema.org/Product" itemscope>
    <meta itemprop="mpn" content="925872" />
    <meta itemprop="name" content="Executive Anvil" />
    <link itemprop="image" href="https://example.com/photos/16x9/photo.jpg" />
    <meta itemprop="description"
        content="Sleeker than ACME's Classic Anvil, the Executive Anvil is perfect for the business traveler looking for something to drop from a height." />
    <div itemprop="offers" itemtype="https://schema.org/Offer" itemscope>
        <link itemprop="url" href="https://example.com/anvil" />
        <meta itemprop="availability" content="https://schema.org/InStock" />
        <meta itemprop="priceCurrency" content="USD" />
        <meta itemprop="itemCondition" content="https://schema.org/UsedCondition" />
        <meta itemprop="price" content="119.99" />
        <meta itemprop="priceValidUntil" content="2020-11-05" />
    </div>
    <div itemprop="aggregateRating" itemtype="https://schema.org/AggregateRating" itemscope>
        <meta itemprop="reviewCount" content="89" />
        <meta itemprop="ratingValue" content="4.4" />
    </div>
    <div itemprop="review" itemtype="https://schema.org/Review" itemscope>
        <div itemprop="author" itemtype="https://schema.org/Person" itemscope>
            <meta itemprop="name" content="Fred Benson" />
        </div>
        <div itemprop="reviewRating" itemtype="https://schema.org/Rating" itemscope>
            <meta itemprop="ratingValue" content="4" />
            <meta itemprop="bestRating" content="5" />
        </div>
    </div>
    <meta itemprop="sku" content="0446310786" />
    <div itemprop="brand" itemtype="https://schema.org/Thing" itemscope>
        <meta itemprop="name" content="ACME" />
    </div>
</div>

Combining microdata and JSON-LD

Emplifi advises against combining microdata and JSON-LD. If you have Product structured data on your PDP, ask your Emplifi Customer Success Manager to set your Emplifi structured data to use the format you’re already using.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close