1 of 100

Techdocs

Introduction

This guide introduces you how to implement Nosto on a e-commerce store that does not yet have a dedicated plugin solution. The articles are designed as digestable step-by-step guides that walk you through how to establish the data exchange between the site and Nosto.

First its important to understand a few of the concepts before delving in to the documentation, to make sure that you as a integrator understand the different steps and tools required.

Nosto initializes by using a snippet of Javascript that starts the dialogue to your dedicated account.
Nosto depends on structured data that we extract from your site. At the bare minimum you need to go through all the steps listed under Manual Implementation - Essentials.
You can augment and extend the product tagging and the data collection process with the help of other articles found under this guide.
You can access your own account in the Nosto admin UI my.nosto.com/admin where you can enable/configure/modify features. All templating and layouts are handled within your account.

In case you have already implemented Nosto and established continuous data exchange you can find more information related to troubleshooting or setting up features at help.nosto.com.

Implementation Checklist

As a first step, please check if your e-commerce platform or software is already supported by a Nosto extension or integration. In case the platform is supported we warmly recommend to use an extension and reading the platform specific guide as this saves you some manual effort and time, since the implementation process differs a bit from the one described in this article series and practically automates all the steps.

Second, make sure that you have a Nosto account and if not, sign up on Nosto home page or contact Nosto sales.

Every Nosto account has a unique identifier known as accountID, which is required in the implementation. If you know that you have an account, but don’t know your accountID, log-in to your Nosto admin panel and learn where you can find it!

Third, if you first implement Nosto on a local device or on a development environment, bookmark this article about implementing Nosto on a test environment for later reading. No need to jump there yet, as it is also featured as the last article in this series.

Implementing Nosto

Implement on your website

Choosing the implementation method

Most customers implement Nosto by installing a Nosto extension to their e-commerce platform. The extension provides a working out of the box implementation for majority of websites handling installing tagging and product updates. However, for customized PWA/SPA environments, you should follow the additional SPA/PWA guides.

Implementing by a Nosto Extension

Implement on your SPA

Implement on your PWA

Implement on your Headless

Implement on a standard e-commerce store

When implementing in SPA and PWA environments, product updates must be done via REST API. In case you are using some of the platforms that Nosto has extension for the extension takes care of the product updates.

SPA / PWA on top of a platform that Nosto has extension for

If you have implemented SPA / PWA on top a platform that Nosto has extension for you will still need to implement the frontend part using Session API. The extension will take care of the product updates, order confirmations, exchange rates and other background processes but displaying the recommendations, popups, etc. must be done using Session API.

When dynamic functionality is needed / no page reload

In case your website implement some dynamic functionality, you can use the JS API. Note that you cannot mix Session API and Page Tagging.

Manual Implementation - Essentials

To implement Nosto manually you will need to go through the following steps to ensure that the store data is captured by Nosto. The following steps will allow Nosto to gather product, cart and order data, and analyze how individual customers are interacting with this data. The implementation steps listed here are necessary for both functionalities based on crowd logic and 1-1 behavioral personalization.

Manual Implementation - Essentials
Advanced Usage
FAQ

If the store is built on explicitly supported platforms like Magento, Magento 2, Shopify, Prestashop or Shopware you should go through their platform specific guides instead.

The tagging context can be provided in two ways

programmatically via tagging providers
as dedicated Nosto elements in page markup

We recommend to utilize tagging providers due to the following benefits

tagging can be dynamically changed in JS without writing to the DOM
tagging context can be provided much earlier, since script tags can also be placed in head element

It is possible to mix DOM based tagging and tagging providers in case the main tagging is provided as HTML elements, but individual parts should be managed via Javascript code dynamically. Also both DOM and tagging provider based tagging are treated in the same way in the client script and debug toolbar.

Setting up your account

You must use a valid domain for your website. If you are creating a test account and running your store locally, you must use valid TLD as using localhost is not supported.

You cannot use the following domains as they are reserved by the IANA.

.test
.example
.localhost
.invalid
.local
.localdomain
.domain
.lan
.home
.corp
.wip

We recommend using a valid official TLD that is aliased to localhost for testing purposes. You will need to edit your operating-system dependent hosts file to add an alias for the domain you are using.

Nosto periodically crawls your website to keep the catalog data in sync and therefore if you run your webshop locally, Nosto will be unable to crawl your website. In order to overcome this, you will either need to:

make it publicly available using a service such as Pagekite or Ngrok
Use the Products API to keep your catalog in sync

Adding the Nosto Script

To start tracking visits and content the Nosto script needs to be active on all pages within the store where the user might navigate. Replace $accountID from the code below with your own account ID and place the code within the <head> section of your sites HTML content. You can find your stores account IDs from the account list within the Nosto admin.

<script type="text/javascript">
    (function(){var name="nostojs";window[name]=window[name]||function(cb){(window[name].q=window[name].q||[]).push(cb);};})();
</script>
<script src="https://connect.nosto.com/include/$accountID" async></script>

Note: The script and the snippet should be added as high up in the <head> portion of the page so the connection is initialized as soon as possible. As the script is flagged async, the page load isn’t delayed.

Note: This needs to exist on every page.

Alternatively to the script injection Nosto can also be used as a library dependency in your Javascript application via the following utility library Nosto Js

Troubleshooting Nosto script:

Once included on all pages, you can review if the site is transmitting data using the Nosto Debug Toolbar. If the debug toolbar executes and shows up on the page Nosto can track visits on the page. You can further verify your session in the Nosto admin by using the live feed under https://my.nosto.com/admin/$accountID/liveFeed

Adding the Cart Tagging

On every page load, the cart content must be tagged. The cart contents are the 1:1 representation of the user's mini-cart.

The cart information is used by the Nosto to tailor the recommendations, dispatch abandoned cart emails and fire Facebook pixel events for retargeting purposes.

nostojs(api => {
  api.setTaggingProvider("cart", {
    items: [
      {
        product_id: "Canoe123",
        quantity: 1,
        name: "Acme Canoe",
        unit_price: 999.0,
        price_currency_code: "EUR"
      },
      {
        product_id: "Canoe245",
        quantity: 3,
        name: "Acme Large Canoe",
        unit_price: 19.0,
        price_currency_code: "EUR"
      }
    ]
  })
})

To learn more about the api.setTaggingProvider usage, please refer to the official API documentation.

The full schema for cart tagging is defined here

or via DOM tagging

<div class="nosto_cart" style="display:none" translate="no">

    <div class="line_item">
        <span class="product_id">Canoe123</span>
        <span class="quantity">1</span>
        <span class="name">Acme Canoe</span>
        <span class="unit_price">999.00</span>
        <span class="price_currency_code">EUR</span>
    </div>

    <div class="line_item">
        <span class="product_id">Canoe245</span>
        <span class="quantity">3</span>
        <span class="name">Acme Large Canoe</span>
        <span class="unit_price">19.00</span>
        <span class="price_currency_code">EUR</span>
    </div>

</div>

Note: The product ID of the product tagging, cart tagging and order tagging must match. Failure to do so will lead to a mismatch in both attribution and statistics across the Nosto product.

Dynamic cart changes

Cart content changes should be reflected to Nosto by either calling api.setTaggingProvider("cart", data) with updated cart contents or updating the cart tagging in the DOM.

Adding support for advanced use cases

Many e-commerce stores utilize SKU:s or "child" products that are sorted under the same "parent" product. To extend the above example with SKU support refer to this article

In cases where a product might have multiple prices in differing currencies, you can also add support for multi-currency. Refer to this article

Tagging the cart restore link

If the platform itself has support for persistent shopping cart or other technologies that remember the users cart contents you do not need to worry about filling out the cart when a user returns to the site. If your platform generates a restore cart link you can also send that to Nosto by adding it as a new attribute within the parent container "nosto_cart".

The following piece of code is just a rough example on how a restore cart could look like. The idea of the example is to document how this is tagged to Nosto.

nostojs(api => {
  api.setTaggingProvider("restoreLink", "https://example.com/cart/restore?cart=4D5C3060-1334-4C63-B6FA-D9D342D88B08")
})

or via DOM tagging

<div class="restore_link">https://example.com/cart/restore?cart=4D5C3060-1334-4C63-B6FA-D9D342D88B08</div>

Troubleshooting

Once included on all pages, you can review if the site is transmitting data using the Nosto Debug Toolbar. If you can see cart contents being picked up under "Tagging" → "Cart" then the cart details are correctly set up in the source code. You can further verify your session in the Nosto admin by using the live feed under https://my.nosto.com/admin/$accountID/liveFeed to see if Nosto correctly picks up product view → product carted events.

Translate attribute

The translate attribute is a HTML5 standard attribute which specifies whether the value of the element and it's Text node children should be translated. If your tagging elements are being translated by e.g. Google Translator then this is the way to opt out elements being translated by Google and possibly other vendors.

Adding the Customer information

On every page, the customer information should be tagged if the customer is logged in. If the customer isn't logged in, this but can be omitted.

The customer information is primarily used for sending personalized triggered emails and for building multi-channel experiences.

nostojs(api => {
  api.setTaggingProvider("customer", {
    email: "[email protected]",
    first_name: "John",
    last_name: "Doe",
    customer_reference: "e18daf14-d715-4d77-82f2-93eceb4ae1ef",
    type: "loggedin",
    newsletter: false
  })
})

To learn more about the api.setTaggingProvider usage, please refer to the official API documentation.

The full schema for customer tagging is defined here

or via DOM tagging

<div class="nosto_customer" style="display:none" translate="no">
  <span class="email">[email protected]</span>
  <span class="first_name">John</span>
  <span class="last_name">Doe</span>
  <span class="customer_reference">e18daf14-d715-4d77-82f2-93eceb4ae1ef</span>
  <span class="marketing_permission">false</span>
</div>

Tagging marketing permission

The new marketing-permission flag denotes whether the customer has consented to email marketing. If the marketing-permission field is omitted, we assume that the current customer has not given their consent and Nosto will refrain from sending out any personalized triggered emails.

The marketing permission is false by default but if a user has explicitly agreed to receive marketing then you can set it to true manually. In practice, this means reading and mapping the value from opt-in for marketing in your platform e.g. a consumer explicitly subscribed for marketing emails when checking out.

The marketing-permission should be included as a part of the customer tagging and should be rendered on all pages.

Tagging customer reference

The customer-reference can be leveraged to unify sessions across channels such as between online and offline. It is a unique identifier provided by you that is used in conjunction with the Nosto cookie. The customer-reference can also be used to uniquely identify users in lieu of an email address.

The customer-reference should be a long, secure and a non-guessable identifier. For example, use your internal customer-id or the customer's loyalty program identifier and use a secure hash function like an HMAC-SHA256 to hash it.

Adding the Product Tagging

All product pages should contain the product tagging. The product tagging can be the entire metadata or only a small subset of it.

The product tagging is used to pass the context of the current product being viewed which in turn is used to personalize the recommendations e.g. cross-sellers, and commonly also periodically crawled by Nosto to build an index.

Note: The product tagging must be server-side rendered as the Nosto crawler does not execute Javascript.

You can tag your product pages in two different ways:

Tagging all the metadata (Recommended): This approach is the recommended way to tag your product pages. It contains the entirety of the product metadata and leverages the crawler to build a 1:1 replica of your catalog.
Tagging the bare minimum: This approach entails tagging just the product-id and requires you to leverage an API to build a 1:1 replica of your catalog. This is an advanced use-case and requires that your account-manager disables crawling for your website.

Basic Tagging

In the event that you are unable to expose the entire subset of the product tagging, you can simply tag the product-id.

To learn more about the api.setTaggingProvider usage, please refer to the .

The full schema for product tagging is defined

or via DOM tagging

When the entirety of the product metadata is tagged, Nosto is able to crawl your site and build a 1:1 replica of your product catalog but in this basic example, you will need to use an alternative mechanism for synchronising your catalog with Nosto.

Note: If you do use this approach, your account-manager must disable crawling for your account. Failure to do so will result in a broken catalog replica.

Via an API

In order to keep your product catalog in Nosto up to date, you must leverage the .

Via a Feed

Nosto does not support a product feed and you must leverage the API in order to synchronise your product catalog.

Troubleshooting

Once included on all pages, you can review if the site is transmitting data using the . If you can see product attributes being picked up under "Tagging" then the product details are correctly set up. You can further verify that products are being indexed to the catalog under the Nosto admin by navigating to Tools → Products:

Translate attribute

The translate attribute is a which specifies whether the value of the element and it's Text node children should be translated. If your tagging elements are being translated by e.g. Google Translator then this is the way to opt out elements being translated by Google and possibly other vendors.

Adding the Category/Brand Tagging

Nosto utilizes meta tags to track what category or brand a certain visitor is viewing or what page type the currently viewed page is. These values are then used for dynamic filtering for categories and brands applied through the Nosto admin UI or exposure of certain pop-up campaigns for page types.

The category tagging should be exposed whenever a user is viewing a certain category.

nostojs(api => {
  api.setTaggingProvider("pageType", "category")
  api.setTaggingProvider("categories", ["/Mens/Jackets/Ski Jackets"]) 
})

or via DOM tagging

<div class="nosto_page_type" style="display:none" translate="no">category</div>
<div class="nosto_category" style="display:none" translate="no">/Mens/Jackets/Ski Jackets</div>

The brand tagging should be exposed whenever a user is viewing a certain brand or vendor.

nostojs(api => {
  api.setTaggingProvider("pageType", "category")
  api.setTaggingProvider("brands", ["Acme"]) 
})

or via DOM tagging

<div class="nosto_page_type" style="display:none" translate="no">category</div>
<div class="nosto_brand" style="display:none" translate="no">Acme</div>

To learn more about the api.setTaggingProvider usage, please refer to the official API documentation.

Tagging the categories

Categories must always be delimited by a slash. For example, /Home/Accessories is a valid category while Home > Accessories is not.

Faceting by other attributes

