Hosted UI JavaScript Implementation

Hosted UI with our JavaScript widgets is the simplest way to get started.

The implementation consists of a single asynchronous script, placeholder elements for the widgets, and a configuration section.

Script

The following script should be added to the <head> section on your website.

your.client.id should be replaced with one of your assigned client IDs.

<script async src="https://js.testfreaks.com/onpage/your.client.id/head.js"></script>

Placeholders

Add the following placeholders to your product pages where you want the content to appear:

<div id="testfreaks-badge"></div>

<div id="testfreaks-reviews"></div>

<div id="testfreaks-qa"></div>

<div id="testfreaks-seller"></div>

<div id="testfreaks-videos"></div>

<div id="testfreaks-all-reviews-badge"></div>

<div id="testfreaks-all-reviews"></div>

badge is the review summary (rating and review count), reviews is the main review section, and qa is the Q&A section.

seller is the seller review summary with popup.

videos is the video thumbnails.

all-reviews-badge is the review summary (rating and review count) of all product and seller reviews combined. all-reviews is the section for all product and seller reviews.

Configuration

On each product page you configure the script with the product ID and the sections you want to load. For example:

<script>
  testFreaks = window.testFreaks || [];
  testFreaks.push(["setProductId", "PRODUCTID"]);
  testFreaks.push(["load", ["badge", "reviews", "qa", "seller", "videos"]]);
</script>

PRODUCTID should be your product ID, or demo for example content.

This configuration can go anywhere on the page but should ideally be in the <head> section for best performance.

Please refer to the API section below for a list of available commands.

Badge Clicks

By default, clicks on the badge will scroll to the review section. This behaviour can be overridden by configuring the following callback:

testFreaks.push(["onBadgeClick", function() {
  // Your code for handling badge clicks
}]);

You may want to use this to scroll to some header appearing before the testfreaks-reviews element. If the reviews are placed in a tab or accordion, you can also make sure the section is selected or expanded.

Hiding empty review sections

If you add headers, tabs or accordions around the testfreaks-reviews placeholder, you may want to hide those elements if there are no reviews for a particular product. This is done by putting a testfreaks-section on the element which you would like to hide, and then hiding it unless testfreaks-section-loaded is also set.

For example, if you create a header like this:

<div class="testfreaks-section">
  <h2>Reviews</h2>
  <div id="testfreaks-reviews"></div>
</div>

The widget script will look for reviews to insert into testfreaks-reviews. If it finds any, it will look for the closest containing testfreaks-section and add the additional class testfreaks-section-loaded. So if there are reviews, this is the end result:

<div class="testfreaks-section testfreaks-section-loaded">
  <h2>Reviews</h2>
  <div id="testfreaks-reviews">
    [...]
  </div>
</div>

To hide this entire section from start and only show it if and when it contains reviews, just add a CSS rule like this:

.testfreaks-section { display: none }
.testfreaks-section-loaded { display: block }

If you have an open “Write review”-form enabled in your widget, the review section will never be hidden to enable users to always write reviews.

Category Stars

To display rating stars and review counts for multiple products on the same page you can add the following placeholder, once for each product, where you want the stars to appear:

<div class="testfreaks-item" data-product-id="PRODUCTID"></div>

PRODUCTID should be the product ID corresponding to each placeholder.

After the last such placeholder on the page you then add the following script to load the stars:

<script>(testFreaks = window.testFreaks || []).push(["load", "items"])</script>

Product Families

It’s often desirable to group customer reviews into product families in order to display the same set of reviews on related products.

If your product and order data contain both product IDs and family IDs, then this grouping will often be enabled automatically. If not you can configure the family ID as follows:

testFreaks.push(["setFamilyId", "FAMILYID"]);
testFreaks.push(["setProductId", "PRODUCTID"]);

And for category stars:

<div class="testfreaks-item"
     data-family-id="FAMILYID"
     data-product-id="PRODUCTID">
</div>

If family IDs are unavailable then it’s possible to group customer reviews by specifying multiple product IDs:

testFreaks.push(["setProductId", ["PRODUCTID_1", "PRODUCTID_2"]]);

<div class="testfreaks-item"
     data-product-id='["PRODUCTID_1","PRODUCTID_2"]'>
</div>

It’s also possible to group families together by specifying multiple family IDs:

testFreaks.push(["setFamilyId", ["FAMILYID_1", "FAMILYID_2"]]);

<div class="testfreaks-item"
     data-family-id='["FAMILYID_1","FAMILYID_2"]'>
</div>

Configuration API

Description of the available configuration commands that can be added between the testFreaks variable declaration and the "load" command.

testFreaks = window.testFreaks || [];

// Configuration
testFreaks.push(["command1", "parameter1"]);
testFreaks.push(["command2"]);

testFreaks.push(["load", ["badge", ...]]);

setProductId

testFreaks.push(["setProductId", "PRODUCTID"]);
  • The key/SSID of the product
  • Also accepts an array of IDs in which case the extra IDs are used to combine customer reviews from related products.

setFamilyId

testFreaks.push(["setFamilyId", "FAMILYID"]);
  • The family/model ID of the product
  • Also accepts an array of IDs in which case the extra IDs are used to combine customer reviews from related families.

setMaxWidthSmall

testFreaks.push(["setMaxWidthSmall", "700px"]);
  • Sets the maximum width for the small screen layout
  • Accepts {reviews: "700px", qa: "600px"} for per-module settings

setMaxWidthMedium

testFreaks.push(["setMaxWidthMedium", "1000px"]);
  • Sets the maximum width for the medium screen layout
  • Accepts {reviews: "1000px", qa: "900px"} for per-module settings

setTranslationLang

testFreaks.push(["setTranslationLang", "en"]);
  • Enables Google Translate into the specified language, for review- and Q&A content
  • An optional {except: ["lang1", "lang2", ...]} parameter can be added to disable translations for selected languages. For example:
testFreaks.push(["setTranslationLang", "sv", {except: ["da", "no"]}]);

setAggregateRatingSchema

testFreaks.push(["setAggregateRatingSchema", "json-ld"]);

setAnalytics

testFreaks.push(["setAnalytics", "dataLayer"]);
  • Enables analytics events to be sent to the dataLayer
  • See Analytics for more details

onBadgeClick

testFreaks.push(["onBadgeClick", function() {...}]);
  • Callback called on each badge click
  • Disables the automatic scrolling to the review section

load

testFreaks.push(["load", ["reviews", "badge", "qa", "seller", "items"]]);
  • Loads and displays the specified modules according to the configuration

reset

testFreaks.push(["reset"])
  • Resets the following configuration in preparation for a new "load" command:
    • setProductId
    • setFamilyId
    • onBadgeClick
  • The implementation is responsible for resetting the placeholders. The widget script will not remove content already loaded into the placeholders. For example:
if (document.getElementById("testfreaks-badge")) {
   document.getElementById("testfreaks-badge").innerHTML="";
}
if (document.getElementById("testfreaks-reviews")) {
   document.getElementById("testfreaks-reviews").innerHTML="";
}
if (document.getElementById("testfreaks-qa")) {
   document.getElementById("testfreaks-qa").innerHTML="";
}

Search Result Stars

The script can be configured to generate aggregate rating data compatible with existing product sections in either microdata or JSON-LD formats.

Please make sure you first have followed Google’s instructions on product page markup.

Microdata

If the #testfreaks-badge placeholder is positioned inside a microdata product section then the following command can be used to enable the rating data (should be configured before the "load" command):

testFreaks.push(["setAggregateRatingSchema", "microdata"]);

Please make sure that your site meets the following requirements:

  • Has a single microdata product section that identifies the product on the page by name or model
  • Has the #testfreaks-badge placeholder located somewhere inside that product section
  • Passes rich snippet validation without errors

Below is an example of a minimal product section that meets these requirements:

<div itemscope itemtype="http://schema.org/Product">
  <span itemprop="name">Apple iPhone 7</span>
  <div id="testfreaks-badge"></div>
</div>

JSON-LD

If the #testfreaks-badge placeholder is added to a page with a JSON-LD product section then two steps are required to enable the rating data:

First extend your existing product section by adding an "@id": "#product" attribute. For example:

<script type="application/ld+json">
{
  "@id": "#product",
  "@context": "http://schema.org",
  "@type": "Product",
  "name": "Product Name"
  ...

Then configure the script to generate ld+json data with the following command (should be configured before the "load" command):

testFreaks.push(["setAggregateRatingSchema", "json-ld"]);

If your product section already has an @id attribute you can leave it unchanged and pass its value to the script:

testFreaks.push(["setAggregateRatingSchema", "json-ld", "your-id"]);

Analytics

The script can be configured to add dataLayer analytics events with the setAnalytics configuration command:

testFreaks.push(["setAnalytics", "dataLayer"]);

The events take the following form:

{
  event: "TestFreaks",
  eventCategory: "TestFreaks Reviews",
  eventAction: "TestFreaks Reviews ClickBadge",
  nonInteraction: "False"
}
  • event is always “TestFreaks”
  • eventCategory and eventAction represent the type of event
  • nonInteraction is “False” for user-initiated events and “True” otherwise

See Analytics Tracking for a description of the available categories and actions.

Google Analytics

Please contact your account manager for event tracking directly to Google Analytics, or use Google Tag Manager to import the dataLayer events as described below.

Google Tag Manager

The following steps describes how to setup Google Tag Manager to import the “TestFreaks” dataLayer events into Google Analytics.

  1. Create three new variables with type “Data Layer Variable” and the following variable names:
    • eventAction
    • eventCategory
    • nonInteration

  2. Create a new trigger with type “Custom Event” and with “TestFreaks” as event name.

  3. Create a new tag with type “Google Analytics: Universal Analytics”.

    Select “Event” as track type, and for “Action”, “Category” and “Non-Interaction Hit”, select the corresponding variables from (1).

    Copy the remaining settings from existing Google Analytics tags, or check “Enable overriding settings in this tag” and enter your Tracking ID.

    Select the trigger from (2) as the trigger for the new tag.