npm package: @frontend-sdk/yotpo
Description: Yotpo integration for Shogun Frontend.
Author: Shogun
Latest version: 0.25.1

# Yotpo

Yotpo integration for Shogun Frontend.

> Yotpo's eCommerce marketing platform offers the most advanced solutions for customer reviews, visual marketing, loyalty, referrals, and SMS marketing.

<table>
  <tbody>
    <tr>
      <td>⚠️</td>
      <td>This package runs on Shogun Frontend and is in customer Beta. It might not currently support all ecommerce platforms or cover all use cases.</td>
    </tr>
  </tbody>
</table>

[Yotpo website →](https://www.yotpo.com)

### Installation

`yarn add @frontend-sdk/yotpo`

`npm install @frontend-sdk/yotpo`

---

## Yotpo Reviews & Ratings

### Usage

1. Find your Yotpo App Key [here](https://support.yotpo.com/en/article/finding-your-yotpo-app-key-and-api-secret). Inject Yotpo's script with your App Key:

   ```jsx
   import { useYotpoReviews } from '@frontend-sdk/yotpo'
   const App = () => {
     useYotpoReviews('<insert Yotpo’s App Key here>')
     return <>…</>
   }
   ```

2. Add `div` with one of supported classes (from [official docs](https://support.yotpo.com/en/article/generic-other-platforms-installing-yotpo)):

   - Reviews Widget (`yotpo yotpo-main-widget`):

     ```jsx
     const ReviewsWidget = () => {
       return (
         <div
           className="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>
       )
     }
     ```

   - Star Rating (`yotpo bottomLine`):

     ```jsx
     const StarRating = () => {
       return <div className="yotpo bottomLine" data-yotpo-product-id="<SKU / Product ID>"></div>
     }
     ```

   - UGC Gallery (`yotpo-pictures-widget`):

     ```jsx
     const Gallery = () => {
       return <div class="yotpo yotpo-pictures-widget" data-gallery-id="<Gallery ID>"></div>
     }
     ```

3. Use `useYotpoReviewsRefresh` hook when widget needs to be updated:

   ```jsx
   import { useYotpoReviewsRefresh } from '@frontend-sdk/yotpo'

   const Component = () => {
     useYotpoReviewsRefresh()
     return <>…</>
   }
   ```

### Links

- [Help Center: Installation ](https://support.yotpo.com/en/article/generic-other-platforms-installing-yotpo-v3) (v3, updated in April 2021)
- [Help Center: `refreshWidgets` API](https://support.yotpo.com/en/article/loading-yotpo-with-ajax)
- [Get Started: Installation](https://yap.yotpo.com/get-started/#/install/integrate/step2) (must be logged-in in Yotpo app)

---

## Yotpo Loyalty & Referrals

### Usage

#### Basic

0. Prerequisites:

   - Find your Yotpo Loyalty `GUID` in [Settings → General](https://loyalty.yotpo.com/general-settings).
   - Enable customer accounts on your ecommerce platform (e.g., [Shopify docs](https://help.shopify.com/en/manual/checkout-settings/customer-accounts)).

1. Use `useYotpoLoyalty` hook at pages where you want Yotpo Loyalty functionality (e.g., product pages, rewards page)

   ```jsx
   import { useYotpoLoyalty } from '@frontend-sdk/yotpo'
   const App = () => {
     useYotpoLoyalty('<Yotpo Loyalty GUID>')
     return <>…</>
   }
   ```

2. Add `div` element with customer information so Yotpo can identify them ([docs](https://support.yotpo.com/en/article/implementing-loyalty-referrals-on-a-custom-or-generic-ecommerce-platform#customer-identification)).

   ```jsx
   const Customer = () => {
     return (
       <div
         id="swell-customer-identification"
         data-authenticated="true"
         data-email={'<customer email>'}
         data-id={'<customer ID>'} // ID in your ecommerce platform
         data-tags="['<tag 1>', '<tag 2>', …]"
         style={{ display: 'none' }}></div>
     )
   }
   ```

3. If you want to use [On-site Modules](https://support.yotpo.com/en/loyalty-referrals/on-site-modules):
   - Customize them in the Yotpo Loyalty admin.
   - Place the provided snippet in a section or component in the Frontend.

That's it!
After Yotpo app is loaded, you should see Yotpo modules.

#### Advanced

If you need more control over the Yotpo Loyalty SDK, `@frontend-sdk/yotpo` can also provide:

- `loading` state (whether Yotpo script is loaded)
- `error` information (in case of timeout, for example)
- Yotpo Loyalty SDK methods (at the moment only the method to show the Rewards Popup module)

You can also control:

- _threshold_ — time before throwing timeout error if Yotpo Loyalty SDK is not loaded
- _interval_ — how often to check whether the SDK is loaded

Here is an example of how to provide a button to show Rewards Popup module

```jsx
import { useYotpoLoyalty } from '@frontend-sdk/yotpo'
const RewardsPage = () => {
  const { loading, error, yotpoLoyalty } = useYotpoLoyalty(
    '<GUID>',
    '<threshold in milliseconds>',
    '<interval in milliseconds>',
  )
  const onClick = () => {
    yotpoLoyalty?.showRewardsModal()
  }
  return (
    <>
      <button type="button" onClick={onClick} disabled={loading || error instanceof Error}>
        {loading ? 'Loading…' : error ? 'Error' : 'Open Rewards modal'}
      </button>

      {error instanceof Error && (
        <code>
          <b>Error:</b> {error.message}.
        </code>
      )}
      <div
        id="swell-customer-identification"
        data-authenticated="true"
        data-email={'…'}
        data-id={'…'}
        style={{ display: 'none' }}></div>
    </>
  )
}
```

### Links

- [Help Center: Implementing Loyalty & Referrals on a Custom or Generic eCommerce Platform](https://support.yotpo.com/en/article/implementing-loyalty-referrals-on-a-custom-or-generic-ecommerce-platform#customer-identification)
- [Help Center: On-site Modules](https://support.yotpo.com/en/loyalty-referrals/on-site-modules)