With Nosto you can also expose other attributes that should be used for category/brand page filtering. For example when a user clicks on a certain color, only products with that certain color attribute should be exposed by both the category list, and Nosto Onsite Recommendations. Available values correspond to custom fields tagged as part of the Product Tagging.

nostojs(api => {
  api.setTaggingProvider("tags", ["color: Red", "gender: Men"])
})

or via DOM tagging

<span class="nosto_tag" style="display:none" translate="no">color: Red</span>
<span class="nosto_tag" style="display:none" translate="no">gender: Men</span>

Tagging the current page type

Page type tagging should be exposed whenever a user is interacting with a page so Nosto understands what kind of page this is.

nostojs(api => {
  api.setTaggingProvider("pageType", "category")    
})

or via DOM tagging

<div class="nosto_page_type" style="display:none" translate="no">category</div>

Page type is optional and used mainly for triggering popups and also to understand what kind of page the user is currently interacting with. The page type must always be lowercase and the accepted values for page type are: front, category, produc, cart, order, search and notfound.

Troubleshooting

Once included on all pages, you can review if the site is transmitting data using the Nosto Debug Toolbar. If you can see order contents being picked up under "Tagging" → "Category" then the category and page type tagging are correctly set up in the source code.

Translate attribute

Adding the Search Tagging

Nosto utilizes tracks what a customer is searching for by reading the search query from the URL's query parameter or from the page source.

When the search term exists as a part of the URL's query parameters e.g. https://www.example.com?q=searchterm, Nosto can be configured to read the search term and you can skip the search term tagging.
When the search term exists as a part of the URL e.g. https://www.example.com/searchterm, Nosto is unable to read it from the URL and you will need to tag as a part of the page source. When you implement the tagging for the search term, remember that it is untrusted user input added as part of your page html and it should be html-encoded to prevent XSS vulnerabilities on the site.\

To learn more about the api.setTaggingProvider usage, please refer to the .

or via DOM tagging

Adding the Order Tagging

All thank-you and order-confirmation pages must have the conversion tracking markup.

The conversion metadata is used for sending personalized order-followup emails, personalize the recommendations e.g. order-related, for segmentation insights and conversion statistics.

To learn more about the api.setTaggingProvider usage, please refer to the .

The full schema for order tagging is defined

or via DOM tagging

Note: The product ID of the product tagging, cart tagging and order tagging must match. Failure to do so will lead to a mismatch in both attribution and statistics across the Nosto product.

Tagging the buyer

You can omit the buyer tagging either partially, or completely if you do not want Nosto to crawl this information. The user details are stored for possible marketing purposes and mainly observed email address is used in this context. Marketing permission is false by default but if this user has explicitly agreed to receive marketing then you can set it to true manually.

Tagging the currencies

Currencies should always be represented in the ISO-4471 three-letter format. For example, use the code USD instead of $ to represent the United States Dollar.

Tagging the payment provider

Payment provider is the payment method or provider used by a shopper to pay the purchase. Omit the payment provider detail if you do not want Nosto to crawl this information.

Tagging the order status code

Status code will be used to track the order state. Different payment providers may use different status codes.

Adding support for advanced use cases

Many ecommerce stores utilize SKU:s or "child" products that are sorted under the same "parent" product. To extend the above example with SKU support refer to

In cases where a product might have multiple prices in differing currencies you can also add support for multi-currency. Refer to

Troubleshooting order tagging:

Once included on all pages, you can review if the site is transmitting data using the Nosto Debug Toolbar. If you can see order contents being picked up under "Tagging" → "Order" then the order details are correctly set up in the source code.

You can further verify your session in the Nosto admin by using the live feed under: https://my.nosto.com/admin/$accountID/liveFeed to see if Nosto correctly picks up product view → product carted → product bought events. You can export all the order history from the store under Settings → Other → Order report under https://my.nosto.com/admin/$account/account/orders/report

Translate attribute

Defining Nosto placements

You can define placements for Nosto to use in two ways:

Traditional approach: Using native HTML elements with nosto_element class
Web component approach: Using the <nosto-campaign> web component

Both approaches mark locations in your site where Nosto can hook into and expose onsite content.

Traditional div-element approach

You can define placements via native HTML elements with the nosto_element class. Each element marks a location in your site where Nosto can hook into and expose onsite content.

Here is an example of a <div> tag on the site:

<div class="nosto_element" id="frontpage-nosto-1" translate="no"></div>

The class needs to always reference nosto_element so Nosto understands that this element is available for onsite content placement. However the id frontpage-nosto-1 is flexible but requires that each unique element-id has a matching placement defined in Nosto's admin dashboard in order to expose campaigns.

Here is an example of a page with multiple <div> elements:

// Three separate <divs> after another on a page

<div class="nosto_element" id="frontpage-nosto-1" translate="no"></div>
<div class="nosto_element" id="frontpage-nosto-2" translate="no"></div>
<div class="nosto_element" id="frontpage-nosto-3" translate="no"></div>

// You can also add the class and id to an element you are already using for other purposes

<div class="sidebar nosto_element" id="nosto-sidebar" translate="no">

   <h1>Hello World!</h1>
   <h2>This is the sidebar</h2>

   // You can also nest nosto elements within other wrapper elements

   <div class="nosto_element" id="nosto-sidebar-nested-1"></div>

</div>

Web component approach with `<nosto-campaign>`

As an alternative to nosto_element divs, you can use the <nosto-campaign> web component. This approach provides cleaner markup integration.

Basic usage

<nosto-campaign placement="frontpage-nosto-1"></nosto-campaign>
<nosto-campaign placement="frontpage-nosto-2"></nosto-campaign>
<nosto-campaign placement="frontpage-nosto-3"></nosto-campaign>

or alternatively

<nosto-campaign id="frontpage-nosto-1"></nosto-campaign>
<nosto-campaign id="frontpage-nosto-2"></nosto-campaign>
<nosto-campaign id="frontpage-nosto-3"></nosto-campaign>

for better compatibility with the scoped styling conventions of Velocity templates

Advanced features

The web component supports additional features like lazy loading, product-specific recommendations, cart synchronization, and embedded Vue templates:

<!-- Lazy-loaded campaign -->
<nosto-campaign placement="below-fold-recommendations" lazy></nosto-campaign>

<!-- Product-specific recommendations -->
<nosto-campaign placement="related-products" product-id="123456"></nosto-campaign>

<!-- Cart-synchronized campaign -->
<nosto-campaign placement="cart-recommendations" cart-synced></nosto-campaign>

<!-- Campaign with embedded Vue template -->
<nosto-campaign placement="best-sellers">
  <template>
    <div class="product-card" v-for="product in products">
      <span class="product-name">{{ product.name }}</span>
      <span class="product-price">{{ product.price }}</span>
    </div>  
  </template>
</nosto-campaign>

When to choose each approach

Use nosto_element divs when:

Working with existing legacy implementations
You prefer traditional HTML markup patterns

Use <nosto-campaign> web component when:

You need advanced features like lazy loading or cart synchronization
You want better integration with modern web development practices
You need embedded Vue templates for store-side templating
Working with Shopify themes (additional integration patterns available)

Setup and integration

To use the <nosto-campaign> web component, you need to include the Nosto Web Components library. For detailed setup instructions, see the Web Components documentation.

Tagging your page types

The page-type tagging enables Nosto to trigger actions, such as showing popups, depending upon a page type. Tagging the page types is optional but without the page-type tagging, you will not be able to avail the use of page type based triggers.

Here is a list of all the valid page types:

The home page of your store should be tagged as front.
All category pages should be tagged as category.
All product pages should be tagged as product.
The shopping cart page should be tagged as cart .
The checkout page, where order information is filled, should be tagged as checkout.
The order confirmation page should be tagged as order.
The search results page should be tagged as search.
All no-found pages should be tagged as notfound.
Other pages should be tagged as other.

To learn more about the api.setTaggingProvider usage, please refer to the .

or via DOM tagging

Advanced Usage

Nosto also supports some advanced use-cases depending on how your store is currently built. You should first read through the following topics to have an understanding of how Nosto works before moving to the advanced use-cases:

Manual Implementation - Essentials

The topics listed below extend the essential tagging with support for SKUs, Multi-currency and Customer group pricing.

Manual Implementation - Advanced

Parameterless Attribution

By default Nosto tracks campaign attribution without additional url parameters. The tracking happens by registering click listeners to the campaign elements that detect product url clicks and associate them with the attribution metadata of the rendered campaign. The pair of url and campaign attribution is stored in the local storage of the Browser.

In most cases this will work out of the box, but in certain scenarious adjustments need to be made.

Product url redirects

In case the product urls used in Nosto campaigns have HTTP level redirects applied the HTML should link back to the canonical url used in Nosto campaign via link[refl="canonical"] elements in the head element. Nosto uses both the current location and the canonical page url as lookup keys for the attribution metadata.

Session API based usage

When combined with Session API based requests and HTML based campaign results it is advisable to let the Nosto API handle the campaign injection by enabling campaign injection on the session level:

Check out the API documentation for

Reliance on the legacy nosto parameters

Parameterless attribution became the default attribution mechanism on May 26th 2025. If your setup relies on the legacy nosto parameters being present you can enable the legacy behavior in your main account settings page.

JSON Rendering Attribution

Attribution in custom element based Nosto campaign rendeirng

Below is an example of a custom element that fetches JSON results based on the placement attribute, renders them and register parameterless attribution for product link clicks:

Rendering of campaign markup in non-managed placement elements

In case the campaign markup is rendered into a non-placement element the element will need to be registered with parameterless attribution handling via api.attributeProductClicksInCampaign:

Check out the API documentation for

Adding support for multi-currency

In this article, you will learn how to implement multi-currency in Nosto. When the implementation is complete, you will be able to display product prices (in any feature) in different currencies.

Prior to the multi-currency implementation, ensure that the Nosto tagging is correctly in place. Some of the tagging must be slightly amended to support multi-currency.

Shopify Multi-Currency

For instructions on integrating with Shopify's multi-currency, please go here.

Changes to the product tagging

The product page tagging must be amended to denote the primary currency code of the product. Typically, most retailers have a primary currency which is the default currency of the inventory.

For example, a US-based retailer who sells in Euros (EUR) and Sterling Pounds (GBP) would have US Dollar (USD) as the primary currency while Euro (EUR) and Sterling Pounds (GBP) would be secondary currencies whose exchange rates would need to be sent via an API.

nostojs(api => {
  api.setTaggingProvider("products", [{
    ...
    variation_id: "USD"
  }])
})

or via DOM tagging

<div class="nosto_product" style="display: none;" translate="no">
  ...
  ...
  ...
  <!-- Variation ID for the primary currency --> 
  <span class="variation_id">USD</span>
</div>

Ensure that a span element with the class variation_id is added as a child of the nosto_product element within the product page tagging.

Note: The code in the variation_id element must remain static, regardless of the currency active on-site. This is the primary currency of your catalog. Although variation_id element often has the same currency code as in the price_currency_code element and may seem redundant, they support different use cases and both need to be tagged.

Do child-products (SKUs) support multi-currency?

Yes. Prices for all SKUs will automatically be converted using the same logic. As long as your SKUs are tagged, no additional changes are needed.

What about the prices in the cart and the order tagging?

The cart and order tagging can be left as-is but the prices must be in the customer's currently active currency. For example, a customer shopping in Swiss Francs (CHF) should have all the cart items tagged in Swiss Francs (CHF). Failure to do so will result in incorrect prices in any triggered mails such as abandoned cart or order followup.

Specifying the active currency

Once you have amended the product tagging, an additional DIV element must be added to all the other pages (including the product page itself). The tag should not be encapsulated in the nosto_product DIV tag. The information sent in the tag refers to the currency active of the customer.

nostojs(api => {
  api.setTaggingProvider("variation", "USD")
})

or via DOM tagging

<div class="nosto_variation" style="display: none;">USD</div>

For example, on the site of a US-based retailer who sells in Euros (EUR) and Sterling Pounds (GBP), if the customer changes the currency to Sterling Pounds (GBP), the nosto_variation element should show GBP. If the customer changes the currency to Euros (EUR), the nosto_variation element should show EUR.

Sending the exchange-rates

In order to send the exchange rate multipliers to Nosto, you will need to use our exchange-rates API. Below is a small snippet of what the payload looks like.

{
  "rates":{
    "GBP":{
      "rate":0.77,
      "price_currency_code":"GBP"
    },
    "EUR":{
      "rate":0.91,
      "price_currency_code":"EUR"
    }
  },
  "valid_until":"2015-02-27T12:00:00Z"
}

In the example above, 0.77 is the exchange rate from US Dollars (USD) to British Pounds (GBP) and 0.91 is the exchange rate from US Dollars (USD) to Euros (EUR).

The valid_until entry defines the expiration date. When the expiration date is reached, the exchange rates won't be applied anymore and prices will be hidden for all the secondary currencies to prevent displaying outdated prices.

When recommendations are served, then exchange rates are dynamically applied to the product prices to reflect the active currency.

Enabling multi-currency from the admin

Once the tagging changed have been done and the API implemented, you need to configure and enable it from your admin panel under Settings > Other > Multi-Currency. Toggle the Use Multiple Currencies and Use Exchange Rates switches on and set the variation ID of the primary currency via the input field and toggle on the exchange rates switch.

Note: Ensure that the Variation ID of the primary currency matches the value sent via the variation_id element in the product tagging.

You will also need to configure the price formatting for your primary and secondary currencies.

Integration with search/category merchandising (universal)

Reviewing your changes

Once you enabled multi-currency and made an API call, you can review the exchange rates received by Nosto by navigating to Settings > Other > Multi-currency.

You can also preview the product prices for different currencies by navigating to Tools > Products and choosing a product.

You will see one or more dropdowns that contain the prices and price calculation for the currency.

When you have reviewed your set-up, Nosto updates in real-time product prices for all the currencies and display the appropriate currency to the right target groups of users. You’re all set and ready to go live with our features.

