Dynamic Yield

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 from the Studio.

   Add Dynamic Yield project configuration fieldsjson

   {
      "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 from the Studio.

   In the Host field, enter the value for the Dynamic Yield data center you are connected to.

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.

2. Upload the data source schema to the Studio.

3. Create the dedicated Frontend component.

4. Add data sources to the dedicated page folder and configure data source filters.

5. Add the Frontend component to a dedicated page version.

6. Report pageviews. 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. 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 in your Dynamic Yield account.

2. Create a product feed to support affinity-based personalization and product recommendations.

3. Create an API recommendation campaign for your website.

Upload the data source schema

The Dynamic Yield extension comes with the dynamicyield/product-recommendations-campaign data source to fetch product recommendations from Dynamic Yield.

To fetch the product recommendations from your recommendation campaign, you must upload to the Studio the following 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.

   Schema of Dynamicyield product recommendations Frontend componentjson

   {
     "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.

   List React componentTypeScript React

   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.

   ProductList React componentTypeScript React

   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.

   ProductRecommendationsTastic Frontend componentTypeScript React

   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.

   Register the ProductRecommendationsTastic Frontend componentTypeScript React

   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 to the page folder 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. 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 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.
   • 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.
   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.

Add Frontend component to the page version

Finally, you must add the Frontend component you created to the page version 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. 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 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.

4. Use the 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.

   

6. Preview and save 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 must be appended to the URL of the page as query parameters.