We are glad to have you as a partner and want to help you get running with Nosto as soon as possible while making it as easy as possible for you.

Our material consists of a general introduction to how Nosto works, additional in-depth information and examples for every product with its possible implementation methods as well as comprehensive API references.

We appreciate your professionalism and understanding that we can't document every single use case. We are confident you'll find everything needed to deliver on your requirements. Custom cases need custom solutions and we'll guide you in the right direction.

If you ever feel stuck, something is confusing or misleading, please contact us so we can a) support you and b) update our information.

It is tempting to skim the headings of a documentation (we feel you and know you want to get back to coding asap). We also understand that you want to make sure you can cover all the complexity for your client and site.

From our experience, there is always added frustration and costs due to several added feedback loops when we take shortcuts in the beginning. You and your client will get the most out of your time and the Nosto platform when you:

• Set aside one hour to read this guide and write down all questions or concerns you might have.

• Use our onboarding team to consult and assist you with best practices. We are there to help you with troubleshooting.

• Focus on the basics first before addressing the complex use cases (although we know they are more fun).

• Use the product as it is intended. This is the most common pitfall: After hours and hours of complex programming it often turns out there already is a functionality inside the platform which is configured with only a few clicks.

• Don't just copy & paste the code examples. Yes, it happens. To improve readability, our examples give you an overview with only the most relevant data/parameters. We don't want to clutter your mind, so please refer to the API references for an extensive overview.

We are happy to with any question regarding the details and are confident you will be able to solve 90% of your questions with this guide.

Pro Tip: Let us review your project plan/milestones before you get started.

We can't stress this enough: When the basics are missing, the more advanced features won't work as intended and you will become very frustrated.

Therefore, please make sure to fill up your brand-new car with the right fuel before taking it for a spin around the neighborhood.

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:

1. 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.

2. 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.

Nosto replicates an eCommerce site’s product catalog (one account per domain/language) as the foundation for all Nosto modules. You might need to adjust the product data structure, so please let us know about your parent/child relationships, customer groups (pricing and visibility) and how you handle translations and multiple currencies (fixed prices or exchange rates).

Nosto then does two basic things onsite:

1. Profile creation: Track what a user is doing on an eCommerce site (which pages (landing page, product page, category page, …) shoppers look at and what they buy).

   • This data is sent to the Nosto backend so we can understand and present insights to the client in our dashboard.

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.

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

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.

The full schema for customer tagging is defined

or via DOM tagging

Fundamentally, Nosto needs a replica of the client's product catalog with price and currency information, parent/child relations, categories, custom fields, tags, stock/inventory information, etc..

To achieve the onsite functionalities, Nosto must be able to do these things:

1. Know on which page the users are.

2. Know what data is on a page (what product, what category, …).

3. Know specific things about the current user (on all pages):

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

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:

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.

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

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:

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:

Read more about implementing Nosto with GraphQL on IOS and Android:

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.

See to see more detailed documentation of the library.

Nosto offers different APIs to use and they all mostly offer the same functionality (in some cases you’ll face a classical trade-off battle). That’s why it’s important to not just look at what you want to achieve, but what setup you currently have (and what your client needs).

We want to make the implementation as easy and clean for you as possible. We don’t want you to bloat up your code or you to do unnecessary things.

Therefore, please take a few minutes and write down the answers to the following questions so we can prevent future headaches (and save a lot of time and money):

1. Is your client’s site running on a major eCommerce platform like Magento 2, Shopify, Shopware, BigCommerce, Prestashop or Salesforce?

2. Have you decoupled the frontend from the backend/are you running a headless frontend? (incl. Magento 2 Hyvä, React, Next.js or Shopify Hydrogen)

3. Is the frontend a single-page-application (SPA) or a progressive-web-app (PWA) where the URL never changes when a user browses the site?

4. Does your client have an international/localized setup with multiple currencies and/or languages?

5. Does your client have multiple customer groups?

We will ask you for these answers in our kickoff meeting and will craft the mutual project plan accordingly.

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

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

