# Nosto

[Nosto](https://www.nosto.com/) is a digital commerce personalization platform that lets you personalize your customers' experience in real time.

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

In this document, you will learn how to add product recommendations from your Nosto account to your commercetools Frontend website.

**Prerequisites**

- A [Nosto account](https://my.nosto.com/auth/signup)
- [Nosto API tokens](https://help.nosto.com/en/articles/613616-settings-authentication-tokens) of [type](https://docs.nosto.com/techdocs/apis/rest#token-types) `API_PRODUCTS` and `API_APPS`

If the `content-nosto` 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-nosto` extension from [the scaffold repository](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/backend/content-nosto) to your project.
2. [Register the extension in your project](/frontend-development/extensions.md#define-extensions).

### Get started

To start using the Nosto 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 Nosto project configuration fields"
   {
     "name": "Commercetools Nosto Extension",
     "fields": [
       {
         "label": "API Token",
         "field": "EXTENSION_NOSTO_API_TOKEN",
         "type": "encrypted",
         "translatable": false,
         "required": true
       },
       {
         "label": "API URL",
         "field": "EXTENSION_NOSTO_API_URL",
         "type": "encrypted",
         "translatable": false,
         "required": true
       }
     ]
   }
   ```

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

   - In the **API Token** field, enter the Nosto `API_APPS` token.
   - In the **API URL** field, enter the [Nosto GraphQL endpoint](https://docs.nosto.com/techdocs/apis/graphql-an-introduction/graphql-using-the-api#sending-raw-graphql-queries).

## Deliver recommendations with the Nosto extension

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

1. [Update products on Nosto](/frontend-development/nosto.md#update-products-on-nosto).

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

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

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

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

### Update products on Nosto

To add product recommendations to your website, you first need to [update products on Nosto](https://docs.nosto.com/techdocs/apis/rest/products/updating-products-using-the-products-api) to synchronize your product catalog with the copy on Nosto.

### Upload the data source schema

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

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

```json title="Nosto Product Recommendations data source schema"
{
  "customDataSourceType": "nosto/product-recommendations",
  "name": "Nosto Product Recommendations",
  "category": "Content",
  "icon": "group",
  "schema": [
    {
      "name": "Configuration",
      "fields": [
        {
          "label": "Page Type",
          "field": "pageType",
          "type": "string",
          "translatable": false
        },
        {
          "label": "Nosto Placement ID",
          "field": "placementId",
          "type": "string",
          "translatable": false
        }
      ]
    }
  ]
}
```

### Create Frontend component

To render the product recommendations coming from the Nosto data source, you must create a Frontend component linked with the `nosto/product-recommendations` 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 Nosto product recommendations Frontend component"
   {
     "tasticType": "commercetools/ui/content/nosto/product-recommendations",
     "name": "Nosto product recommendations",
     "category": "Content",
     "icon": "list",
     "schema": [
       {
         "name": "Configuration",
         "fields": [
           {
             "label": "Nosto product recommendations",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "nosto/product-recommendations",
             "required": true
           }
         ]
       },
       {
         "name": "Layout",
         "fields": [
           {
             "label": "Nosto product recommendations page title",
             "field": "pageTitle",
             "translatable": true,
             "type": "string",
             "required": false,
             "default": ""
           }
         ]
       }
     ]
   }
   ```

2. Add the following `list.tsx` file under `components/commercetools-ui/content/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/product/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.variants[0].sku}
               className="mb-8 flex justify-center self-end md:mb-0"
             >
               <NextLink href={product._url}>
                 <a className="group">
                   <div className="relative w-52 rounded-lg transition-shadow hover:shadow-xl">
                     <Image
                       src={product.variants[0].images[0] || ''}
                       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/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/product/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/nosto-product-recommendations` to create a `NostoProductRecommendationsTastic` Frontend component that receives product recommendations from the `nosto/product-recommendations` data source and passes the `products` to the `ProductList` React component.

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

   const NostoProductRecommendationsTastic = ({ data }) => {
     const pageTitle = data.pageTitle;
     const recommendedProducts: [] =
       data?.data?.dataSource?.recommendedProducts;

     return (
       <ProductList
         pageTitle={pageTitle}
         products={recommendedProducts}
         totalProducts={recommendedProducts.length}
       />
     );
   };

   export default NostoProductRecommendationsTastic;
   ```

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

   ```tsx title="Register the NostoProductRecommendationsTastic 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/nosto/product-recommendations': NostoProductRecommendationsTastic,
   ...
   default: NotFound,
   };
   ```

### Add data sources and configure data source filters

Now you need to add the [**Nosto Product Recommendations** data source](/frontend-development/nosto.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 **Nosto 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, then save.

   - In the **Page Type** field, enter one of the following [Nosto page types](https://docs.nosto.com/techdocs/implementing-nosto/implement-on-your-website/manual-implementation/tag-your-page-types):

     - `cart`
     - `category`
     - `front`
     - `product`
     - `search`

   - In the **Nosto Placement ID** field, enter the `id` of the [Nosto static placement](https://help.nosto.com/en/articles/1883767-placements-general-article#h_115f5bdc0e) you want to use.

   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/nosto.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 **Nosto product recommendations** Frontend component to the **1/1** layout element.

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

6. In **Component settings** > **Layout** > **Nosto product recommendations page title** field, enter the title of the product recommendations page to be displayed on your website.

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

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

   To display on the page the product recommendations from Nosto, the Nosto target (`target`) and session ID (`session`) [parameters](https://docs.nosto.com/techdocs/apis/graphql-an-introduction/graphql-using-mutations/graphql-onsite-sessions) must be appended to the URL of the page as query parameters. The `session` parameter must be maintained on the client's website or mobile application and supplied to Nosto.

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

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Dynamic Yield](/frontend-development/dynamic-yield.md)
- [Next page: Talon.One](/frontend-development/talon-one.md)
- [Search documentation and API specs](/search.md)