Review Developer Docs

Reviews are structured models for collecting, moderating, and rendering public feedback in FaceFlow.

They allow technical teams to manage reputation-sensitive content as governed website output rather than as unmanaged freeform testimonials.

Core Responsibility

A Review model is responsible for:

• configurable review models
• structured rating fields
• public submission capture
• moderation and verification policy
• embeddable display output
• publication control

This makes Reviews suitable for trust-driven website sections that need both public visibility and operational control.

Core Review Model

A Review model usually combines:

• core review identity fields
• rating fields
• optional custom rating dimensions
• moderation settings
• verification behavior
• presentation and output settings

In practice, the Review layer defines both what feedback can be collected and what approved feedback can be published back to the website.

Conceptually:

{
  "name": "customer-success-reviews",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Submission and Publication Flow

At a high level:

1. a Review model is defined centrally
2. it is embedded into a Page through a Component
3. visitors submit feedback
4. moderation and verification rules are applied
5. approved entries are rendered back into the website experience

Conceptually:

review widget render
  -> visitor submission
  -> pending review state
  -> moderation / verification
  -> approved review published

This is why Reviews should be treated as governed public content, not just another input form.

Rating Structure

Review models can support:

• overall rating
• review title
• review content
• custom rating dimensions for more structured feedback

Example:

overall_rating
service_rating
communication_rating
value_rating

Use extra dimensions only when they improve trust and interpretation.

Review Model Example

A technical review should be able to inspect the model shape clearly:

{
  "name": "service-review",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

This helps teams review what is being collected, what is required, and how much moderation load the model is likely to create.

Moderation and Verification

Moderation and verification are central to Review design.

Technical teams should decide:

• whether entries require approval
• whether additional verification is needed
• who owns publication decisions
• how reputation-sensitive content should be handled

The higher the reputation risk, the stronger the controls should usually be.

Embedding Reviews

Reviews are typically embedded into page sections through Components.

A common embed marker is:

<div data-review-embed="service-review"></div>

Example section:

<section class="customer-proof">
  <header>
    <h2>What customers say</h2>
  </header>
  <div data-review-embed="customer-success-reviews"></div>
</section>

This keeps review collection and display reusable while allowing the Page to place trust content where it has the most impact.

Fixed vs Field-Backed Embeds

There are two common embed patterns.

Use a fixed managed review model id when the template should always render one specific Review model:

<div data-review-embed="customer-success-reviews"></div>

Use a field-backed embed when a Component exposes a reviewSelect field and authors should choose the managed Review model at authoring time:

<div data-review-embed="{serviceReview}"></div>

Decision rule:

• fixed embed -> one stable trust workflow owned by the template
• field-backed embed -> reusable Component with author-selectable review workflow

Integration Pattern

The clean runtime path is:

Review model
-> Component embed via reviewSelect or explicit data-review-embed marker
-> Page composition
-> public submission, moderation, and approved display output

That keeps reputation-sensitive workflow logic centralized instead of scattering it across one-off page markup.

Operational Guidance

Good Review design usually favors:

• one Review model per business context
• clear moderation ownership
• structured rating dimensions only where they add real value
• a submission experience short enough to preserve quality
• a publication model that supports trust instead of noise

If a Review model becomes too broad, quality and moderation usually become harder to manage.

Rating Contract Guidance

Keep the rating model proportional to the public workflow.

Typical patterns:

• simple trust section -> overall rating + title + review body
• service-quality workflow -> overall rating plus a small number of dimensions such as service, communication, or value

If a short public flow needs too many rating inputs, submission quality and completion rate usually drop.

Technical Guidance

• separate Review models by business context
• align moderation and verification policy with reputation sensitivity
• keep public review collection short enough to maintain submission quality
• treat published review content as governed output
• review collection, moderation, and display together as one workflow

Anti-Patterns

Avoid:

• one giant Review model used for unrelated business contexts
• too many rating dimensions for a short public flow
• publishing without clear moderation ownership
• treating Reviews like unmanaged testimonials pasted into Components
• designing the input flow without reviewing the display and approval model

Example Build Pattern

Review model:
  customer-success-reviews

Component:
  review-strip

Embed:
  <div data-review-embed="customer-success-reviews"></div>

That pattern keeps trust content reusable and governed.

Related

• Reviews Product Overview
• Review Guide
• Components
• Pages
• Users