Installing the widgets

Everything Evident renders on your storefront comes from one script and a container element per widget.

The script

Storefront → Install & Theme has your copy of this, with your store environment ID filled in. Add it once, anywhere — theme footer, app shell, root layout.

<script
  src="https://app.evidentugc.com/widgets/evident-sdk.min.js"
  data-store-env-id="YOUR_STORE_ENV_ID"
  defer
></script>

It loads its own stylesheet, fetches your theme settings, and mounts every container it finds. It also watches the DOM, so containers your framework renders later are mounted too, and re-mounted if a re-render blows one away.

The store environment ID is not a secret — it identifies a store, it does not authorise anything. What controls who may call the API from a browser is the origin allow-list under Settings → Store, which is enforced by CORS. A browser on a domain that is not on the list is refused.

The widgets

Place a container wherever you want output. The widget type goes in data-evident-widget.

star-badge

The compact rating summary — stars, average, count. Goes on product cards and near the product title.

<div data-evident-widget="star-badge" data-product-id="PRODUCT_ID"></div>

Options: data-show-count, data-show-label, data-size (sm, md, lg), data-scroll-target (a CSS selector to jump to when clicked — point it at your review list).

review-list

The full review list for one product, with sorting and pagination.

<div data-evident-widget="review-list" data-product-id="PRODUCT_ID"></div>

Options: data-layout, data-grid-columns (for the grid layout), data-limit, data-show-distribution, data-show-sorting, data-show-images, data-image-size, data-show-helpful, data-show-date, data-show-form. When the list includes the form, it also takes the review-form options below.

review-form

A standalone submission form. Most stores do not need this — the hosted form linked from review request emails covers the normal path — but it is there for “write a review” on the page itself.

<div data-evident-widget="review-form" data-product-id="PRODUCT_ID"></div>

Options: data-allow-images, data-max-images, data-allow-videos, data-max-video-duration (seconds).

review-carousel

Store-wide reviews, rotating. For a homepage or a landing page. Takes no product ID.

<div data-evident-widget="review-carousel"></div>

Options: data-autoplay, data-autoplay-interval, data-limit, data-show-images, data-show-product-name, data-show-date.

gallery

A curated gallery, by slug.

<div
  data-evident-widget="gallery"
  data-gallery-slug="customer-photos"
  data-columns="3"
></div>

Options: data-columns, data-display-mode (GRID or CAROUSEL, overriding the gallery’s own setting), data-carousel-arrows, data-carousel-dots, data-caption-position, data-show-title, data-show-description, data-show-favorites, data-show-submissions, and the data-lead-form-* family if the gallery captures leads.

faq

FAQs for a target. data-target-type is product, category, page or blog, and the ID attribute follows from it — data-product-id, data-category-id, or data-page-id.

<div
  data-evident-widget="faq"
  data-target-type="product"
  data-product-id="PRODUCT_ID"
></div>

Options: data-layout (accordion, dual-column, list), data-no-global to suppress the store-wide FAQs that otherwise cascade in.

loyalty

The customer’s loyalty panel — balance, tier, ways to earn, rewards.

<div data-evident-widget="loyalty" data-email="CUSTOMER_EMAIL"></div>

Options: data-show-rewards, data-show-earning-rules, data-show-referral-code.

Every widget

data-max-width caps the container’s width — 1600px unless you say otherwise. A bare number is pixels; px, % and rem are honoured; none removes the cap so the widget fills its parent.

Product IDs

data-product-id is your platform’s product ID — the same value Evident synced or you pushed. On BigCommerce that is {{product.id}}; on Shopify, {{ product.id }}. On a headless store it is whatever you sent as platformProductId.

Getting this wrong is the usual cause of a widget rendering nothing at all. The match is exact — "SKU-1024" and "sku-1024" are different products — and a product Evident does not know about makes the star badge render nothing and the review list show “Failed to load reviews”. See Troubleshooting the widgets.

Performance

The snippet loads with defer, so it does not block rendering, and the SDK waits for the page to be parsed before it mounts anything.

While a widget fetches its data it shows a placeholder. A widget with nothing to show — a star badge on a product with no approved reviews, an empty gallery or FAQ list — renders nothing at all rather than an empty box, so do not rely on it to hold space in your layout.

If you enforce a Content Security Policy, the widgets need connect-src https://api.evidentugc.com as well as script, style and image sources — the full list is under Headless storefronts, and it applies to every storefront, not only headless ones.

Programmatic control

The SDK exposes an API on window.Evident for frameworks that would rather mount explicitly than rely on DOM watching: init(), refresh(), mount(el) and unmount(el). All are safe to call more than once. See Headless storefronts for the React pattern.