Integrating Yotpo Reviews with Salesforce Commerce Cloud

Yotpo’s suite of integrated solutions for user-generated content marketing helps commerce companies accelerate growth by enabling advocacy and maximizing customer lifetime value. With Yotpo, brands can effectively leverage social proof to increase trust and sales and make better business decisions based on real customer feedback.

This document provides a technical overview and instructions for installing and using Yotpo's Salesforce Commerce Link Cartridge, enabling you to integrate various Yotpo features within a Salesforce Commerce storefront.

Merchants using Yotpo's Salesforce Commerce Link Cartridge can access the following features:

• Product Review Widget
• Star Rating Widget
• Automatic Review Request Emails

Functional overview

Following is the list of features implemented in the Yotpo Link cartridge integration:

• Product Widgets
  • Product Review Widget
  • Star Rating Widget
• Automatic Review Request Emails
  • Order Export
• Analytics
  • Purchase conversion tracking

Privacy and payment

• Masked Order Information and Aggregate Sales Information may be captured as part of purchase tracking implementation on the site
• No customer-specific profile data or sensitive information will be stored related to Yotpo LINK cartridge
• The Yotpo LINK cartridge itself is available free of charge. See the Limitations & Constraints section below for details regarding potential costs involved with enabling Yotpo to start collecting reviews on your behalf
• In using the Yotpo LINK cartridge, you agree to Yotpo's Terms of Service

Limitations and constraints

• To use the Salesforce Commerce Link Cartridge, you must be subscribed to an eligible Yotpo premium plan. 
• Use of the Yotpo LINK cartridge by itself does not grant nor enable the use of Yotpo product offerings. You must first enter a contractual agreement with Yotpo for Yotpo to start collecting reviews on behalf of your business. 
• To learn more, please reach out to Yotpo Sales at: sales@yotpo.com

Use cases

Setup and configuration

The Yotpo LINK integration makes use of the following cartridges: 

Cartridge registration

1. Navigate to the following path:

• Administration > Manage Sites  > Select Relevant Site  >  Settings

2. Add cartridge names to the Cartridges path as demonstrated in each expandable section below:

SiteGenesis Controller Cartridge configuration

The Yotpo cartridge relies on a “guard” script from SiteGenesis Controller cartridge if the integration is being implemented with controller version. The default name used is:  app_storefront_controllers 

If the controller cartridge name differs from the default name, change; exports.SITEGENESIS_CARTRIDGE_NAME = "app_storefront_controllers";

In int_yotpo/cartridge/scripts/yotpo/utils/Constants.js

Import Yotpo metadata services and jobs schedules

1. Retrieve the metadata.zip file from the Yotpo cartridge’s Metadata folder:
2. Navigate to Administration > Site Development > Site Import & Export
3. Select the metadata.zip file and 
4. Click on Import and complete the import process through the interface
   1. The Jobs, Services, Site Preferences, Custom Objects will be imported including Yotpo Configurations and Yotpo Jobs Configurations.
   2. The details on job schedules and services is described in section 3.3 and 3.4 respectively.
   3. The details on Yotpo Custom Preferences is described in section  5.2.1. For further details on configuring custom objects see section 5.2.2 and 5.2.3.

Job details

Services details

Navigate to Administration > Services

After successfully importing services, the following will be added:

Authentication service

Navigate to Administration > Operations > Services > Click on the Credentials tab

The URL for the authentication token API could be set in int_yotpo.https.post.auth.api.cred

Export purchase service

The URL for Export Post API could be set in int_yotpo.https.post.export.purchase.api.cred

Import review service

URL for importing review could be set in int_yotpo.http.post.import.reviews.api.cred

Custom code pipelines and controllers

Adding Yotpo JavaScript
For widgets and conversion tracking to work, Yotpo's JavaScript must be included in storefront header file i.e. htmlhead.isml:

<isinclude template="include/yotpoheader" />

Adding Yotpo Modules

In order to add widgets and tracking modules make sure the Yotpo module modules are added on the top of each template. Copy the below code snippet:

<isinclude template="util/yotpomodules.isml" />

Adding Product Review Widget
Product Review Widget can be added to any product page in your store.

To add the Product Review Widget include the following Yotpo widget definition code snippet to the desired page e.g. at the end of product details block in productcontent.isml

Pipelines Version

<isyotporeviewswidget product="${pdict.Product}"  ispipeline="true" yotporeviewspage="1" isreview="true" />

Controllers Version

<isyotporeviewswidget product="${pdict.Product}" yotporeviewspage="1" isreview="true" />

yotporeviewspage is set to 1, but this can set to any arbitrary value to fetch specific review page. isreview should be set to true for loading reviews.

Yotpo reviews are fetched from Yotpo in real-time and response is rendered by yotporeviewsresponse.isml. The page is cached for 24 hours for performance concerns, which can be adjusted in the template.