Adding support for customer group pricing

In this article, you will learn how to implement multi-variants in Nosto. When the implementation is complete, you will be able to display different products at different prices to different customer groups.

Note: You can only change the pricing and the availabilities using this feature.

Note: You cannot use SKUs with this feature at the time of writing.

You will need to implement the multi-variate tagging if you have any such scenarios:

Your store has different prices for B2B and B2C customers
Your store has different prices for logged-in and logged-out customers
Your store has different prices for loyalty customers
Your store has different prices and availabilities for different locations

Prior to the multi-variate implementation, ensure that the Nosto tagging is correctly in place. Some of the tagging must be slightly amended to support multi-variants.

Changes to the product tagging

The product page tagging must be amended to denote the primary variation code of the product.

For example, a retailer who has different prices for normal and loyal customers would have GENERAL as the default variation id and LOYAL as an extra variation.

nostojs(api => {
  api.setTaggingProvider("products", [{
    variation_id: "GENERAL", // Primary variation
    variations: {
      LOYAL: {
        variation_id: "LOYAL",
        price_currency_code: "EUR",
        price: "27.00",
        list_price: "45.19",
        availability: "InStock"
      },
      B2B: {
        variation_id: "B2B",
        price_currency_code: "GBP",
        price: "24.00",
        list_price: "41.55",
        availability: "OutOfStock"
      }
    }
  }])
});

or using DOM tagging

<div class="nosto_product" style="display: none;" translate="no">
  ...
  ...
  ...
  <!-- Variation ID for the primary currency --> 
  <span class="variation_id">GENERAL</span>
  <!-- Variation block for a secondary currency -->
  <div class="variation">
    <span class="variation_id">LOYAL</span>
    <span class="price_currency_code">EUR</span>
    <span class="price">27.00</span>
    <span class="list_price">45.19</span>
    <span class="availability">InStock</span>
  </div>
  <!-- Variation block for a secondary currency -->
  <div class="variation">
    <span class="variation_id">B2B</span>
    <span class="price_currency_code">GBP</span>
    <span class="price">24.00</span>
    <span class="list_price">41.55</span>
    <span class="availability">OutOfStock</span>
  </div>
</div>

Ensure that a span element with the class variation_id is added as a child of the nosto_product element within the product page tagging.

Note: The code in the variation_id element must remain static, regardless of the current context. For example, if a loyal customer is logged in, the variation_id field would still GENERAL and not change.

What about the prices in the cart and the order tagging?

Specifying the active variation

nostojs(api => {
  api.setTaggingProvider("variation", "GENERAL")
})

or via DOM tagging

<div class="nosto_variation" style="display: none;">GENERAL</div>

For example, on the site of a retailer, who has different prices for normal (GENERAL) and loyal (LOYAL) customers, if the customer is a logged in customer and is a known loyalty customer, the nosto_variation element should show LOYAL. If the customer logs out or a new customer visits, and there is no way to identify him as a loyal customer, the nosto_variation element should show GENERAL.

Integration with search/category merchandising (universal)

Enabling multi-variants from the admin

Once the tagging changes have been done and the API implemented, you need to configure and enable it from your admin panel under Settings > Other > Multi-Currency. Toggle the Use Multiple Currencies switch on and Use Exchange Rates switch off and set the variation ID of the primary currency via the input field and toggle on the exchange rates switch.

Note: Ensure that the Variation ID of the primary currency matches the value sent via the variation_id element in the product tagging.
Note: Multi-variants cannot be used in conjunction with exchange-rates based multi-currency feature. You must keep the Use Exchange Rates switch off.

You will also need to configure the price formatting for your primary and secondary currencies.

Reviewing your changes

Once you enabled multi-variants you can preview the product prices for different groups by navigating to Tools > Products and choosing a product.

You will see one or more dropdowns that contain the prices and the availability for that group.

When you have reviewed your set-up, you’re all set and ready to go live with our features. Nosto will automatically handle the different customer groups across its feature set.

Event API: Listening to Bus Events with api.listen

Overview

Registers a listener for Nosto JS API events. Use this to react to specific lifecycle or user events dispatched by the Nosto client.

Check out the API documentation for

Example Usage

Supported `BusEvent` Types

The following table lists all event types supported by the listen API. See for API documentation on each of these event types and it's associated payload

Lifecycle Events

A Nosto recommendation request is sent to the /ev1 endpoint and returns the product recommendation(s) for placements injected on the page.

A recommendation response is the response returned from the /ev1 endpoint.

Event Name

Description

Event Name

Description

Tagging Events

Event Name

Description

Unregistering listener

Use the unlisten method to remove a previously registered event handler for a specific event type, using the listen API method. Check out the API documentation for .

Example usage

Note: If the callback was not previously registered for the event, calling unlisten has no effect.

FAQ

The nosto parameter allows Nosto to attribute clicks on content and recommendations. In the event, you'd like to omit the parameter, you'll need to manually send the product-view event. You can do so by executing the following snippet.

How the attribution is tracked will be entirely dependent upon your implementation.

Implement on native mobile

Implementing Nosto on a native mobile application allows a retailer to collect behavioral events similarly as within a traditional web page. This information will then be merged with Nosto data across other sources, impacting product relationships and real-time statistics across the board.

Read more about the commercial benefits of Mobile Application support here: https://www.nosto.com/products/mobile-app-personalization/

Due to the nature of the technical environment related to Native Application development, both behavioral and transactional data needs to be sent manually, and consequently all requests for personalization features needs to be tailored within the application as well.

Read more about Nosto's GraphQL API: https://docs.nosto.com/techdocs/apis/graphql-an-introduction

Read more about implementing Nosto with GraphQL on IOS and Android: https://docs.nosto.com/techdocs/apis/graphql-an-introduction/graphql-for-ios-and-android

Implement on a physical store

For multi-channel retailers tying the brick-and-mortar stores into Nosto's personalization solution allows retailers to collect all data into one. This information will then be merged with Nosto data across other sources, impacting product relationships and real-time statistics across the board. Retailers who have unified their data, can also start matching customers across different channels, and personalize every aspect of their shopping journey.

Read more about the commercial benefits of Mobile Application support here:

Using Search Templates Starter

The Search Templates Starter is a Preact-based starter template that provides a complete development environment for building custom search experiences with Nosto.

Why use Search Templates Starter?

Search Templates Starter allows you to build fully custom search implementations with modern development practices. You get:

Full source code control with Git version management
Modern development tooling including TypeScript, Vitest, and Storybook
Local development environment with hot reloading and debugging
Component library with pre-built, customizable search components
Complete flexibility to modify any aspect of the search experience

This approach is ideal when you need advanced customization or when your development team prefers working with familiar local tools and workflows.

Get Started

To start developing with Search Templates Starter, you'll need Node.js 22+ and familiarity with React/Preact.

Implementation guides

LLM Examples

Utilizing LLMs for Development

Large Language Models (LLMs) like GitHub Copilot, ChatGPT, and Claude can significantly accelerate development with the Search Templates Starter. This guide provides proven prompts and strategies for common development tasks.

Why use LLMs with Search Templates Starter?

The Search Templates Starter's well-structured codebase and modern tooling make it ideal for AI assistance:

Consistent patterns - The organized project structure helps LLMs understand context
TypeScript support - Type information provides better AI suggestions and error detection
Component-based architecture - Clear boundaries make it easier to generate focused code
Testing infrastructure - LLMs can generate tests alongside implementation code

Effective Prompting Strategies

Follow Standard Development Patterns

The Search Templates Starter includes standard development patterns and documentation that LLMs can leverage:

AGENTS.md Standard - Follows the standardized pattern for providing AI coding agents with project-specific context, build commands, code style guidelines, and testing instructions
Copilot Instructions - Pre-configured GitHub Copilot instructions are included in the repository and should be customized for your specific use case
README patterns - Follow the established documentation structure for consistency

Tip: Consider modifying the AGENTS.md file in your project root to align with your project's custom conventions. Following the standard ensures that all AI coding tools can consistently adjust their contributions to match your guidelines.

Common Development Tasks

Component Modifications

Example: Replace FilterSidebar with FilterTopbar

Example: Replace Pills with Checkboxes in Filters

Styling Changes

Example: Replace CSS Modules with Tailwind

Search Functionality

Example: Replace Infinite Scroll with Load More Button

Best Practices for LLM-Assisted Development

Code Review

Always review LLM-generated code for:

Adherence to project patterns and conventions
TypeScript type safety
Security considerations
Performance implications
Test coverage completeness

Iterative Refinement

Start with basic prompts and refine:

Get a working implementation
Ask for improvements and optimizations
Add error handling and edge cases
Enhance with additional features
Optimize for performance and maintainability

Combine with Human Expertise

Use LLMs to:

Generate boilerplate code quickly
Explore different implementation approaches
Create comprehensive test suites
Document complex functionality

But rely on human judgment for:

Architecture decisions
Security considerations
Performance trade-offs
User experience design

Troubleshooting LLM Issues

Common Problems

Generated code doesn't follow project patterns:

Include more specific context about existing patterns
Reference specific files as examples
Provide the project structure in your prompt

TypeScript errors in generated code:

Ask the LLM to review and fix TypeScript errors
Provide the exact error messages for targeted fixes
Include relevant type definitions in your prompt

Tests fail or are incomplete:

Request test coverage for specific scenarios
Ask for tests that follow existing test patterns
Include example test files for reference

Generated code lacks optimization:

Ask specifically for performance considerations
Request code review focusing on optimization
Include performance requirements in your initial prompt

By following these patterns and examples, you can significantly accelerate your development workflow while maintaining code quality and project consistency.

Customizations

Product Image Configuration

Customizing Product Image Aspect Ratio

You can use CSS custom properties (variables) to define the aspect ratio for specific components. This is useful for components like the autocomplete dropdown where you might want a different aspect ratio than the main product grid.

The project defines a CSS custom property --ns-aspect-ratio for this purpose.

Example: Autocomplete Product Image

The product images within the autocomplete results use this CSS variable.

File to inspect: src/components/Autocomplete/Item/Product.module.css

/* src/components/Autocomplete/Item/Product.module.css */
.image {
  height: auto;
  aspect-ratio: var(--ns-aspect-ratio);
  object-fit: contain;
  width: 100%;
}

You can override the value of --ns-aspect-ratio in your theme's CSS file or directly in the component's stylesheet to change the aspect ratio. The value is defined in src/variable.css.

File to edit: src/variable.css

/* src/variable.css */
:root {
  /* ... other variables ... */

  --ns-aspect-ratio: 1; /* Default to square */
}

By changing --ns-aspect-ratio to 4 / 3, for instance, any component using this variable will render images with a 4:3 aspect ratio.

Search page redirects

Autocomplete Search Submission and Redirects

This document explains how submitting a search from the autocomplete component navigates the user to the Search Engine Results Page (SERP).

Overview

When a user selects a suggestion or submits a query from the autocomplete dropdown, the application's behavior depends on the user's current location. The goal is to ensure the user always ends up on the main SERP to see the full results.

This logic is primarily handled within the onSubmit function in the Search component.

File to inspect: src/components/Search/Search.tsx

How It Works

The onSubmit function checks the current page's URL (window.location.pathname) to decide whether to perform an in-place search update or a full-page redirect.

Scenario 1: User is Already on the SERP

If the user is already on a page that includes /search in its path, submitting a new search will not cause a full-page redirect.

The newSearch({ query }) action is dispatched.
@nosto/search-js fetches the new results.
The components on the SERP update in place to display the new results.

This provides a fast and smooth experience when refining a search.

Scenario 2: User is on Another Page (e.g., Homepage)

If the user performs a search from any page that is not the SERP (e.g., the homepage, a content page), the application will perform a full-page redirect to the SERP.

The browser is redirected to /search?q=<your-query>.
The SERP then loads, reads the q parameter from the URL, and automatically fetches and displays the results for that query.

This ensures a consistent experience, where a search always leads the user to the dedicated, fully-featured search results page.

Implementation Example

Here is a simplified look at the logic inside src/components/Search/Search.tsx:

// src/components/Search/Search.tsx

export default function Search() {
  const { newSearch } = useActions();

  const onSubmit = (query: string) => {
    // If we are already on the search page, just update the results
    if (window.location.pathname.includes("/search")) {
      newSearch({ query });
    } else {
      // Otherwise, redirect to the main search page
      window.location.href = `/search?q=${encodeURIComponent(query)}`;
    }
  };

  // ... component JSX that uses onSubmit
}

URL Mapping

Search Results Page URL Management

When a search is performed (either by submitting the search form or clicking a non-redirect keyword), the user is taken to the search results page. The state of the search (query, filters, pagination, etc.) is reflected in the URL's query parameters.

URL Structure

The search results page URL is managed by a set of utility functions in src/mapping/url/. The URL is constructed with the following parameters:

q: The search query.
p: The current page number (omitted for the first page).
size: The number of results per page.
filter.*: Applied filters (e.g., filter.brand=Nike).
sort: The selected sorting option.

How It Works

State Management: The SearchQueryHandler component (src/components/SearchQueryHandler/SearchQueryHandler.tsx) is responsible for synchronizing the application's search state with the URL.
URL Updates: It uses the updateUrl function (src/mapping/url/updateUrl.ts) to serialize the current search state into URL parameters and update the browser's history using window.history.replaceState.
Initial State: On page load, the getCurrentUrlState function (src/mapping/url/getCurrentUrlState.ts) deserializes the parameters from the URL to initialize the search state. This ensures that a user can share a URL, and it will load the same search results.

Example

A search for "shoes" on the second page with a filter for the brand "Nike" would result in a URL like this:

/search?q=shoes&p=2&filter.brand=Nike

Autocomplete features

Enabling Autocomplete Features

This document explains how to enable and configure various features for the autocomplete component, including category suggestions and trending searches.

To enable these features, you only need to modify the withAutocompleteDefaults function in src/config.ts to request the necessary data. The UI components in src/components/Autocomplete/Results/ are already set up to render this data once it's fetched.

Enabling Category Suggestions

You can enhance the autocomplete experience by including category suggestions alongside product and keyword results.

Configuration

To enable this feature, add a categories object to the query returned by the withAutocompleteDefaults function.

File to edit: src/config.ts

How It Works

By adding the categories object to the query, you are instructing @nosto/search-js to fetch category suggestions. The useResponse hook within the Results component (src/components/Autocomplete/Results/Results.tsx) will then receive this data.

The Results component, in turn, passes the category data to the Categories component (src/components/Autocomplete/Results/Categories.tsx), which is responsible for rendering the suggestions. No additional rendering configuration is needed.

Enabling Popular Searches

Displaying popular searches can help guide users and improve product discovery. This feature shows suggestions based on what other shoppers are searching for.

Configuration

To enable this feature, add a popularSearches object to the query returned by the withAutocompleteDefaults function.

File to edit: src/config.ts

How It Works

Similar to category suggestions, adding the popularSearches object to the query will cause the data to be fetched. The useResponse hook in the Results component will receive the data and pass it to the PopularSearches component (src/components/Autocomplete/Results/PopularSearches.tsx), which handles the rendering automatically.

Dynamic product cards

For Shopify stores, dynamic cards offer a powerful way to display products. Instead of building product cards from individual pieces of data (like a product's name and price), you can load the complete, ready-made product card directly from your theme.

This is the recommended approach when:

Your product cards have complex logic, such as variant selectors, color swatches, or add-to-cart forms.
You want to maintain a single source of truth for your product card templates within your Shopify theme.
You need to display rich product information that may not be available as individual fields in the search API response.

How It Works

The starter template uses a decorator to extract a product's handle from its URL. This handle is then passed as a prop to the DynamicCard Preact component, which in turn sets the handle attribute on the nosto-dynamic-card web component.

The key props you will work with are:

handle: This is derived automatically by the handleDecorator from the product.url. You typically do not need to manage this manually.
template: The name of the alternate template to use for rendering.
section: The ID of the section to render from your product template.

Note: To render a dynamic card, you must provide the handle prop along with either the template or section prop.

The nosto-dynamic-card web component leverages Shopify's built-in support for these features. When you provide a template or section prop, the component constructs the appropriate URL to fetch the pre-rendered HTML from your Shopify store.

Configuration

1. Configure the `DynamicCardProduct` Component

The template provides DynamicCardProduct components for both the search results page (SERP) and the autocomplete dropdown. You need to ensure the template prop matches a template available in your backend.

SERP Location: src/components/Product/DynamicCardProduct.tsx
Autocomplete Location: src/components/Autocomplete/DynamicCardProduct/DynamicCardProduct.tsx

For example, to change the template name for the search results page:

2. Enable Dynamic Rendering in the Product Grid

The search results page (Products.tsx) can be configured to use either the static Product.tsx component (client-side rendering) or the DynamicCardProduct.tsx component (server-side rendering).

To use dynamic cards, ensure the component is imported from DynamicCardProduct.tsx.

Visually Testing Dynamic Product Cards

When using dynamic product cards, the HTML for the cards is fetched directly from the merchant's website. This means that the styling for these cards is not included in the starter template's CSS.

To visually test the dynamic product cards in your local development environment, you need to include your store's CSS. You can do this by adding a <link> tag to the <head> of the index.html file in the root of the project.

For example:

Replace https://your-store.com/store.css with the actual URL to your store's main stylesheet. This will allow you to see the correctly styled product cards when running the development server.

Using Search Templates

Why use Search Templates?

Search Templates allow you to add a search function to your website quickly and easily without the need to use an API. You can customize the design of your search pages and autocomplete boxes to match your brand's look and feel. This saves you a lot of time compared to implementing search functionality through an API.

Get Started

To get started with Search Templates on your website, navigate to the Search tab under 'On-site' within the Nosto UI. This is where everything for Search can be configured and controlled, including designing the templates for search pages and autocomplete dropdowns, as well as search analytics, merchandising rules and other settings. Synonyms for search queries can also be configured here.

If you prefer to develop the template in your local IDE of choice, we recommend you also take a look at . The CLI tool set allows you to develop the template on your machine with your own tools, and upload the build artifacts directly to Nosto.

To begin implementing Search, navigate to the Templates tab under Search, and Click on “Open Code Editor”.

You will then be redirected to the Code Editor window, where you can see and edit all project files.

Search Templates ship with a library called @nosto/preact that contains functionality to interact with the Nosto Search product. API documentation for the library is available

Project structure

Project structure has the following requirements:

index.js - this is application entry point that is used when building project. When building project it will recursively scan this file for imports.
build/ - this directory stores build output that will be used when deploying project.

Saving, testing & deploying

After saving changes (CTRL + S) build should be triggered and bundled code should be uploaded to CDN. You can preview final result on your website and deploy it when ready.

Implementing Category pages

Category pages can be rendered using search templates over existing category pages.

Configuration

To render the category page, provide additional configuration parameters to the init function in the index.js entry point file. Default configurations for categoryQuery and isCategoryPage are already provided. Custom configuration is necessary only if the default settings are not suitable for your application.

The default isCategoryPage function checks for the presence of an element in the DOM and determines if the page should be considered a category page based on its content.

Category query parameter as function

In the example above, we supply autocomplete query parameters as an object. Additionally, the categoryQuery parameter can also be supplied as a function. The function flavor can be used for building complex query parameters and provides access to other pre-defined configuration parameters. Section below shows an example of categoryQuery supplied as a function which provides the product variationId by accessing the pre-defined categoryId and categoryPath methods from the default configuration.

If you want to integrate only Categories without Search or Autocomplete, ensure that the following entries are removed or commented out:

serpComponent

historyComponent

autocompleteComponent

Handling native results

Nosto will attempt to display the original category page products in case Nosto service is unavailable or can't be reached. In addition, the original products are made available for the SEO crawlers, improving the page's ranking in the search engines. To make it possible, it's recommended to hide the original category page products instead of removing or blocking them.

The best approach is to add ns-content-hidden class name to the same element you are targeting with contentCssSelector or categoryCssSelector. This class name will be stripped away by Nosto automatically as soon as the script is initialized.

In addition, you should define CSS to hide the target element:

Detect search page

The isCategoryPage function should detect whether the current page is a category page. Its result should not be cached, as it needs to dynamically detect the page type since it can change during the app's execution. For example, if the user navigates from a category page to a search page, the function should reflect that change in page type.

Category query

The categoryQuery should generate a category page query based on the current page. It must return either categoryPath (identical to the categories field filter) or categoryId to select the current category. The default implementation extracts the categoryId and categoryPath fields from the DOM.

Category component

The category component should also be implemented. In most cases, it is the same component as the search page component, except that the search query should not be displayed.

Other features & implementation

The category page shares a lot of similarities with the search page, so please refer to the search page documentation:

Analytics

Search automatically tracks to Google Analytics & Nosto Analytics when using the SerpElement component.

Using the API

Implement Category pages

Nosto provides functionality to retrieve all products for a specific category. This is useful when you want to implement category merchandising using the same API as for Search.

API Requests

Using category ID and category path

Using the category ID is only fully supported for Shopify merchants. Others should use the category path instead to benefit from full functionality.

Provide the categoryId API parameter to fetch all products associated with that category. Additionally categoryPath should be provided for better analytics data.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      categoryId: "123456789",
      categoryPath: "Pants"
    }
  ) {
    products {
      hits {
        productId
        name
        url
        imageUrl
        price
      }
      total
      size
    }
  }
}

Product fields that can be requested in the hits object are documented here. All indexed fields are accessible via the API.

Using only category path

Provide the categoryPath API parameter to fetch all products associated with that category. This parameter is the same as the categories product field.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      categoryPath: "Pants"
    }
  ) {
    products {
      hits {
        productId
        name
        url
        imageUrl
        price
      }
      total
      size
    }
  }
}

Product fields that can be requested in the hits object are documented here. All indexed fields are accessible via the API.

Child category handling

Depending on your configuration, fetching a parent category will also include products from the child categories. For example, fetching products for the category Pants would also include products from the categories Pants -> Shorts and Pants -> Khakis.

This is an admin-only setting. Please contact your Nosto representative to adjust this setting.

Using custom filters

In some rare cases categoryId or categoryPath is not enough. In these cases custom filters can be used to build any query for category & landing pages.

Query

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    products: {
      preFilter: [
        {
          field: "productId",
          value: [
            "2276",
            "2274"
          ]
        }
      ],
    }
  ) {
    products {
      hits {
        productId
        name
      }
      total
      size
    }
  }
}

Other features & implementation

The category page shares a lot of similarities with the search page, so please refer to the search page documentation:

Implement Search results page

Analytics

Nosto Analytics

FAQ

Additionally, please refer to for further useful information!

Search returns up to 10000 documents

Due to performance optimization, the search function will calculate the total count up to 10,000. In this case the search page should display a count of 10,000+ to indicate that more than 10,000 products were found.

Filters and sorting operations are executed on all found products, even if there are more than this limit. Therefore, it's still possible to find other products if you filter or sort them. This should not affect the user experience in any way because it's unlikely that someone would actually view more than 10,000 products with a single search.

By default, up to 250 products can be retrieved at once (in a single request). Paginate to access results past 250 products.

Products in category listings are in a different order as soon as I deliver results from Nosto API

As soon as you use the results delivered by Nosto API, you will see that the listings in categories have a different order than listings delivered by your native shop-system, even if you didn't set up any merchandising rules. The products are mainly delivered as indexed during the data sync, but there is no defined behavior for this. We recommend to always set up at least one global rule before going live with Nosto category merchandising to create product listings matching your business strategies.

Implement Autocomplete using the Nosto Autocomplete library

Nosto Autocomplete library is designed to simplify the implementation of Search Autocomplete functionality by providing:

Autocomplete products, keywords and history visualization.
Automatic bindings to Nosto Search API.
Autocomplete component state management.
Nosto Analytics out of the box, Google Analytics support.
Default Autocomplete components and templates.
Keyboard navigation.

The Nosto Autocomplete library is independent from the Search Templates offering which covers Search, Category Merchandising and Autocomplete.

Search Templates offers a hosted development environment based on Visual Studio Web using Preact components for the development of Search and Category Merchandising result pages, as well as Autocomplete experiences. Nosto Autocomplete covers only the Autocomplete part as an independent NPM package and provides integration into various rendering technologies such as React/Preact, Mustache and Liquid.

Installation

You can install the Nosto Autocomplete library via npm:

The Nosto Autocomplete library can be imported and used in various ways, depending on your preferred framework or template language. Some of the supported import methods include:

Framework

Import Statement

Choose the import method that aligns with your project's requirements and technology stack.

❗Do not combine multiple imports as it will fetch multiple bundles.❗

Submit search

When submitting Search results through Autocomplete, submit callback is called on these events:

Enter key press.
Submit button click.
Keyword click.

By default submit checks if query/keyword length satisfies minQueryLength, sends Search Submit event to Nosto Analytics, and sends Search request to the Nosto Search API.

In the usual scenario, you want to render Search Results on submit, so you should override submit function:

To disable submit pass undefined value. \

📊 Nosto Analytics (enabled by default)

Setting nostoAnalytics: true will enable Nosto Analytics tracking. Tracking results can be seen in the Nosto Dashboard under Search & Categories -> Analytics page.

Note: You should additionally add click events on your search results page according to with type: serp || category according to the results page type.

📈 Google Analytics (enabled by default)

By default, we send pageview events to existing GA tag, found in shop site. To send pageview events with correct search information, a minimal configuration is needed in googleAnalytics property.

serpPath - Search query url parameter name
queryParamName - Search query url parameter name
enabled - Enable Google Analytics

For example, if search results URL is https://examplenostoshop.com/search-results?query=shoes, then configuration should be:

To disable Google Analytics, set googleAnalytics: false.

Create Autocomplete template

Attributes

The following data-* attributes are required by the library to handle attributions (click events) for products/keywords/history items rendered in the autocomplete result:

data-ns-hit

This attribute should be used on clickable keyword, product, history list elements. This attribute handles submit keyword/history as search, redirect to product, analytics (if enabled) request.

Encode HTML content

This is specific to cases where no template language like liquid/handlebars is used and the content is rendered using plain HTML.

Make sure to HTML encode content passed to this attribute. Bacause JSON.stringify may produce result that can't be directly used in HTML especially when the content includes special characters.

For example, consider the below example

{
  "keyword": "new year's eve",
  "_highlight": { "keyword": "new year's eve" }
}

can be encoded as

{&quot;keyword&quot;:&quot;year's eve&quot;,&quot;_highlight&quot;:{&quot;keyword&quot;:&quot;<strong>year</strong>'s eve&quot;}}

Following table shows value for this attribute depending on the rendering context.

Context

Value

keyword

value from response.data.search.keywords

Code example:

Value example:

product

productId and url from response.data.search.products.hits

Code example:

Value example:

history

historyEnabled & historySize config. Refer

data-ns-remove-history

This attribute should be used to delete history entries in the autocomplete

To make an element delete a single history entry when clicked, add data-ns-remove-history={hit.item} to an element. In order to delete all history entries, add data-ns-remove-history="all" to clear button.

Starter templates

This section provides links to default startup templates for different rendering frameworks. These templates can be copied and customized as needed.

Handlebars, Mustache, Liquid, React/Preact (HTML)

Mustache helpers

Mustache is based on logic-less templates which can be enhanced with helpers, e.g toJson, imagePlaceholder, showListPrice in example template.

import { fromMustacheTemplate } from '@nosto/autocomplete/mustache'

fromMustacheTemplate(template, {
    helpers: {
        toJson: function () {
            return JSON.stringify(this)
        },
    },
})

Deployment & Testing

This section provides guides on how to test and deploy your Search Templates and Search Templates Starter implementations.

Testing

With the Nosto debug toolbar, you can see all the changes made to your website right away. To enable this feature, simply turn on the preview mode. After saving any changes in the code editor, you will be able to see them directly on your website.

How to use preview:

Navigate to your website
In the URL, append ?nostodebug=true to enable the debug toolbar
The Nosto debug toolbar should open up, where you will be asked to log in
Once you have logged in, enable the Preview toggle button at the bottom
You should now be able to view your changes live, via the Search box

Manual testing

Before each deployment search should be manually tested to ensure that everything works correctly.

What to test?

Autocomplete returns results
Search displays results, facets with counts
You can select multiple facets (on the same field and different fields)
Sorting is working
Pagination is working

Test both mobile & desktop view using Chrome device simulation.

Deploying

When you finished working on search implementation & carefully tested everything using , it's time to deploy everything.

Production Deployment

The Nosto CLI only handles preview deployments. To promote your changes to production:

Test thoroughly in preview mode
Navigate to Nosto Admin UI > Search > Templates
Click "Deploy latest and launch live"

Important: Always test your changes thoroughly in preview mode before promoting to production, as this affects all your store visitors. It can take up to 15 minutes for deployment to be visible.

Deployment Safety

Preview First: All CLI uploads go to preview mode initially
Admin Control: Production deployments require manual approval in the Admin UI
Rollback Available: Previous versions can be restored from the Admin UI if needed

Rollback previous deployment

If the most recent update doesn't work properly, you have the option to revert to any previous update. Reverting won't alter the source, which means you can deploy the latest changes again simply by clicking on the main deployment button.

How to revert deployment

Navigate to the Nosto Admin UI > Search > Templates
Click on the desired deployment, click on ... and then on Redeploy

Disable Templates

If your latest update doesn't work and you don't have a previous working version to go back to, or if you want to completely remove the search function, you can turn off the search templates for a temporary period.

Reverting won't alter the source, which means you can deploy the latest changes again simply by clicking on the main deployment button.

How to disable templates?

Navigate to the Nosto Admin UI > Search > Templates
Click on the Disable Templates button.

Template customization

This section describes template customization tools and best practices for the following Nosto products:

Product Recommendations
Onsite Content Personalization
Pop-Ups

These three products share the same templating technology and use Velocity based templates which are injected into the page via Nosto's client script.

In addition to Velocity-based server-side templating, we also have templating usage in other products:

Search Templates
Nosto Autocomplete

Web Components

For template customization we recommend the usage of both our own web component offering and third party tooling such as:

Swiper A modern touch slider used for creating responsive, mobile-friendly carousels. It offers smooth transitions, extensive configuration options, and high performance. Find more details at Swiper Homepage.
unpic A lightweight, on-demand image optimization library that delivers optimized images with lazy loading. It helps improve performance and user experience by automatically adjusting image sizes. Visit the unpic Homepage for additional information.
shoelace A collection of professionally designed, accessible, and customizable web components. It makes it easy to build modern web interfaces with consistent styling. Learn more on the shoelace Homepage.

Starting points

Each new Nosto account comes with three base recommendation templates to customize.

Default

The Default template has the following features:

Recommended products in a grid
Alternate image on hover
Ribbons for new, most viewed, and top-selling products
Highlighting of discounts
Add to cart functionality

Carousel

The Carousel template extends the base template with a Swiper-based carousel to cycle between the recommended products. The library dependency is loaded via a script module, but a locally available version of the library can be used as well.

Carousel implementation via Swiper
Swiper is loaded via CDN URL into script module scope
Swiper default styles are injected into the DOM
Navigation module is loaded, and navigation buttons are provided in the DOM
Basic mobile breakpoints are provided

Swatches

The Swatches template extends the base template with SKU selection-aware product cards with swatches for color and size selection.

Color and size swatch rendering
Product and SkuOptions web components to maintain swatch selection state and abstract the add-to-cart logic away
Web components library is loaded via CDN URL into script module scope
Product image is updated based on color swatch selection
Add to cart button becomes visible when color and size values have been chosen

Product cards

Nosto recommends using shop-provided resources for rendering product cards in Nosto templates. Doing so offers:

Faster onboarding
Easier maintenance
Consistent styling and behavior

Below are the recommended approaches.

Custom Web Components

If your shop themes use web components, we suggest leveraging them in your Nosto templates as well. This avoids duplicating markup and logic between your shop and Nosto templates. For building web components efficiently, consider using Lit or similar high-level frameworks.

Nosto Web Components

Nosto offers several web components designed to simplify product card integration:

DynamicCard Renders product cards entirely on the Shopify side. &#xNAN;Requires alternate product card templates to be available within Shopify themes. Choose this approach if the shop already uses product card markup in Liquid templates and you want to reuse that markup in Nosto campaign rendering. Detailed instructions on how to set this up in your Shopify store are provided here
Product Enhances static product card markup with interactive features such as:
- Swatch selection
- Add-to-cart interactions
- Dynamic product image updates based on swatch and SKU selections

Nosto's web component offering is documented here

Style Reuse

If web components aren’t an option, we advise duplicating only the markup for product cards within Nosto templates while applying shop-side CSS rules to maintain consistent styling.

Product images

This article covers how Nosto provides product images in on-site recommendations and helps you how to change the image settings if these look unsharp or otherwise bad to you. On the contrary, if recommendation images load slowly the article covers also how to adjust settings to speed up image load times and other common errors with the images.

Introduction

The implementation of Nosto on a web-site maps out an original product image used on a product detail page (PDP) to Nosto automatically. In the background, an automated service fetches the default product image and creates eight different image versions out of the image, which are stored at Nosto and made available in our Content Delivery Network (CDN).

Some image versions are processed slightly by resizing, cropping and zooming the image a bit. Applicable image versions in Nosto’s CDN are:

Version

Dimensions

These are the the available image sizes via Nosto's CDN. Alternatively you can use original image , but in this case an image is loaded from your servers possibly affecting site load times, entirely depending on how images are hosted on your servers. Use following variable to use the original image.

The Nosto CDN thumbnails are accessible via

where size is a number between 1-7 basd on the version mapping above.

Custom thumbnail sizes

For Shopify and Bigcommerce Nosto supports also direct access to Shopify and Bigcommerce CDN thumbnails.

These are accessed via the following pattern:

To access the first alternate image scaled down to a 300x300 image use

The custom thumbnails are served without any cropping.

It is also possible to leave width or height undefined to define only a limit for one of the dimensions:

This would scale down the image to have a max width of 300 pixels.

Troubleshooting Common Issues

Product Images Don’t Appear

If a product image doesn’t appear or if the image link is broken this usually due to error in image url tagging, erroneous url mapping or a temporarily error while fetching the images from your site to Nosto’s CDN. If you very recently implemented Nosto occasionally errors might occur and re-indexation of images is needed.

In any case, please review markup-example in tagging guide and then use the Nosto debug-toolbar and check that the image url mapped to Nosto is correct.

If image tagging is correct, there might have been an unusual error with Nosto’s image processing. In this case a manual reindex of product details is required which is launched from the Nosto admin.

In case Nosto is implemented on a site unaccessible from the Internet, this is expected behavior. Read about implementing Nosto on test environments.

New Product Image Doesn’t Update

If you update a new image version for an old product, preferably save the image with a new file name, which typically generates a new image url for the product image as well.

Nosto doesn’t recognize images by file size or image content but by URL, hence if a url for an image is unaltered, Nosto doesn’t update image version in it’s index and uses older version of the product image in recommendations. On the contrary, new products and product images are automatically fetched and processed and no manual input is needed.

Manual re-index for an image version can be launched by enabling debug-mode and clicking Send Product Update Request-button on a product page.

For a full re-index, log in to Nosto’s admin and navigate to Tools > Products > Update products.

Unsharp Images

Typically when an image in a recommendation looks unsharp it’s simply because a small image version is upscaled to a bigger physical area in the template. Applying a bigger image version in a recommendation template will fix the issue, so essentially you simply need to adjust the styling slightly and use a bigger image version stored in Nosto’s CDN

When creating a recommendation template on Nosto Admin Panel, you can choose which image size you would like to use. Nosto doesn’t improve or manipulate pictures, however image versions 1-6 are cropped into squares, sharpened a bit, and zoomed slightly closer to details. Two versions, seven and eight, are original versions, but with aspect limitations of 200px (7) and 400px (8) respectively.

Increased Load Time or Page Size

In the event of slow recommendation load time or increased page size, most likely a Nosto recommendation either uses an original product image or too big image version, which are downscaled to fit a smaller physical area in a browser, making it an opposite scenario to the unsharp images, with different consequences.

Debug by reviewing that the template uses a suitable image version and not an original product image as high-resolution image versions can often exceed size of 1M, consequently slowing down the recommendation load time if multiple products are displayed in a recommendation.

Vertical and Horizontal Product Images

Nosto doesn’t recognize details or tell the difference between horizontal and vertical images, so be sure that most of the details of a product are in the center of the picture. Alternatively you might need to adjust the implementation slightly so that you would consistently map either horizontal or vertical version.

Styling

The content of this page only applies to templates used within:

Product Recommendations
Onsite Content Personalization
Pop-Ups

Styling the recommendations is generally quite straightforward. Just add a style block to the template and use CSS to style the recommendation elements as you would style any HTML content.

Encapsulating styles

While the basic styling of the recommendations works great, it can be problematic if there are multiple recommendation elements on the same page. If styles from different recommendations share the same class names, the last element on the page will override the styles of the previous recommendations.

You can use the $divId variable to print out the current placement ID in the template. Using the variable, you can form CSS selectors that start with the ID of the placement, which limits the scope of the CSS to only the current campaign. You can also target styles to the campaign directly by using the ID selector.

Nested CSS

We recommend the use of Nested CSS for scoped styling of campaign templates due to its more compact syntax and wide browser support.

As most of the recommendation template styles should be scoped to a specific slot, it is common to see scoping structures like this:

#$divId .nosto-block {
  ...
}
#$divId .nosto-header {
 ...
}
#$divId .nosto-list {
 ...
}

which can be expressed like this using nested CSS:

#$divId {
  .nosto-block {
    ...
  }
  .nosto-header {
    ...
  }
  .nosto-list {
    ...
  }
}

To make CSS Nesting in placement and popup templates also available for older browsers that don’t support this feature, the client script provides a polyfill for this. To use the nesting polyfill, you will need to provide the attribute nested on a style element.

Example conversion:

<style nested>
#$divId {
  .wrapper {
    .blue {
      color: blue;
    }
    .red {
      color: red;
    }
  }
}
</style>

becomes the following with divId as nosto-product1:

<style nested data-transpiled="true">
#nosto-product1 .wrapper .blue { color: blue; }
#nosto-product1 .wrapper .red { color: red; }
</style>

The transpilation will be applied in debug mode for all browsers and in normal mode for browsers that don’t support CSS Nesting.

Scripting

The content of this page only applies to templates used within:

Product Recommendations
Onsite Content Personalization
Pop-Ups

Nosto campaign templates support two ways to define JavaScript script elements as part of the templates.

In the legacy mode, the script contents are evaluated in the scope of the nosto iframe and can refer to the main window via the global _targetWindow variable.

To support ES module loading in placement and popup script elements, the client script supports the usage of script[type='module'] elements in both of these contexts. This newer module mode is evaluated in the main window but uses module scope for sandboxing. To write variables to the global scope, you will need to do so explicitly by declaring fields in the window object.

For new accounts, we recommend the use of ES module scripts. For older accounts with existing templates, the legacy script mode works as well, but interaction with the main window is a bit more verbose.

The differences between the two modes are summarized here:

Legacy scripts

Syntax: <script>...</script>
Loaded into the nosto iframe sandbox
Access to the site window happens via the _targetWindow variable
Helper modules in the nosto window namespace are available without a prefix

Module scripts

Syntax: <script type="module">...</script>
Loaded as sandboxed modules into the site window
Site window contents are directly available, e.g., jQuery
Helper modules in the nosto window namespace are available via the nosto. prefix

Examples

becomes

Additionally, module scripts support:

Import syntax

Top-level await

Lightweight sandboxing

Custom logic

If you want to attach stateful logic as event handlers to your template elements, is a useful tool. petite-vue is an alternative distribution of Vue optimized for progressive enhancement. It provides the same template syntax and reactivity mental model as standard Vue. However, it is specifically optimized for "sprinkling" a small amount of interactions on an existing HTML page rendered by a server framework.

Some rules/constraints to consider:

Leave the HTML rendering primarily to Velocity
Maintain minimal state in the Vue context, enough to satisfy your use case
Use a single Vue app context for the whole template
Make sure that the recommendation template renders correctly without the Vue layer

These rules will guide you to use petite-vue within it's intended use cases, for Progressive Enhancement, and not like Vue, a SPA framework.

Some use cases where petite-vue is useful are listed below

Event handlers to call external APIs and libraries

This example is stateless and show cases how functions can be exposed to template

Usage from template

In this case the selection state is kept in petite-vue and hooked into the template

template usage

APIs

GraphQL

GraphQL is a query language for APIs. What does this mean for you? Unlike regular SOAP or REST APIs, GraphQL gives you the ultimate flexibility in being able to specify in your API requests specifically what data you need and get back exactly that.

As a query language, it provides you with a lot of flexibility that most normal APIs will not. Without needing to recreate endpoints, you can provide developers with the same functionality as a bulk endpoint. Your queries will be cleaner and easier to understand by combining multiple queries into one request.

What’s the difference between GraphQL API and the regular API?

The regular API is very well structured and specifically defined. The endpoints have their set requests and responses and that’s what you get whether or not that matches your usage pattern. GraphQL lets you control all of this so that the way you consume the data matches exactly what you need.

This is both a pro and a con. If your use case does not require all of the data, GraphQL can speed up your requests as we do less work on the server-side to fulfill those requests. Conversely, if you need all of the data in one request, your requests could slow down as we do more work to fulfill these requests.

Should I use GraphQL over the regular API?

If you would like to access our intelligence engine, you must use GraphQL. The legacy REST APIs are primarily used for sending orders, products and exchange rates.

Limitations

Geo Segments:

Geo segments rely on the ability to determine the geographical location of the end customer. This typically requires a client-side script that can access the user's IP address. In case of a GraphQL only implementation, this should still be possible if the GraphQL calls are made directly from the end user to Nosto. If the calls are being proxied to a backend server and subsequently forwarded to Nosto, this will essentially hide the end-user's IP from the request and instead, send the backend server IP to Nosto, making it impossible to determine the geolocation of the end user.

The Playground

Start exploring Nosto's GraphQL API on your account. GraphiQL is an in-browser IDE for exploring GraphQL. You don't need any access for using the GraphiQL Explorer.

Toy around, use the API and when you'd like API access to the endpoint for use through a library such as Apollo, please contact support.

Use the embedded GraphiQL explorer below to run queries. The GraphiQL Explorer is accessible at https://my.nosto.com/\[account-id]/graphql (please add your account ID).

Documentation

Documentation is a first-class citizen of GraphQL, and GraphiQL leverages it. The right-hand pane exists for you to explore the possible queries, mutations, fields, their types (if they’re required), the works. Even if your server doesn’t implement human-composed descriptions, you will always be able to explore the graph of possibilities.

Debugging

You don’t even have to read the documentation to discover our API. GraphiQL supports debugging as-you-type, giving hints and pointing out errors.

JSON Viewer

GraphiQL comes with a JSON viewer with all the niceties you’d expect: code folding, automatic indentation, copy support, and read-only so you won’t accidentally delete or edit.

Testing and Debugging

The GraphQL endpoints provide functionality to make it easier to test against a real account.

Ignoring Test Requests

Every operation made against the GraphQL endpoints cause your website's data to be mutated. When doing performance testing or an equivalent, it is often necessary to exclude test traffic so as to not pollute your live account.

Using the header X-Nosto-Ignore: True will cause any traffic from being recorded. Queries and Mutations will work normally but any API calls containing this header will not be archived or accrue towards the statistics.

An example of how this header can be leveraged can be found on our Nosto's GraphQL Android Example app.

Debugging Requests

Every operation made against our GraphQL endpoint returns a unique request identifier contained in an X-Request-Id response header.

While we ensure that the APIs are as robust as possible if you do encounter an HTTP 5XX response from the endpoint, simply log the request identifier along with the error as the unique request identifier allows our engineers to troubleshoot the issue swiftly.

Using Mutations

The mutation methods allow you to change the session on Nosto's end and request personalized recommendations. Each mutation operation allows you to update the cart and customer information, all while giving you access to recommendations for the sessions.

Any mobile experience built atop Nosto's GraphQL API should use the mutation operation as it feeds data into to the recommender systems while providing personalization data.

_The given example updates the customer's information and his current shopping cart contents sends an event that the customer is currently viewing product number 400 and requests the personalized recommendations associated with a given product for him aliased as front_page_1.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation MySession {
  updateSession(id: "ad8f0d0e-1156-4df2-b385-10e03f8f8a44",
    params: {
      customer: {
        firstName: "John"
        lastName: "Doe"
        marketingPermission: true
        customerReference: "319330"
      }
      event: {
        type: VIEWED_PRODUCT
        target: "400"
      }
      cart: {
        items: [
          {
            productId: "100",
            skuId: "100-1",
            name: "#100",
            unitPrice: 199,
            priceCurrencyCode: "EUR",
            quantity: 1
          },
          {
            productId: "200",
            skuId: "200-1",
            name: "#200",
            unitPrice: 299,
            priceCurrencyCode: "EUR",
            quantity: 2
          },
          {
            productId: "300",
            skuId: "300-1",
            name: "#300",
            unitPrice: 399,
            priceCurrencyCode: "EUR",
            quantity: 3
          },
        ]
      }
    }) {
      id,
      recos (preview: false, image: VERSION_8_400_400) {
        front_page_1: related(productIds: ["525834092559"],
          relationship: VIEWED_TOGETHER
          params: {
            minProducts: 3,
            maxProducts: 5
        }) {
        primary {
          productId
        }
      }
    }
  }
}
EOF

Updating Products

Mutations can be used to update the product catalog in Nosto. The updateProducts mutation allows you to update one or more products at a go.

Any validation errors in the product data are accessible in the response. The entire product object is accessible in the response too. In the event that a product validation error led to the product to not be updated, the response would contain the errors as well as the invalid product data.

The given example updates the product #101 and requests the details of the updated products and any associated errors.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  updateProducts(products: [
    {
      productId: "101"
      url: "http://mridang.dev.nos.to:8890/product.htm"
      imageUrl: "https://example.com/product/sku-1.jpg"
      priceCurrencyCode: "EUR"
      price: 10
      skus: [
        {
          id: "sku-1"
          name: "One"
          availability: "InStock"
          price: 100
          listPrice: 111
          imageUrl: "https://example.com/product/sku-1.jpg"
        }
      ]
    }
  ]) {
    result {
      errors {
        field
        message
      }
      data {
        productId
      }
    }
  }
}
EOF

The given example updates the price of #101 and requests the details of the updated products and any associated errors.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  updateProducts(products: [
    {
      productId: "101"
      url: "http://mridang.dev.nos.to:8890/product.htm"
      price: 10
    }
  ]) {
    result {
      errors {
        field
        message
      }
      data {
        productId
      }
    }
  }
}
EOF

Updating Categories

Mutations can be used to update the category listing in Nosto. The upsertCategories mutation allows you to update one or more category at one go. If the category doesn't already exist, a new one is created.

A category can have the following fields:

id The category identifier. If a category with this id doesn't already exist, a new one is created.
name The displayed name for the category.
urlPath The path that can be used to generate the URL of the category listing.
available If the category is visible on the store. This can be set to false to soft delete the category in an upsert.

Some stores support hierarchical categories i.e. a category may have parent and child categories. The following fields can be used for hierarchical categories:

parentId The identifier of the parent category.
fullName The name of every category in the hierarchy.

Updating Identities

Mutations can be used to update the email identities in Nosto. An "identity" is the personal information associated with an email address.

Upserting Identities

The upsertIdentity mutation allows you to upsert the details of an identity. The given example updates the customer attributes for the email [email protected] and requests the details of all the attributes of the identity.

If the identity for [email protected] does not exist, a new identity will be created.

Note: If a specified attribute already exists on that identity, it will be overwritten.

What can identity attributes be used for?

The attributes associated with an identity can be used to segment users. This works similarly to how the attributes can be leveraged .

Deleting Identities

There is currently no way to delete an identity.

Nosto MCP Server (beta)

This MCP server provides a comprehensive set of GraphQL tools for integrating Nosto's personalization and recommendation engine into commerce applications.

Nosto MCP Server is in Beta state, and any generated code should be reviewed.

What is an MCP Server?

MCP (Model Context Protocol) is a standardized protocol that allows AI assistants like Claude to connect to external tools, databases and services. Think of it as a bridge that extends AI assistants capabilities with specialized functionality.

Overview of tools

The Nosto MCP server exposes 7 main GraphQL tools that handle different aspects of Nosto Integration:

Session Managing - Creating and managing user sessions
Event Tracking - Tracking user interactions and behaviour
Recommendations - Fetching personalized product recommendations
Complete Workflows - End-to-end integration patterns
Service Layer - Clean architecture with service classes
Cookie Management - Session persistence via cookies
Concept Explanation - Educational content about Nosto GraphQL concepts

There are also 2 Documentation tools

Feature Documentation - RAG-powered feature documentation search
Technical Documentation - RAG-powered code/technical documentation search

Nosto MCP Server

Server URL https://dev.mcp.nosto.com/mcp

Nosto MCP server specializes in:

Nosto GraphQL API Integration
Multi-framework support (React, Next Js, Shopify Hydrogen, etc.)
Production-ready code generation
Best practives enforcement
Complete workflow documantation
Technical documentation from https://docs.nosto.com

How to use Nosto MCP Server

Nosto MCP server can be used with any AI Assistant that support Model Context Protocol. Claude code is used in the documentation below.

Quick Start with Claude Code

Prerequisites: You need access to Claude Code (Anthropic's IDE integration) to use Nosto MCP servers.

Step 1

Configure MCP

Add the Nosto MCP server to your Claude Code configuration:

{
  "mcpServers": {
    "nosto-graphql": {
       "type": "http",
       "url": "https://dev.mcp.nosto.com/mcp",
       "env": {}
    }
  }
}

Step 2

Verify Connection

Test the connection by asking Claude:

Can you list the available Nosto GraphQL tools?

Claude should respond with the 7 GraphQL specific tools and 2 (RAG) documentation tools.

Step 3

Start Building

Now you can request complete integrations:

Add Nosto product recommendations to my home page

Claude will automatically use the MCP tools to generate complete, production-ready code, including the creation of Nosto specific service, creating a newSession request, storing the sessionId, and calling updateSession and retrieve recommendations.

Reasons to use MCP Server

MCP server is aware of the step by step workflow of how Nosto should be implemented and how graphQL mutations should look. This means that asking AI assistant such as:\

Will look through multiple tools exposed by the Nosto MCP Server

And will generate the Nosto service code which is aware of creating a new session, storing sessionId in the cookie, and using the sessionId for update session mutations and getting recommendations.

End result is visible Nosto recommendations on home and product pages within minutes.

Available GraphQL Integration Patterns

The MCP server provides 7 specialized graphql tools that can be combined. to create complete e-commerce solutions.

Common usage patters:

Homepage integration "Add Nosto Recommendation to my React homepage" -> Uses generate_nosto_service + generate_complete_workflow tools
Product page setup "Set up Nosto on my Shopify Hydrogen product page" -> Uses generate_nosto_service + generate_complete_workflow tools + Includes Shopify GID handling
Explanation of the Nosto "Explain how Nosto can be integrated on my store" -> Uses generate_complete_workflow + concept_explainer

Feedback

If you have found MCP server useful, or if you found some issues or would like MCP server to support more use-cases please don't hesitate to contact us at [email protected]

Working with Orders

GraphQL: Updating Order Statuses

If you would like to update the order-status for a given order, you can do so using the following request.

Querying Products

List Products

Querying products gives access to Nosto's product catalogs current state. It can be useful for backend integration and verification purposes. It is not meant for online use purposes as it doesn't include any concepts related to user sessions or attribution, for those refer to GraphQL For Headless

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  products(
    limit: 5
    offset: 0
    sort: {field: PRICE, reverse:true},
    filter: {categories: "shoes"}
  ) {
    products {
      productId
      url
      price
      categories
    }
  }
}
EOF

The maximum number of products that can be paged over is capped at 10000. If you need to get around this limitation, we recommend adding more restrictive filters to narrow down the result set.

Query by Product ID

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  product(id: "5358") {
    productId
    name
    url
    price
    listPrice
    imageUrl
    attributes {
      key
      value
    }
    skus {
      name
      price
      listPrice
      availability
      imageUrl
      url
    }
  }
}
EOF

Querying Identities

You can query identities using the GraphQL Identities endpoint. An "identity" is the personal information associated with an email address.

So long as you are able to specify the email address, you will be able to query the identity, its associated customer affinity and the personalized recommendations for that identity.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  identity(email:"[email protected]") {
    email,
    attributes {
      name,
      value
    }
    recos(preview: true, image: VERSION_ORIGINAL) {
      history(params: {
        minProducts: 3,
        maxProducts: 10,
        showRelatedProducts: true,
        skipProductsInCart: true,
        skipBoughtProducts: true
      }) {
        primary {
          url
          imageUrl
        }
      }
    }
  }
}
EOF

What can identity attributes be used for?

The attributes associated with an identity can be used to segment users. This works similarly to how the attributes can be leveraged when importing them via a CSV.

Querying Orders

You can query orders using the GraphQL orders endpoint. So long as you are able to specify the order number or an external order reference, you will be able to query the order.

Querying Segments

You can query all the configured segments using the GraphQL Segments endpoint. You are able to query all the names and identifiers of the segments.

Sample Output

Querying Search

Search GraphQL API uses different API endpoint. For more information see:

For iOS & Android

GraphQL is a query language for the APIs for getting your data. It is an alternative for the REST APIs. It is not specific to a single platform and works for all type of clients including Android, iOS or the web. It stands between your server and client and helps you to query your data in a more optimized way.

Building for Android

If you would like to leverage Nosto's intelligence engine in your Android app, please see our example app and the docs.

Building for iOS

Leveraging Nosto's intelligence engine on iOS is just as easy as on Android. While an example app is yet to be provided, please read the Apollo docs.

REST

Nosto offers a multitude of APIs for different use cases. The APIs are not entirely RESTful but provide lightweight endpoints that expose similar usability.

All the APIs reside at https://api.nosto.com and must be accessed over HTTPS.

Note: If you happen to call the interface via HTTP using a valid API key, that API key will be invalidated immediately and a notice of the token revocation will be sent to the account owner.

Authentication

Authenticating with the API is done by using . You authenticate by using your API key as the password and the username is left empty.

You can see your API keys in the Nosto Backend under account settings. API key is always tied to a single store in your account.

Note: Keep your API key secret and delete it immediately if you think someone untrusted might have had access to it.

HTTP Header

Value

Requesting access

To get access to our APIs, please log in to your Nosto account at and contact support via chat. When you request API access, please provide following information:

What is the API in question?
What is the purpose for the API use?
What is the volume of requests?
What is the request distribution, on-demand or periodic?

Token types

You can get token values from page under your Nosto Account. Each set of endpoints are secured using different token types.

Token type

Description

Rate Limits

Nosto does not rate-limit the API usage but follows a fair-use policy. Nosto reserves the right to revoke API access for any abusive API usage patterns.

GDPR

Redacting customer data

This endpoint is used for redacting all personal data associated with an email. All requests to these endpoints are asynchronous and simply enqueue the email address for redaction. It may take up to 24 hours for the redaction process to complete. If the email address is found, a notification email (informing you about the redaction) will be sent once the process has completed.

Token

This endpoint requires an Email token.

Usage

Initiating data takeouts

This endpoint is used for initiating a personal-data takeout request. All requests to this endpoint are asynchronous and simply enqueue the email address for takeout. It may take up to 24 hours for the takeout process to complete. If the email address is found, a notification email (informing you about the takeout request) will be sent once the process has completed.

Token

This endpoint requires an Email token.

Usage

curl -v -X POST https://api.nosto.com/v1/customers/takeout/[email protected] \
--user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw

Customers

Blacklisting Customers

This endpoint is used for blacklisting email addresses from receiving Nosto's triggered emails such as cart-abandonment emails, order-follow emails, and we-miss-you emails.

Having the corresponding email address in our system prior to blacklisting or unblacklisting is not a prerequisite. If the specified email record does not exist in our system, it will be created.

Token

This endpoint requires an Email token.

Blacklisting an email

You can specify multiple email addresses separated by a newline.

Unblacklisting an email

You can specify multiple email addresses separated by a newline.

Toggling marketing consent

This endpoint is used for toggling the marketing permission for an email. The marketing permission for an email is normally gathered .

This endpoint is only intended for use when the consent needs to be programmatically managed and should be a considered an advanced use case.

Token

This endpoint requires an Email token.

Usage

Products

Implementing Search page

Configuration

To create a search application, call the init function with your configuration. This will create a new Preact application that renders on the specified contentCssSelector. It will also bind to the input element identified by the provided inputCssSelector and execute a search upon form submission.

index.js

import { init } from '@nosto/preact'

import serpComponent from './serp'

init({
    ...window.nostoTemplatesConfig,
    serpComponent,
    inputCssSelector: '#search',
    contentCssSelector: '#content',
    serpPath: '/search',
    serpPathRedirect: true,
    formCssSelector: '#search-form',
    formUnbindDelay: 1000, // 1 second
    serpUrlMapping: {
        query: 'q',
    },
    serpQuery: {
        products: {
            size: 20,
            from: 0,
        },
    },
})

Serp query parameter flavors

In the example above, we supply serp query parameters as an object. Additionally, the serpQuery parameter can also be supplied as a function. The function flavor can be used for building complex query parameters and provides access to other pre-defined configuration parameters.

Using variationId for price variations

When you have price variations in use, provide the product variation ID by accessing the pre-defined variationId method from the default configuration:

index.js

import { init } from '@nosto/preact'

import serpComponent from './serp'

init({
    ...window.nostoTemplatesConfig,
    serpComponent,
    inputCssSelector: '#search',
    contentCssSelector: '#content',
    serpPath: '/search',
    serpPathRedirect: true,
    formCssSelector: '#search-form',
    formUnbindDelay: 1000, // 1 second
    serpUrlMapping: {
        query: 'q',
    },
    serpQuery() {
        return {
            products: {
                size: 20,
                from: 0,
                variationId: this.variationId()
            },
        }
    }
})

Using currency for exchange rates

When you use exchange rates for multi-currency support, use the currency parameter instead:

index.js

import { init } from '@nosto/preact'

import serpComponent from './serp'

init({
    ...window.nostoTemplatesConfig,
    serpComponent,
    inputCssSelector: '#search',
    contentCssSelector: '#content',
    serpPath: '/search',
    serpPathRedirect: true,
    formCssSelector: '#search-form',
    formUnbindDelay: 1000, // 1 second
    serpUrlMapping: {
        query: 'q',
    },
    serpQuery() {
        return {
            products: {
                size: 20,
                from: 0,
                currency: this.variationId()
            },
        }
    }
})

The full list of Configuration options is documented here

Search page redirect

When serpPathRedirect parameter is set to true, the application after search submission will redirect the browser to the search page specified in serpPath. Default behavior will only rewrite browser history to the specified path, without reloading the page.

In many cases, the search/autocomplete input is located on a different page from the search results. For example, on the landing or home page; or it may be always visible in the store's header. For those cases, it may be desired to redirect the user to the search results when a search request is submitted. If search page redirect is not configured, Nosto integration assumes that the search results should be rendered on the current page.

The redirect is controlled by two configuration variables:

serpPath (string) - specifies the path to the search page (follows the browser's location.pathname).
serpPathRedirect - (boolean or function) - combined variable that controls whether or not the redirect is enabled, and also provides a custom navigation mechanism if necessary.

When serpPathRedirect is omitted or set to false, the default behaviour is to update the browser's history (i.e. rewrite the current URL) to add the search query parameter.

When serpPathRedirect is set to true, the browser will redirect to the search page indicated by serpPath upon search submission. The default mechanism is location.href = {targetUrl} . If the current page already matches the search path, the search query parameter will be added instead.

When serpPathRedirect is set to a function, it will be called instead of setting location.href . This is useful to, for example, interact with your frontend framework, inject custom logic before redirect or handle special cases for redirect. For example:

init({
    serpPath: '/search',
    serpPathRedirect: (query: SearchQuery, options: AutocompleteOptions | undefined) => {
        location.href = `https://store.com/search/${query?.query}` // Query as a path param
    },
})

In function form, serpPathRedirect exposes the main query object that holds the data which would instead be send to Nosto. The second object simply holds information about the click.

export interface AutocompleteOptions {
    isKeyword?: boolean // true if the user clicked on a suggested keyword
}

Checkout our API documentation on serpPathRedirect

Unbinding existing search input

To prevent events from firing on an existing input, you need to provide the CSS selector of the form that the input is in to the initialization configuration. When optional fromCssSelector is passed, it will unbind the form and the elements inside from existing events. Additionally, formUnbindDelay in milliseconds as value can be passed to delay the unbinding functionality.

Serp component

The search results page component should render a full search page using the provided app state. A minimal example might look like this:

serp/index.js

import { useAppStateSelector, SerpElement } from '@nosto/preact'

export default () => {
    const { products, loading } = useAppStateSelector((state) => ({
        products: state.response.products,
        loading: state.loading,
    }))

    return (
        <div>
            {loading && <div>Loading...</div>}
            {products.total ? <div>
                {products.hits.map(hit => <SerpElement as="a" hit={hit}>
                    {hit.name}
                    {hit.price} 
                </SerpElement>)}
            </div> : <div>
                No results were found
            </div>}
        </div>
    )
}

Automatic URL Parameter Compression

When the compressUrlParameters flag is set to true, it automatically applies the URL parameter compression functions for filters, sort and pagination.

Checkout our API documentation on compressUrlParameters

import { init } from '@nosto/preact'

import serpComponent from './serp'

init({
    ...window.nostoTemplatesConfig,
    serpComponent,
    inputCssSelector: '#search',
    contentCssSelector: '#content',
    serpPath: '/search',
    serpPathRedirect: false,
    serpUrlMapping: {
        query: 'q',
        'products.page': 'page'
    },
    compressUrlParameters: true,
    serpQuery: {
        products: {
            size: 20,
            from: 0,
        },
    },
})

@nosto/preact library has pre-built functions for changing search url format:

Description

Example

Pagination

Replaces from parameter with page number.

Before: /search?products.from=20&q=shorts After: /search?page=2&q=shorts

Sorting

Returns shorter sort parameters.

Before: /search?q=shorts&products.sort.0.field=price&products.sort.0.order=desc After: /search?q=shorts&products.sort=price~desc

Filtering

Compresses filter parameters. Multiple filter values are separated by a comma, which is encoded. This is because filter values can contain non-alphanumeric letters themselves.

Before: /search?q=shorts&products.filter.0.field=customFields.producttype&products.filter.0.value.0=Shorts&products.filter.0.value.1=Swim&products.filter.1.field=price&products.filter.1.range.0.gte=10&products.filter.1.range.0.lte=30 After: /search?q=shorts&filter.customFields.producttype=Shorts%7C%7CSwim&filter.price=10~30

Product thumbnails

Product thumbnails are supported via decorators that augment the product data returned by the Nosto Search service.

The following example shows modifications to the init call to make product thumbnails available in the result data:

import { init, thumbnailDecorator, priceDecorator } from "@nosto/preact"

init({
    ...window.nostoTemplatesConfig,
    ...
    serpQuery: {
        products: {
            fields: [
                ...
                // needed for thumbnailDecorator
                "imageHash"
            ],
            facets: ["*"],
            size: defaultConfig.serpSize,
            from: 0
        }
    },    
    hitDecorators: [
        thumbnailDecorator({ size: "9" })
    ]
})

The thumbnailDecorator takes a size argument and requires the following additional fields to be made available in the result set for accurate thumbnails:

imageHash for imageUrl thumbnails
thumbHash for thumbUrl thumbnails
alternateImageHashes for alternateImageUrls thumbnails
sku.imageHash for sku.imageUrl thumbnails

The supported sizes are

Code

Description

170x170 px

100x100 px

90x70 px

50x50 px

30x30 px

100x140 px

200x200 px

400x400 px

750x750 px

Original (Square)

200x200 px (Square)

400x400 px (Square)

750x750 px (Square)

The same mapping will also be attempted for SKU level data

Checkout our API documentation on thumbnailDecorator

Currency formatting

Currency formatting is implemented via the priceDecorator decorator function.

The priceDecorator utilizes the currency formatting definitions of the Nosto account to format prices into priceText and listPriceText fields, covering both product and SKU level data.

Include Required Fields
- The fields required for this mapping are:
- price will be formatted to priceText
- listPrice will be formatted to listPriceText
- priceCurrencyCode will be used as the currency code
Use the priceDecorator The priceDecorator is responsible for formatting prices into text fields using above mentioned fields.

A complete example of the Search-templates configuration for price variations:

import { init, priceDecorator } from "@nosto/preact";

init({
    ...window.nostoTemplatesConfig,
    ...
    serpQuery() {
        return {
            products: {
                variationId: this.variationId(),
                fields: [
                    // needed for priceDecorator
                    "price", 
                    "listPrice",
                    "priceCurrencyCode",
                ],
                size: 20,
                from: 0
            }
        }    
    },
    hitDecorators: [
        priceDecorator()
    ]
});

For exchange rates, use currency instead:

import { init, priceDecorator } from "@nosto/preact";

init({
    ...window.nostoTemplatesConfig,
    ...
    serpQuery() {
        return {
            products: {
                currency: this.variationId(),
                fields: [
                    // needed for priceDecorator
                    "price", 
                    "listPrice",
                    "priceCurrencyCode",
                ],
                size: 20,
                from: 0
            }
        }    
    },
    hitDecorators: [
        priceDecorator()
    ]
});

Checkout our API documentation on priceDecorator

Multi-Currency

To enable multi-currency functionality in search templates, follow these steps:

Enable Multi-Currency in Nosto Admin - Enabling multi-currency from the admin
Choose the appropriate parameter based on your setup:
- Use variationId: this.variationId() when you have price variations in use
- Use currency: this.variationId() when you use exchange rates for multi-currency support

Price variations example

When using price variations, include the variationId parameter in your search query:

import { init } from "@nosto/preact";

init({
    ...window.nostoTemplatesConfig,
    ...
    serpQuery() {
        return {
            products: {
                variationId: this.variationId()
                ...
            }
        }
    }
});

Exchange rates example

When using exchange rates, include the currency parameter in your search query:

import { init } from "@nosto/preact";

init({
    ...window.nostoTemplatesConfig,
    ...
    serpQuery() {
        return {
            products: {
                currency: this.variationId()
                ...
            }
        }
    }
});

Query parameter mapping

In addition to the compressUrlParameters flag the serpUrlMapping should be used to control the mapping from URL parameter keys to paths in the internal query object. The default looks like this:

serpUrlMapping: {
  query: "q",
  "products.filter": "filter",
  "products.page": "page",
  "products.sort": "sort"
}

The key is the internal path in the query model and the value is the query parameter name that should be used in the URL.

Features

Stats facet

The stats facet returns the minimum and maximum values of numerical fields from search results. This functionality is especially useful when creating interactive elements such as sliders and range selectors. For instance, a price slider can use these min-max values to define its adjustable range, providing a simple way for users to filter products within a specific price range. Similarly, these values are utilized in the RangeSelector to define the overall scope of range selections, allowing for the configuration of selection precision through the range size parameter.

Range Slider

Utilize the useRange ( or previously useRangeSlider ) hook to generate useful context for rendering range inputs. Additionally, employ the component to generate the interactive slider itself. These tools together facilitate the creation of dynamic and interactive range sliders for your application.

Example #1:

with useRange

import { useRange } from "@nosto/search-js/preact/hooks";
import { useState } from "react";

const Component = ({ facetId }) => {
  const { min, max, range, active, toggleActive, updateRange } = useRange(facetId);
  
  return (
    <div>
      <button onClick={() => toggleActive()}>
        {active ? "Hide" : "Show"} Range Filter
      </button>
      {active && (
        <div>
          Current Range: {range[0]} to {range[1]}
          <button onClick={() => updateRange([min, max])}>Reset Range</button>
        </div>
      )}
    </div>
  );
};

Example #2

with useRangeSlider (legacy)


import { RangeSlider, useRangeSlider } from '@nosto/preact'

export default ({ facet }) => {
    const {
        min,
        max,
        range,
        updateRange
    } = useRangeSlider(facet.id)

    return  <div>
        <h2>{facet.name}</h2>
        <label>
            Min.
            <input type="number" value={range[0]} min={min} max={max} onChange={(e) => {
                const value = parseFloat(e.currentTarget.value) || undefined
                updateRange([value, range[1]])
            }}/>
        </label>
        <label>
            Max.
            <input type="number" value={range[1]} min={min} max={max} onChange={(e) => {
                const value = parseFloat(e.currentTarget.value) || undefined
                updateRange([range[0], value])
            }} />
        </label>
        <RangeSlider id={facet.id} />
    </div>
}

Checkout our API documentation for useRangeSlider hook

useRangeSlider has been renamed to useRange but the older useRangeSlider name is still supported for backward compatibility.

Range Selector

If you require an alternative method where values are selected through radio buttons rather than a slider, consider using useRangeSelector hook. This tool allows users to choose from predefined range intervals with radio buttons, offering a different interaction style.

The range size parameter in the useRangeSelector hook specifies the size of each interval in the range and determines the total number of range items displayed. Additionally, it automatically rounds the minimum value down to ensure intervals are aligned with the specified range size.

For example, if the minimum product price in the current catalog is 230, and the maximum product price is 1000, the range size of 200 will adjust the starting point to 200 and create intervals displayed under the "Price" filter as follows:

200 - 400
400 - 600
600 - 800
800 - 1000

import { useRangeSelector } from "@nosto/preact"
import { useState } from "preact/hooks"
import RangeInput from "./elements/RangeInput"
import Icon from "./elements/Icon"
import RadioButton from "./elements/RadioButton"

export default function RangeSelector({ facet }) {
    const {
        min,
        max,
        range,
        ranges,
        updateRange,
        handleMinChange,
        handleMaxChange,
        isSelected
    } = useRangeSelector(facet.id, 100)
    const [active, setActive] = useState(false)

    return (
        <li>
            <div>
                <ul>
                    {ranges.map(({ min, max, selected }, index) => {
                        return (
                            <li
                            >
                                <RadioButton
                                    key={index}
                                    value={`${min} - ${max}`}
                                    selected={selected}
                                    onChange={() => updateRange([min, max])}
                                />
                            </li>
                        )
                    })}
                    <div>
                        <div>
                            <label for={`ns-${facet.id}-min`}>
                                Min.
                            </label>
                            <RangeInput
                                id={`ns-${facet.id}-min`}
                                min={min}
                                max={max}
                                range={range}
                                value={range[0] ?? min}
                                onChange={e => handleMinChange(parseFloat(e.currentTarget.value) || min)}
                            />
                        </div>
                        <div>
                            <label for={`ns-${facet.id}-max`}>
                                Max.
                            </label>
                            <RangeInput
                                id={`ns-${facet.id}-max`}
                                min={min}
                                max={max}
                                range={range}
                                value={range[1] ?? max}
                                onChange={e => handleMaxChange(parseFloat(e.currentTarget.value) || max)}
                            />
                        </div>
                    </div>
                </ul>
            </div>
        </li>
    )
}

Checkout our API documentation on useRangeSelector

Terms facet

The terms facet returns field terms for all products found in the search. This feature analyzes the content of each product and extracts meaningful terms. These terms can then be used to filter or refine search results, providing users with a more accurate and targeted product search.

import { useActions } from '@nosto/preact'

export default ({ facet }) => {
    const { toggleProductFilter } = useActions()

    return <div>
        <h2>{facet.name}</h2>
        <ul>
            {facet.data?.map((value) => <li>
                <label>
                    {value.value}
                    <input
                        type="checkbox"
                        checked={value.selected}
                        onChange={(e) => {
                            e.preventDefault()
                            toggleProductFilter(
                                facet.field,
                                value.value,
                                !value.selected
                            )
                        }}
                    />
                </label>
                ({value.count})
            </li>)}
        </ul>
    </div>
}

You can use the toggleProductFilter function to toggle any filter value. This function will either add the filter value if it's not already applied or remove it if it's currently active, thus providing an efficient way to manipulate product filters in your application.

Checkout our API documentation on useActions hook

Pagination

Use the usePagination hook to generate useful context for rendering any desired pagination. Utilize the width parameter to adjust how many page options should be visible. Also, remember to scroll to the top on each page change to ensure a seamless navigation experience for users.

serp/pagination.jsx

import { usePagination, useActions } from '@nosto/preact'

export default () => {
    const pagination = usePagination({
        width: 5
    })
    const { updateSearch } = useActions()
    
    const createCallback = (from) => () => {
        updateSearch({
            products: {
                from,
            },
        })
        scrollTo(0, 0)
    }

    return (
        <ul>
            {pagination.prev && <li>
                <a
                    href="javascript:void(0)"
                    onClick={createCallback(pagination.prev.size)}
                >
                    prev
                </a>
            </li>}
            {pagination.first && <li>
                <a
                    href="javascript:void(0)"
                    onClick={createCallback(pagination.first.from)}
                >
                    {pagination.first.page}
                </a>
            </li>}
            {pagination.first && <li>...</li>}
            {pagination.pages.map((page) => <li class={page.current ? "active" : ""}>
                <a
                    href="javascript:void(0)"
                    onClick={createCallback(page.from)}
                >
                    {page.page}
                </a>
            </li>)}
            {pagination.last && <li>...</li>}
            {pagination.last && <li>
                <a
                    href="javascript:void(0)"
                    onClick={createCallback(pagination.last.from)}
                >
                    {pagination.last.page}
                </a>
            </li>}
            {pagination.next && <li>
                <a
                    href="javascript:void(0)"
                    onClick={createCallback(pagination.next.offset)}
                >
                    <span aria-hidden="true">
                        <i class="ns-icon ns-icon-arrow"></i>
                    </span>
                </a>
            </li>}
        </ul>
    )
}

Checkout our API documentation on usePagination hook

Infinite Scroll

Nosto search-templates library provides a simple out-of-the-box solution to implement infinite scroll functionality. Simply wrapping your product rendering with the <InfiniteScroll> component is generally enough.

As the user scrolls the page down, the wrapper will detect it using the IntersectionObserver. If it is not supported by the user's browser, a 'load more' button will be shown instead.

Infinite scroll works best when the product images have a pre-defined aspect ratio.

serp.jsx

function Products() {
    const products = useAppStateSelector(state => state.response.products)

    return (
        <>
            {products.hits.map((hit, index) => {
                return <Product product={hit} key={hit.productId ?? index} />
            })}
        </>
    )
}

function SerpInfiniteScroll() {
    return (
        <InfiniteScroll>
            <Products />
        </InfiniteScroll>
    )
}

Checkout our API documentation on InfiniteScroll

Observer options

To achieve a smoother scrolling experience, the InfiniteScroll component accepts an optional prop called observerOptions. This prop allows you to customize the behavior of the Intersection Observer API, which is used to detect when the scroll trigger comes into view.

serp.jsx

    <InfiniteScroll observerOptions={{
        rootMargin: "100px"
    }}>
        <Products />
    </InfiniteScroll>

The observerOptions prop accepts the same parameters as the IntersectionObserver options.

Persistent Search Cache

When using infinite scroll, consider enabling persistent search cache as well. When this feature is enabled, the latest search API response will be automatically cached and stored in the browser's session storage.

This improves the user experience significantly when the user navigates from a product details page back into the search results using the browser's 'back' function. The data necessary to display the products is already available, and the user will see the products immediately, without waiting for them to load again.

This feature is useful for both paginated and infinite scroll, but the benefits are significantly more visible with the latter.

import { init } from '@nosto/preact'

init({
    ...otherFields,
    persistentSearchCache: true,
})

Checkout our API documentation on persistentSearchCache

Product actions

Since the code editor utilizes the Preact framework, it offers significant flexibility in customizing behavior or integrating the search page with existing elements on your site. For instance, you can implement actions such as 'Add to Cart', 'Wishlist', or 'Quick View'.

serp/Product.jsx

import { SerpElement } from '@nosto/preact'
import { useState } from 'preact/hooks'

export default ({ product }) => {
    const [addedToCart, setAddedToCart] = useState(false)
    
    return (
        <SerpElement
            as="a"
            hit={product}
        >
            <img src={product.imageUrl} />
            <div>
                {product.name}
            </div>
            <button
                // Allow the button to be clicked only once
                disabled={addedToCart}
                // Add the product to the cart when the button is clicked
                onClick={(event) => {
                    // Don't navigate to the product page
                    event.preventDefault()

                    // Update the button text and disable it
                    setAddedToCart(true)

                    // Add the product to the cart, this depends on the cart implementation
                    jQuery.post('/cart/add.js', {
                        quantity: 1,
                        id: product.productId,
                    })
                }}
            >
                // Show different text if product was added to the cart
                {addedToCart ? 'Added to cart' : 'Add to cart'}
            </button>
        </SerpElement>
    )
}

Handling native results

Nosto will attempt to display the original search results in case Nosto service is unavailable or can't be reached. In addition, the original products are made available for the SEO crawlers, improving the page's ranking in the search engines. To make it possible, it's recommended to hide the original search results instead of removing or blocking them.

In addition, you should define CSS to hide the target element:

css

.ns-content-hidden {
    display: none;
    /* Or other styles as needed */
}

Analytics

Search automatically tracks to Google Analytics & Nosto Analytics when using SerpElement component.

export default ({ product }) => {
    return (
        <SerpElement as="a" hit={product}>
            {product.name}
        </SerpElement>
    )
}

Component parameters:

hit

Product object.

Element to render <SerpElement /> as. Recommended to use as="a". If a element is used, href attribute is added automatically.

onClick (optional)

Additional onClick callback (tracking callback is already implemented in the component).

The SerpElement component supports any other HTML attribute, e.g. class.

Checkout our API documentation on SerpElement

Fallback Functionality

The search page incorporates built-in fallback functionality, allowing users to customize the behavior in case the search service encounters issues. To activate this feature, modify the initialization configuration to include the fallback: true key-value pair.

Enabling Fallback

To enable fallback functionality, include the following code in the initialization configuration:

import { init } from '@nosto/preact'

init({
    ...window.nostoTemplatesConfig,
    fallback: true,
})

Once fallback is enabled, if the search request fails to retrieve data, the search functionality will be temporarily disabled for 10 minutes, and the original content Nosto has overridden will be restored.

The fallback: true setting only works out of the box if the path is the same for both the dedicated Nosto search page and the native search page, as well as for category pages.

If the paths differ, you must configure the serpFallback or categoryFallback function to ensure proper redirection. See: Customizing Fallback Location

Alternative Fallback Behavior

If the behavior described above is undesirable, the configuration supports an alternative option. Fallback mode can be set to fallback: 'legacy', in which case the user will see a page reload if the search request fails. After that, Nosto will not attempt to override the original search results or category pages for 10 minutes.

This behavior has been the default fallback behavior before August 20, 2024.

import { init } from '@nosto/preact'

init({
    ...window.nostoTemplatesConfig,
    fallback: 'legacy',
})

Customizing Fallback Location

Additionally, it's possible to customize the location to which users are redirected when the search functionality is unavailable. This customization involves specifying functions for both the search engine results page (SERP) and category pages.

SERP Fallback

To redirect users to a specific location when the search engine is down, define a function for serpFallback. This function accepts one parameter containing information about the current search query, including the query itself.

import { init } from '@nosto/preact'

init({
    ...window.nostoTemplatesConfig,
    fallback: true,
    serpFallback: (searchQuery) => {
        location.replace(`/search?q=${searchQuery.query}`);
    },
})

Category Fallback

Similarly, for category pages, define a function for categoryFallback. This function also accepts one parameter containing information about the current query, including the category ID or Path.

import { init } from '@nosto/preact';

init({
    ...window.nostoTemplatesConfig,
    fallback: true,
    categoryFallback: (query) => {
        location.replace(`/categories/${query.products.categoryId}`);
    },
});

By customizing these fallback locations, you can enhance the user experience by providing them with alternative navigation options if the search functionality is temporarily unavailable.

Search engine configuration

Nosto Search engine is relevant out of the box and search API can be used without any initial setup. Nosto Dashboard can be used to further tune search engine configuration:

Searchable Fields - manage which fields are used for search and their priorities,
Facets - create facets (filtering options) for search results page,
Ranking and Personalization Ranking and Personalization - manage how results are ranked,
Synonyms, Redirects, and other search features are also managed through Nosto Dashboard (my.nosto.com).

Techdocs

Introduction

Implementing Nosto

Implement on your website

Choosing the implementation method

SPA / PWA on top of a platform that Nosto has extension for

When dynamic functionality is needed / no page reload

Manual Implementation - Essentials

Setting up your account

Adding the Nosto Script

Troubleshooting Nosto script:

Adding the Cart Tagging

Dynamic cart changes

Adding support for advanced use cases

Tagging the cart restore link

Troubleshooting

Translate attribute

Adding the Customer information

Tagging marketing permission

Tagging customer reference

Adding the Product Tagging

Basic Tagging

Via an API

Via a Feed

Troubleshooting

Translate attribute

Adding the Category/Brand Tagging

Tagging the categories

Faceting by other attributes

Tagging the current page type

Troubleshooting

Translate attribute

Adding the Search Tagging

Adding the Order Tagging

Tagging the buyer

Tagging the currencies

Tagging the payment provider

Tagging the order status code

Adding support for advanced use cases

Troubleshooting order tagging:

Translate attribute

Defining Nosto placements

Traditional div-element approach

Web component approach with <nosto-campaign>

Basic usage

Advanced features

When to choose each approach

Setup and integration

Tagging your page types

Advanced Usage

Parameterless Attribution

Product url redirects

Session API based usage

Reliance on the legacy nosto parameters

JSON Rendering Attribution

Attribution in custom element based Nosto campaign rendeirng

Rendering of campaign markup in non-managed placement elements

Adding support for multi-currency

Shopify Multi-Currency

Changes to the product tagging

Do child-products (SKUs) support multi-currency?

What about the prices in the cart and the order tagging?

Specifying the active currency

Sending the exchange-rates

Enabling multi-currency from the admin

Integration with search/category merchandising (universal)

Reviewing your changes

See also

Adding support for customer group pricing

Changes to the product tagging

What about the prices in the cart and the order tagging?

Specifying the active variation

Integration with search/category merchandising (universal)

Enabling multi-variants from the admin

Reviewing your changes

See also

Event API: Listening to Bus Events with api.listen

Overview

Example Usage

Supported BusEvent Types

Web component approach with `<nosto-campaign>`

Supported `BusEvent` Types

1. Configure the `DynamicCardProduct` Component