Generic (Other Platforms): Installing Yotpo Reviews (v3)

      Generic (Other Platforms): Installing Yotpo Reviews (v3)


        Article Summary

        Products


        Reviews
        Supported plans

        Free, Growth, Prime, Premium, Enterprise

        eCommerce Platform

        Custom

        This article will guide you through the steps of installing Yotpo Reviews on a generic eCommerce platform.

        Who should use this guide?
        • Use this guide if you’re a merchant using an eCommerce platform that is not listed as a Yotpo supported platform. Otherwise, we recommend you should use the relevant platform-specific guide. See supported platforms
        • This guide is intended for new Yotpo customers, as it uses our Core API v3, released in April 2021. If you already installed Yotpo before this date, you might prefer to use our previous installation guide.

        How it works

        To provide its full breadth of capabilities, Yotpo integrates with your store’s backend and frontend. Yotpo’s architecture decouples both, so you can decide on the best means of integration according to your specific setup. Moreover, Yotpo’s APIs allow you to fully customize every aspect of the integration programmatically.

        Getting started

        Before you start using our APIs, make sure you’ve got your Yotpo app key and API secret handy. If you have multiple Yotpo stores set up in your account, each store will have its own API credentials. Not sure how to find them? See Finding your Yotpo App Key and API Secret

        Syncing your store backend

        Our one-time API integration allows you to sync your store activity and related information to Yotpo, including orders, product catalog information, customers, and other store information required to configure Yotpo products. 

        For example, the Core API allows you to integrate your backend with Yotpo for Reviews and then quickly add SMS with no integration downtime.

        Tip:
        If this is the first time you’re working with Yotpo’s APIs, we highly recommend that you carefully read the Getting Started section of the API documentation to learn how to work with our RESTtful API.

        If you’ve already integrated another product in the past, for example, Yotpo SMS, you may not need to recreate the same service (e.g. products).

        Step 1 - Generating a UToken

        The first thing you will need to do is use your store API credentials to generate a UToken. The UToken may expire from time to time, and will need to be re-generated if you receive an authentication error.

        Step 2 - Sending products to Yotpo

        You must send your product information to Yotpo in order for Yotpo to send review request emails to your customers, display these reviews on your product pages and marketing channels, and allow you to tag images with products.

        We recommend that you send a standalone product feed with products as they are created and updated in your system to keep your catalog in sync with Yotpo at all times. 

        A few things to note about products:

        • Variants: If you are listing products on Google Shopping or using Yotpo’s retail syndication with Walmart or other partners, you will need to include a feed of product variants associated with each parent product and include each variant’s unique product identifiers.
        • Product hierarchy: We recommend sending to Yotpo your parent-level products. 
        • Grouping products: You may group products together to share reviews or images both ways, by adding the same Group Name to two products. 
        • Product Identifiers: We highly recommend including all available product identifiers, including SKU, MPN, Brand & GTIN with every product, so Google and other marketplaces can match your reviews and display them.
        • Add a product to your blocklist: When you add a product to your blocklist, Yotpo will not trigger any automatic review requests for it.
        • Review form tags: You can include a product tag to be used to create different review forms for different categories of products.

        If you do not have the resources to create a separate product feed, you may send aggregated order info, coupled with the product information that will be used in Yotpo. By using this approach, you'll be able to sync your store information to Yotpo with a single API call. However, you may be limited from using certain Yotpo features such as tagging new products to images, product sampling integrations, Google seller rating, Google Shopping, or syndication, until the first order for that product is received.

        Step 3 - Sending orders to Yotpo

        In order for Yotpo to send out automatic review requests, you must send your orders to Yotpo. We recommend that you send us your orders as soon as they are created.We'll send out review requests only for fulfilled orders. You can set your order status by using the same order creation endpoint, or as a separate API call. Make sure you include the following fields: 

        • fulfillment_date
        • fulfillment_status=success

        Yotpo will send the review request email a few days after the "fulfillment date", as defined in Yotpo Reviews.

        Please note:
        If you pass a cancellation object in the Create order API call, all scheduled review requests for this order will also be cancelled. This action is not reversible.

        That’s it, your back end is now integrated with Yotpo and you can start collecting reviews and tagging products.

        To learn more, see How to use the Core API or reach out to your Yotpo representative or Yotpo Support.

        Integrating your store frontend

        Integrating your store frontend includes placing Yotpo’s core scripts and widgets in your storefront. These widgets will be automatically populated with the scoring and review content relevant to the product page.

        Additionally, you can style your widgets via the cloud-based Yotpo admin to make sure they match your brand’s voice and tone.

        Step 1 - Adding the JavaScript library code

        Add the following to the <head> tag:

        <script type="text/javascript">
        (function e(){var e=document.createElement("script");e.type="text/javascript",e.async=true,e.src="//staticw2.yotpo.com/###YOUR APP-KEY###/widget.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})();
        </script>

        Make sure you replace ###YOUR APP-KEY### with your Yotpo app key!

        Step 2 - Adding the Reviews Widget

        The Reviews Widget allows you to showcase your reviews on product pages in a fully customizable format. Each review will appear with a title, review content, and its associated star rating.

        To add the Reviews Widget to your website, add the following code snippet to your product pages:

        <div class="yotpo yotpo-main-widget"
        data-product-id="SKU/Product_ID"
        data-price="Product Price"
        data-currency="Price Currency"
        data-name="Product Title"
        data-url="The url of your product page"
        data-image-url="The product image url">
        </div>

        Make sure you replace each data element with the appropriate values of your website and product attributes.

        The data-product-id attribute supports only alphanumeric (a...z, A...Z, 0...9) and "_" and "-" symbols.

        Reviews Widget - Example

        Once you fill in the appropriate values, the review code should look like this:

        <div class="yotpo yotpo-main-widget"data-product-id="1957"data-price="50"data-currency="USD"data-name="Soap"data-url="www.item.com/soap"data-image-url="www.url.com"></div>

        Prefiltering & presorting your widget using metadata filters

        If your Reviews Widget includes metadata filters, you have the option of configuring the widget to load in a pre-sorted and/or pre-filtered state according to the predefined or custom metadata params defined upon order creation. 

        You can use the following parameters:

        • customer_properties
        • order_properties
        • product_properties
        • custom_customer_properties
        • custom_order_properties
        • custom_product_properties

        Learn more in our Reviews Metadata API Reference.

        Please note:
        Metadata filtering is currently available only for stores built on non-hosted (custom/generic) eCommerce platforms. Contact your Yotpo representative to learn more.

        Widget pre-sorting

        Pre-sorting your widget allows you to surface certain reviews based on your sorting criteria. The widget will load in a pre-sorted state according to the metadata parameters defined upon order creation.

        To pre-sort your Reviews Widget according to metadata params, add the snippet below to your Reviews Widget snippet:

        data-presorting='[
        {"type": "customer_property", "key": "state", "value": "New York"},
        {"type": "customer_custom_property", "key": "age", "value": 22},
        {"type": "customer_custom_property", "key": "still_alive", "value": true}
        ]'

        Widget pre-filtering

        Pre-filtering your widget allows you to display only certain reviews based on your filtering criteria. The widget will load in a pre-sorted state according to the metadata parameters defined upon order creation. 

        To pre-filter your Reviews Widget according to metadata params, add the snippet below to your Reviews Widget:

        data-prefilter='{
        "order_properties":{"year":["2017"]},
        "customer_properties":{"state": ["New York"]},
        "customer_custom_properties":null}'

        Pre-sorted, pre-filtered widget

        The snippet below reflects the Yotpo Reviews Widget with pre-filtered and pre-sorted fields:

        <div class="yotpo yotpo-main-widget"
        data-product-id="{{ product.id }}"
        data-name="{{ product.title | escape }}"
        data-url="{{ shop.url }}{{ product.url }}"
        data-image-url="{{ product.featured_image | product_img_url: "large" |replace: '?', '%3F' | replace: '&','%26'}}"
        data-description="{{ product.description | escape }}"
        data-prefilter='{"order_properties":{"year":["2017"]},"customer_properties":{"state": ["New York"]},"customer_custom_properties":null}'
        data-presorting='[{"type": "customer_property", "key": "state", "value": "New York"},{"type": "customer_property", "key": "age", "value": 22},{"type": "customer_property", "key": "still_alive", "value": true}]'>
        </div>

        Step 3 - Adding the Star Rating element

        The Star Rating reflects the average aggregated rating of a product's published reviews and offers an easy way to link shoppers to read full reviews on your site. The star rating will appear only next to products that have reviews. When the star rating is installed, clicking on it will bring you to all the reviews of the product. For this reason, people usually insert the star rating code somewhere close to the product description near the top of the page.

        To add the Star Rating to your website, add the following code snippet to your product pages:

        <div class="yotpo bottomLine"
        data-yotpo-product-id="SKU/Product_ID">
        </div>

        Make sure you replace each data element with the appropriate values of your website and product attributes.

        The data-product-id attribute supports only alphanumeric (a...z, A...Z, 0...9) and "_" and "-" symbols.

        Tip:
        To add the star rating widget on the collection page, place the same code in your category/collection page file.

        Step 4 - Adding additional widgets (optional)

        Yotpo offers a wide range of on-site widgets that you can add to your store in addition to our core features. View the list below and click the relevant link to learn more:

        Reviews Badge

        Reviews Widget Smart Filters

        Review Highlights

        Reviews Tab

        Promoted Products

        SEO Page

        Step 5 - Setting up conversion tracking

        Yotpo helps you leverage your reviews to drive traffic to your store, and increase your sales. The Conversion Tracking code enables you to measure those gains.

        Following each successful checkout submission, Yotpo validates if the visit and sale were generated by Yotpo or self-served.

        The Conversion Tracking code below should be loaded at the completion of each purchase, in the order confirmation page:

        <script type="text/javascript">(function e(){var e=document.createElement("script");e.type="text/javascript",e.async=true,e.src="//staticw2.yotpo.com/{{APP_KEY}}/widget.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t)})();</script><script>yotpoTrackConversionData = {orderId: "######ORDER_ID######", orderAmount: "######ORDER_AMOUNT#####", orderCurrency: "######ORDER_CURRENCY#####"}</script><noscript><img src="//api.yotpo.com/conversion_tracking.gif?app_key={{APP_KEY}}&order_id=######ORDER_ID######&order_amount=######ORDER_AMOUNT#####&order_currency=######CURRENCY######" width="1" height="1"></noscript>
        Important:

        Make sure to replace the two {{APP_KEY}} portions of the code with the App Key from your account. Please note that the brackets must be removed as well.

        Additionally, replace the ######ORDER_ID#####, ######ORDER_AMOUNT##### - total amount paid for the order, and ######ORDER_CURRENCY##### portions of the code with the correct placeholders.

        Can't find your App Key? Click here

        Additional resources


        Was this article helpful?