Adding the Star Rating widget on product pages

The Star Rating Widget can be added to a product page template.

To add Star Rating Widget include the following Yotpo widget definition code snippet to the desired page e.g. after product ID in productcontent.isml

<isyotpoproductbottomlinewidget product="${pdict.Product}" />

Adding the Star Rating widget to category pages

To add Star Rating Widget on Category/Search page, include following code snippet at top of the page e.g in categoryproducthits.isml

<isyotpocategorybottomlineheader />

And then add the following code snippet in the box below, to the desired page e.g in producttile.isml after or before the following code snippet.

<isif condition="${showrating && !Product.productSet}">

        <isinclude template="product/components/reviewsmini"/>

</isif>

<isyotpocategorybottomlinewidget product="${pdict.product}" />

Adding purchase conversion tracking

Conversion Tracking should be added in “confirmation page” in your store.

In order to enable Conversion Tracking include following code snippet to the confirmation page i.e. at the end of confirmation.isml 

<isyotpoconversiontracking order="${pdict.Order}" />

Adding Conversion Tracking widget

Conversion Tracking should be added in confirmation page in your store.

In order to enable Conversion Tracking, override any of order confirmation template e.g. confirmation.isml and include following code snippet;

<isinclude template="tracking/yotpoconversiontracking" />

Custom Code SFRA

The SFRA overridden templates resides in int_yotpo_sfra. SFRA architecture doesn’t allow extending template functionality therefore complete templates are overridden. It is highly recommended to copy the specific code only, if other cartridges have customised their functionality. The details of default overridden templates are described below.

Adding Yotpo JavaScript

For widgets and conversion tracking to work, Yotpo's dynamic JavaScript must be included in SFRA storefront header file i.e. htmlhead.isml

<isinclude template="include/yotpoheader" />

See default overridden templates in the cartridge for reference:

• /int_yotpo_sfra/cartridge/templates/default/common/htmlHead.isml

Adding Product Review Widget

Product reviews can be added to any product page in your store.

To add product reviews, override the desired template and include the following code snippet in e.g. descriptionAndDetails.isml

<isinclude template="widget/yotporeviewswidget" />

• See default overridden templates in the cartridge for reference: /int_yotpo_sfra/cartridge/templates/default/product/components/descriptionAndDetails.isml

Adding Product Ratings Widget (Category and PDP)

Product ratings can be added to any product page/tile in your store.

To add product ratings override the desired template and include the following code snippet in e.g. productRating.isml for Product Details Page and ratings.isml for Category/Search pages.

<isinclude template="widget/yotporatingswidget" />

See default overridden templates in the cartridge for reference:

• /int_yotpo_sfra/cartridge/templates/default/product/components/productRating.isml
• /int_yotpo_sfra/cartridge/templates/default/product/components/ratings.isml

Adding Conversion Tracking Widget

Conversion Tracking should be added in confirmation page in your store.

In order to enable Conversion Tracking override any of order confirmation template e.g. confirmation.isml and include following code snippet;

<isinclude template="tracking/yotpoconversiontracking" />

See default overridden templates in the cartridge for reference:

• /int_yotpo_sfra/cartridge/templates/default/checkout/confirmation/confirmation.isml

Testing

To see a demo of product reviews and Star Rating visit the following pages:

• http://yotpo01-tech-prtnr-eu01-dw.demandware.net/s/SiteGenesis/en_US/womens/clothing/tops/25518058.html
• http://yotpo01-tech-prtnr-eu01-dw.demandware.net/s/MobileFirst/black-single-pleat-athletic-fit-wool-suit/750518699578.html 

Data storage

Order Custom Attributes

Availability

Yotpo services are based on a high-availability infrastructure and have 99.9% uptime. If Yotpo endpoints go down and your pages are unable to get reviews from our servers, the Yotpo reviews and Star Rating will simply not show, it won’t degrade or break your page in any way.

User guide

Roles and responsibilities

Yotpo Export Orders job should be scheduled to run at least once daily.

Make sure enablePurchaseFeed, enableReviews, and enableBottomLine is enabled in:

Merchant Tools > Custom Objects > Custom Objects Editor > Yotpo Configurations for a specific locale to make ratings, reviews, or conversation tracking work.

Business Manager

Yotpo Site Preferences

The Yotpo LINK cartridge consists of the following configuration properties in:

• Site > Site Preferences > Custom Preferences > Yotpo Configs
  

Setting up yotpoConfiguration

1. Navigate to Merchant Tools > Custom Objects > Custom Object Editor
2. Select yotpoConfigurations
3. Click New
   
4. Configure the your values in the relevant fields:
   1. Refer to the table below if you need help.
      

Set up the yotpoJobsConfiguration

Select yotpoJobsConfigurations and press New as shown in the screenshot below: