Nosto

Nosto 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
Nosto API tokens of type 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:

Clone the extension repository and add the code to your project.
Register the extension in your project.

Get started

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

Add the following project configuration fields to the project schema from the Studio.

Add Nosto project configuration fieldsjson

{
  "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
    }
  ]
}

Set the Nosto configuration values from the Studio:
- In the API Token field, enter the Nosto API_APPS token.
- In the API URL field, enter the Nosto GraphQL endpoint.

Deliver recommendations with the Nosto extension

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

Update products on Nosto.
Upload the data source schema to the Studio.
Create the dedicated Frontend component.
Add data sources to the dedicated page folder and configure data source filters.
Add the Frontend component to a dedicated page version.

Update products on Nosto

To add product recommendations to your website, you first need to update products on Nosto 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 to fetch product recommendations from Nosto.

To fetch the product recommendations from your Nosto account, you must upload to the Studio the following data source schema:

Nosto Product Recommendations data source schemajson

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

Create the Frontend component schema by uploading the following schema to the Studio.

Schema of Nosto product recommendations Frontend componentjson

{
  "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": ""
        }
      ]
    }
  ]
}

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.

List React componentTypeScript React

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;

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.

ProductList React componentTypeScript React

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>
  );
}

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.

NostoProductRecommendationsTastic Frontend componentTypeScript React

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;

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

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 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:

If necessary, create a page folder. Otherwise, from the Studio home page or from the left menu, go to Site builder.
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.
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 opens.
Configure the data source filter as follows, then save.
- In the Page Type field, enter one of the following Nosto page types:
  - cart
  - category
  - front
  - product
  - search
- In the Nosto Placement ID field, enter the id of the Nosto static placement 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.

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:

If necessary, create a page version. Otherwise, from the Studio home page or from the left menu, go to Site builder.
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.
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.
Use the 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.
Select the Frontend component, then, in Component settings > Content select the Nosto Product Recommendations data source.
In Component settings > Layout > Nosto product reccomendations page title field, enter the title of the product reccomendations page to be displayed on your website.
Preview and save 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 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.