# Dynamic Yield

[Dynamic Yield](https://www.dynamicyield.com/) is a platform-as-a-service (PaaS) that lets you personalize your customers' experience in real time.
Dynamic Yield provides tailored recommendations and promotions to individual customers by analyzing their behavior.

commercetools Frontend comes with an out-of-the-box extension to integrate Dynamic Yield in your commercetools Frontend project.

For demonstration purposes, in this document, you will learn how to add product recommendations to your commercetools Frontend website from the recommendation campaign you created in your Dynamic Yield account.

**Prerequisites**

- A [Dynamic Yield account](https://adm.dynamicyield.com/users/sign_in)
- A [Dynamic Yield API key](https://support.dynamicyield.com/hc/en-us/articles/360022734893-API-Keys#create-an-api-key-0-1) for server-side API calls

If the `content-dynamicyield` extension is not available in your commercetools Frontend project at this path `packages/PROJECT_NAME/backend`, before proceeding with the following configurations, you must:

1. Copy the `content-dynamicyield` extension from [the scaffold repository](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/backend/content-dynamicyield) to your project.
2. [Register the extension in your project](/frontend-development/extensions.md#define-extensions).

### Get started

To start using the Dynamic Yield extension in your commercetools Frontend project, follow these steps:

1. [Add the following project configuration fields to the project schema](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) from the Studio.

   ```json title="Add Dynamic Yield project configuration fields"
   {
      "name": "Commercetools Dynamicyield Extension",
      "fields": [
        {
          "label": "API Key",
          "field": "EXTENSION_DYNAMICYIELD_API_KEY",
          "type": "encrypted",
          "translatable": false,
          "required": true
        },
        {
          "label": "Host",
          "field": "EXTENSION_DYNAMICYIELD_HOST",
          "type": "encrypted",
          "translatable": false,
          "required": true
        }
      ]
    },
   ```

2. [Set the Dynamic Yield configuration values](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) from the Studio.

   In the **Host** field, enter the value for the [Dynamic Yield data center you are connected to](https://support.dynamicyield.com/hc/en-us/articles/360007593797--Early-Access-Creating-and-Syncing-a-Product-Feed-Using-APIs-#creating-api-calls-0-3).

## Deliver recommendations with the Dynamic Yield extension

To deliver product recommendations with the Dynamic Yield extension, follow these steps:

1. [Create a Dynamic Yield recommendation campaign](/frontend-development/dynamic-yield.md#create-a-dynamic-yield-recommendation-campaign).

2. [Upload the data source schema to the Studio](/frontend-development/dynamic-yield.md#upload-the-data-source-schema).

3. [Create the dedicated Frontend component](/frontend-development/dynamic-yield.md#create-frontend-component).

4. [Add data sources to the dedicated page folder and configure data source filters](/frontend-development/dynamic-yield.md#add-data-sources-and-configure-data-source-filters).

5. [Add the Frontend component to a dedicated page version](/frontend-development/dynamic-yield.md#add-frontend-component-to-the-page-version).

6. [Report pageviews](https://support.dynamicyield.com/hc/en-us/articles/360010439538-Reporting-Pageviews#reporting-pageviews-0-0). Make sure pageviews are reported to Dynamic Yield to track statistics before fetching recommendations.

   For page reporting and recommendations fetching, Dynamic Yield requires the Dynamic Yield user ID (`user`) and Dynamic Yield session ID (`session`) [parameters](https://support.dynamicyield.com/hc/en-us/articles/9675297422493-Recommendations-Campaigns-for-Experience-API-Sites#h_01FPSJFZ3QRZ713AZVBT097M9J). The parameters must be maintained on the client's website or mobile application and supplied to Dynamic Yield.

### Create a Dynamic Yield recommendation campaign

To add product recommendations to your website, you first need to create a Dynamic Yield recommendation campaign.

To create a recommendation campaign, follow these steps:

1. [Create a new site](https://support.dynamicyield.com/hc/en-us/articles/360022833894-Managing-Sites#creating-a-new-site-0-1) in your Dynamic Yield account.

2. [Create a product feed](https://support.dynamicyield.com/hc/en-us/articles/360038581394-Product-Feeds#product-feeds-0-0) to support affinity-based personalization and product recommendations.

3. [Create an API recommendation campaign](https://support.dynamicyield.com/hc/en-us/articles/9675297422493-Recommendations-Campaigns-for-Experience-API-Sites#h_01FPSJFQMHFM5PHY4AY8S8FZV3) for your website.

### Upload the data source schema

The Dynamic Yield extension comes with the `dynamicyield/product-recommendations-campaign` [data source](/frontend-development/development-concepts.md#data-sources) to fetch product recommendations from Dynamic Yield.

To fetch the product recommendations from your recommendation campaign, you must [upload to the Studio](/frontend-studio/using-data-sources-in-the-studio.md) the following data source schema:

```json title="DynamicYield Product Recommendations data source schema"
{
  "customDataSourceType": "dynamicyield/product-recommendations-campaign",
  "name": "DynamicYield Product Recommendations",
  "category": "Content",
  "icon": "group",
  "schema": [
    {
      "name": "Configuration",
      "fields": [
        {
          "label": "Campaign Selector Name",
          "field": "campaignSelectorName",
          "type": "string",
          "translatable": false
        },
        {
          "label": "Page Context Type",
          "field": "pageContextType",
          "type": "string",
          "translatable": false
        }
      ]
    }
  ]
}
```

### Create Frontend component

To render the product recommendations coming from the Dynamic Yield data source, you must create a Frontend component linked with the `dynamicyield/product-recommendations-campaign` data source.

In this example, we create the Frontend component to display a list of recommended products.

To create the Frontend component, follow these steps:

1. Create the Frontend component schema by [uploading the following schema to the Studio](/frontend-development/creating-a-frontend-component.md#create-a-frontend-component-schema).

   ```json title="Schema of Dynamicyield product recommendations Frontend component"
   {
     "tasticType": "commercetools/ui/content/dynamicyield/product-recommendations",
     "name": "Dynamicyield product recommendations",
     "category": "Content",
     "icon": "list",
     "schema": [
       {
         "name": "Configuration",
         "fields": [
           {
             "label": "Dynamicyield product recommendations campaign",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "dynamicyield/product-recommendations-campaign",
             "required": true
           }
         ]
       }
     ]
   }
   ```

2. Add the following `list.tsx` file under `components/commercetools-ui/content/dynamicyield/product-recommendations` to create a `List` React component that renders the list of products received as props.

   ```tsx title="List React component"
   import React from 'react';
   import NextLink from 'next/link';
   import { Product } from '@Types/content/dynamicyield/Product';
   import { useFormat } from 'helpers/hooks/useFormat';
   import Image from 'frontastic/lib/image';
   import Price from '../../price';

   interface Props {
     products: Product[];
     filtering?: boolean;
   }

   const List: React.FC<Props> = ({ products, filtering }) => {
     //i18n messages
     const { formatMessage: formatProductMessage } = useFormat({
       name: 'product',
     });

     return (
       <div className="mx-auto max-w-2xl pt-8 pb-16 lg:max-w-7xl">
         <h2 className="sr-only">
           {formatProductMessage({
             id: 'products',
             defaultMessage: 'Products',
           })}
         </h2>
         <ul
           className={`grid grid-cols-1 align-bottom sm:grid-cols-2 md:grid-cols-3 md:gap-x-12 md:gap-y-16 lg:grid-cols-${
             filtering ? '3' : '4'
           }`}
         >
           {products?.map((product) => (
             <li
               key={product.sku}
               className="mb-8 flex justify-center self-end md:mb-0"
             >
               <NextLink href="https://commercetools.com">
                 <a className="group">
                   <div className="relative w-52 rounded-lg transition-shadow hover:shadow-xl">
                     <Image
                       src={product.imageUrl || ''}
                       alt={product.name}
                       layout="fill"
                       className="rounded-lg"
                     />
                   </div>
                   <h3 className="mt-4 w-52 overflow-hidden truncate text-lg font-bold text-gray-700 dark:text-light-100">
                     {product.name}
                   </h3>
                   <div className="flex">
                     <Price
                       price={product.price}
                       className={`text-sm text-gray-900 dark:text-light-100`}
                     />
                   </div>
                 </a>
               </NextLink>
             </li>
           ))}
         </ul>
       </div>
     );
   };

   export default List;
   ```

3. Add the following `index.tsx` file under `components/commercetools-ui/content/dynamicyield/product-recommendations` to create a `ProductList` React component that renders a list of products using the `List` React component you created.

   ```tsx title="ProductList React component"
   import { Product } from '@Types/content/dynamicyield/Product';
   import List from './list';
   import { useFormat } from 'helpers/hooks/useFormat';

   export interface Props {
     products: Product[];
     totalProducts: number;
   }

   export default function ProductList({ products, totalProducts }: Props) {
     const { formatMessage: formatProductMessage } = useFormat({
       name: 'product',
     });

     return (
       <div className="mt-10 px-1 sm:px-3 lg:px-6">
         <div className="mt-8 gap-16 lg:grid lg:grid-cols-3">
           <p>Product Recommendations</p>
           <h6 className="col-span-2 hidden text-right dark:text-light-100 lg:block">
             {`${products.length} ${formatProductMessage({
               id: 'items',
               defaultMessage: 'Items',
             })} ${totalProducts}`}
           </h6>
         </div>
         <div className="mt-10 px-1 sm:px-3 lg:px-6">
           <List products={products} />
         </div>
       </div>
     );
   }
   ```

4. Add the following `index.tsx` file under `tastics/content/dynamicyield/product-recommendations` to create a `ProductRecommendationsTastic` Frontend component that receives product recommendations from
   the `dynamicyield/product-recommendations-campaign` data source and passes the `products` to the `ProductList` React component.

   ```tsx title="ProductRecommendationsTastic Frontend component"
   import ProductList from 'components/commercetools-ui/content/dynamicyield/product-recommendations';

   const ProductRecommendationsTastic = ({ data }) => {
     if (!data?.data?.dataSource) return <></>;
     const productRecommendationsResult = data?.data?.dataSource;
     const items = productRecommendationsResult.items;
     const totalItems = productRecommendationsResult.items.length;
     return <ProductList products={items} totalProducts={totalItems} />;
   };

   export default ProductRecommendationsTastic;
   ```

5. Register the `commercetools/ui/content/dynamicyield/product-recommendations` Frontend component in the `frontastic/tastic/index.tsx` file.

   ```tsx title="Register the ProductRecommendationsTastic Frontend component" highlightLines="8"
   export const tastics = {
   ...
   'commercetools/ui/checkout': Checkout,
   'commercetools/ui/thank-you': ThankYou,
   'commercetools/ui/cart': Cart,
   'commercetools/ui/footer': Footer,
   'commercetools/ui/header': Header,
   'commercetools/ui/content/dynamicyield/product-recommendations': ProductRecommendationsTastic,
   'commercetools/ui/content/tile': Tile,
   'commercetools/ui/content/spacer': Spacer,
   'commercetools/ui/content/showcase': Showcase,
   ...
   default: NotFound,
   };
   ```

### Add data sources and configure data source filters

Now you need to add the [**DynamicYield Product Recommendations** data source](/frontend-development/dynamic-yield.md#upload-the-data-source-schema) to the [page folder](/frontend-studio/page-folders.md) where you want to render the content, then you need to configure the data source filters.

To add the data sources to the page folder and configure the data source filters, follow these steps:

1. If necessary, [create a page folder](/frontend-studio/page-folders.md#create-a-page-folder). Otherwise, from the Studio home page or from the left menu, go to **Site builder**.

2. In the page folder list, hold the pointer over the page folder where you want to render the content and click the **Settings** icon: the **Page folder settings** dialog opens.

3. In the **Data source** section, click **+ Add data source filter**: the list of the available data sources opens. From the list, select the **DynamicYield Product Recommendations** data source. When you select a data source, the [data source filter editor](/frontend-studio/using-the-data-source-filter-editor.md) opens.

4. Configure the data source filter as follows and save:

   - In the **Campaign Selector Name** field, enter the campaign selector name for the [campaign you created](/frontend-development/dynamic-yield.md#create-a-dynamic-yield-recommendation-campaign).
   - In the **Page Context Type** field, enter the page context to be adopted for recommendations. For more details about page context type, see [Page context types](https://support.dynamicyield.com/hc/en-us/articles/4414492810769-Choosing-Variations-and-Pageviews#h_01G9YHNAX52HX3G0WNYVZYCWXJ).

   You can also manage data source filters from the page builder, the **Templates** area, and the **Dynamic pages** area. For more information, see [Using the data source filter editor](/frontend-studio/using-the-data-source-filter-editor.md).

### Add Frontend component to the page version

Finally, you must add the [Frontend component you created](/frontend-development/dynamic-yield.md#create-frontend-component) to the [page version](/frontend-studio/page-versions.md) where you want to render the content. Thus, the data retrieved from the data source is rendered on the page version through the Frontend component.

To add the Frontend component to the page version, follow these steps:

1. If necessary, [create a page version](/frontend-studio/page-versions.md#create-a-page-version). Otherwise, from the Studio home page or from the left menu, go to **Site builder**.

2. Use the page folder list and the status sections to navigate to the page version where you want to add the Frontend component. Then, hold the pointer over the page version and click the **Edit** icon: the [page builder](/frontend-studio/using-the-page-builder.md) opens.

3. Edit the layout of the page version as you wish. In this example, we add a **1/1** layout element to the **MAIN** [layout section](/frontend-studio/using-the-page-builder.md#layout-section).

4. Use the [**Components** pane](/frontend-studio/using-the-page-builder.md#components-pane) to find the Frontend component to add. Then, drag it to the layout element. In this example, we drag the **Dynamicyield product recommendations** Frontend component to the **1/1** layout element.

5. Select the Frontend component, then, in **Component settings > Content** select the **Dynamicyield Product Recommendations** data source.

   ![The Dynamicyield product recommendations Frontend component and the Component settings section in the page builder](https://docs.commercetools.com/frontend-development/images/dynamic-yield-page-version.png)

6. [Preview and save](/frontend-studio/using-the-page-builder.md#menu-bar) your changes. Your Dynamic Yield product recommendations are now displayed on your commercetools Frontend website.

   To display on the page the product recommendations from Dynamic Yield, the Dynamic Yield user ID (`user`) and Dynamic Yield session ID (`session`) [parameters](https://support.dynamicyield.com/hc/en-us/articles/9675297422493-Recommendations-Campaigns-for-Experience-API-Sites#h_01FPSJFZ3QRZ713AZVBT097M9J) must be appended to the URL of the page as query parameters.

   ![A preview page with a product recommendation from Dynamic Yield](https://docs.commercetools.com/frontend-development/images/dynamic-yield-preview.png)

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Contentstack](/frontend-development/contentstack.md)
- [Next page: Nosto](/frontend-development/nosto.md)