Production Deployment

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

1. Test thoroughly in preview mode

2. Navigate to Nosto Admin UI > Search > Templates

3. 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

1. Navigate to the Nosto Admin UI > Search > Templates

2. 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?

1. Navigate to the Nosto Admin UI > Search > Templates

2. Click on the Disable Templates button.

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.

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

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.

nostojs(api => {
   var request = api.createRecommendationRequest()
     .addEvent('vp', "product-id", "placement-id")
     .loadRecommendations();
});

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

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.

The query methods allow you to fetch basic recommender data and does not require any sessions. Query operations are light and do not give you the benefit of personalization but can be used to fulfill simple use cases e.g. an in-store display that always shows the top 10 viewed products.

_The given example simply fetches products related to a given search term aliased as q_related and also fetches the most viewed products within the last week.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  recos (preview: false, image: VERSION_7_200_200) {
    hot_now: toplist(hours: 168, sort: VIEWS, params: {
      minProducts: 1
      maxProducts: 10
    }) {
      primary {
        name
        productId
      }
    }
    q_related: search(term: "black", params: {
      minProducts: 1
      maxProducts: 10
    }) {
      primary {
        name
        productId
      }
    }
  }
}
EOF

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.

When implementing in SPA and PWA environments, product updates must be done via . 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 . Note that you cannot mix Session API and Page Tagging.

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:

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.

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:

1. make it publicly available using a service such as or

2. Use the to keep your catalog in sync

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

  • Adding the Nosto Script

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

• Manual Implementation - Advanced

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

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

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

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

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

You can install the Nosto Autocomplete library via npm:

npm install @nosto/autocomplete

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:

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.❗

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.

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.

How It Works

1. State Management: The SearchQueryHandler component (src/components/SearchQueryHandler/SearchQueryHandler.tsx) is responsible for synchronizing the application's search state with the URL.

2. 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.

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

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.

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.

How to use debug toolbar to preview search

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:

1. Navigate to your website

2. In the URL, append ?nostodebug=true to enable the debug toolbar

3. The Nosto debug toolbar should open up, where you will be asked to log in

4. Once you have logged in, enable the Preview toggle button at the bottom

5. 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

Test both mobile & desktop view using Chrome .

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.

or via DOM tagging

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:

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 .

• 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 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 .

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.

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.

If you are running a headless frontend or SPA (Single Page Application), you will follow the same approach using the Nosto Session API. Please read more on the , and (instead of page 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.

or via DOM tagging

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

or via DOM tagging

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.

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

• Enter key press.

• Submit button click.

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+

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.\

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

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

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.

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.

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.

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.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  segments{
    segments{
      id,
      name
    }
  }
}
EOF

Sample Output

{
  "data": {
    "segments": {
      "segments": [
        {
          "id": "5a497a000000000000000001",
          "name": "First-Time Visitors"
        },
        {
          "id": "5b71f1500000000000000006",
          "name": "Returning Visitors"
        },
        {
          "id": "5a497a000000000000000002",
          "name": "Prospects"
        },
        {
          "id": "5a497a000000000000000003",
          "name": "First-Time Customers"
        },
        {
          "id": "5a497a000000000000000004",
          "name": "Repeat Customers"
        },
        {
          "id": "5a497a000000000000000005",
          "name": "Loyal Customers"
        },
        {
          "id": "5a497a000000000000000000",
          "name": "All Customers"
        }
      ]
    }
  }
}

The following gives a quick overview of page tagging/event tracking (coupled with handling Nosto product recommendations and banners) for headless and SPA (Single Page Application) builds. You can find more details in the personalization implementation guide, but this page will already give you a general understanding of the concept.

Search and Category Merchandising is separate from the personalization guide and covered at the end of this page.

Page Tagging and Event Tracking + Requesting Nosto Content for rendering with your Templates

On every page visit, you need to send a request to Nosto using our about the page type the user is browsing and what exactly they're looking at (e.g. type = product, ID = 123).

You can , the concept is the same every time.

Nosto then returns a response with two types of content:

• Product Recommendations -> with an array of

• Onsite Content Personalization (OCP, e.g. banners or text) ->

Nosto Content via Session API

You take the response and pass it to your rendering function, building the HTML template and injecting it into your theme.

This is done via (empty divs on every page that can be populated from the backend, e.g. pdp-top, pdp-mid, home-1, home-2, ...) and you pass all the placement-IDs that are on the current page to Nosto. Nosto then returns the data of the campaigns that are inside of those placements.

Using placements gives the eCom-team a high degree of flexibility since they can control what to show where and they can run A/B tests within Nosto.

Nosto offers you several helper functions to simplify injecting your campaigns and setting up click attribution. If you want to read more on DOM injection and click attribution .

Nosto Content via GraphQL

The event tracking can also be done via GraphQL.

The concept is the same: and .

Please beware of the following drawbacks:

1. You request the campaigns for a specific product ID or category (without placements) and will receive the Recommendation campaign IDs directly and therefore can't use Nosto built-in A/B testing. You need an alternative, full page A/B testing like Omniconvert in this case.

2. is not possible via GraphQL. We highly recommend to go with the Session API and use .

3. Nosto OCP (like personalized banners or other HTML content) can not be retrieved via GraphQL.

Choosing the right Implementation Method

The Nosto team is happy to support you finding the method that matches your tech stack, requirements and preferences. We highly recommend reading our , but if you're in a hurry, take a look at our .

Implementation Methods for Nosto Search/Category Merchandising (CM)

Here you can find an .

The differences between the GraphQL API and JS Library (wrapping the GraphQL API) are:

• Queries done with the JS Library are automatically tracked, (when a user clicks on a product that was returned by a Nosto-powered search overlay, SERP or PLP)

• Nosto A/B testing is automatically included with the JS Library and

• to get the current session params from the browser and pass it to the GraphQL request

The endpoints and requests are very similar, you either pass a search query or a category and Nosto returns all products and associated facets. Here are .

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

The full schema for product tagging is defined here

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.

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

1. Traditional approach: Using native HTML elements with nosto_element class

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

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:

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

or alternatively

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:

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 .

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:

which can be expressed like this using nested CSS:

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:

becomes the following with divId as nosto-product1:

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

Further reading

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.

The full schema for order tagging is defined

or via DOM tagging

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.

Edge cases

If either of the following cases applies to you, we recommend either an API implementation or fetching the prices via the frontend API of your platform instead of sending the price variations to Nosto. Shopify for example has the and our Shopware plugin has an that you can extend. Please or your Nosto onboarding manager for additional consultation.

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.

The full schema for cart tagging is defined

or via DOM tagging

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

When a user places an order onsite or offsite, you must send the conversion tracking information to Nosto.

Orders can be associated with a customer either by or by customer id. The customer id matches the Nosto cookie (this cookie is typically called 2c.cId).

Tracking orders by customer id looks like the following:

Working with recommendations

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:

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 scenarios adjustments need to be made. For a comprehensive overview, please read our .

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.

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.

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.

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.

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

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.

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.

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

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

Query

Using only category path

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

Query

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 or is not enough. In these cases can be used to build any query for category & landing pages.

Query

Other features & implementation

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

Analytics

Nosto Analytics

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.

or via DOM tagging

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.

or via DOM tagging

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 . Below is a small snippet of what the payload looks like.

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.

See also

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

Nosto provides plugins for the most common eCommerce platforms like Shopify, Magento 2, Shopware 6, BigCommerce and Prestashop.

• The plugins have implemented the Nosto backend APIs so in most cases 90% of the product catalog sync is already handled.

  • If your client has custom use cases, you likely will have to extend the Nosto plugin, change the data structure within your platform or make use of one of the Nosto backend APIs to ensure all the needed product data is in Nosto.

• Depending on your platform, a Nosto plugin (like for Shopware or Magento 2) extends the default theme (like Dawn, Storefront, Luma or Hyvä) and implements the frontend mechanisms that are explained in the following.

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

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?