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.

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 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 can not mix Session API and JS API.

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

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

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

Action

Action in the Session API context means fetching recommendations for a specific view. For example when a visitor navigates from the front page to a product view you would most likely fetch recommendations related to a product. This would be considered as an Action. Setting the cart contents however would not be considered as action.

It's also good to keep in mind that each Action is considered as a page view in Nosto's analytics. It's recommended to perform an action only once per route change to keep the analytics consistent and comparable to traditional "static" e-commerce stores.

Route change

Route change in the context of this documentation means, as it stands, when the navigational route (url) of the application is changed. In traditional web sites this would be a (full) page load.

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.

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

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

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

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 personalised triggered emails and for building multi-channel experiences.

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.

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

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

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.

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.

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

See to see more detailed documentation of the library.

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 or similar high-level frameworks.

Nosto Web Components

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

• NostoDynamicCard Renders product cards entirely on the Shopify side. Requires alternate product card templates to be available within Shopify themes.

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

• NostoProductCard Provides a platform-agnostic custom element that delegates rendering to a shop side templates (Handlebars and Liquid are currently supported).

Nosto's web component offering is documented

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.

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.

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:

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.

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

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

<script>
  _targetWindow.jQuery(
</script>

becomes

<script type="module">
  jQuery(
</script>

Additionally, module scripts support:

Import syntax

<script type="module">
  import { createApp } from 'https://unpkg.com/petite-vue?module'
  createApp().mount()
</script>

Top-level await

<script type="module">
  const response = await fetch('http://www.acme.com/myapi/myresource')
  // Do something with the response
</script>

Lightweight sandboxing

<script type="module">
  // Config is not written to the window namespace but scoped to the script tag
  const config = {
    key: "738209438"
  }
</script>

Further reading

JavaScript modules

You can define placements for Nosto to use via a code block called div-elements. 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>

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

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.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  upsertIdentity(identity: {
    email: "[email protected]",
    attributes: [
      {name: "loyalty-tier", value: "Gold"},
      {name: "shoe-size", value: "42"},
    ]
  }) {
    email,
    attributes {
      name,
      value
    }
  }
}
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.

Deleting Identities

There is currently no way to delete an identity.

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.

List Products

Querying products gives access to Nosto's product catalogues 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

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

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.

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

A single-page application (SPA) is a web application or web site that interacts with the user by dynamically rewriting the current page rather than loading entire new pages from a server. This approach avoids interruption of the user experience between successive pages, making the application behave more like a desktop application. In a SPA, either all necessary code – HTML, JavaScript, and CSS – is retrieved with a single page load,[1] or the appropriate resources are dynamically loaded and added to the page as necessary, usually in response to user actions. The page does not reload at any point in the process, nor does control transfer to another page, although the location hash or the HTML5 History API can be used to provide the perception and navigability of separate logical pages in the application.[2] Interaction with the single page application often involves dynamic communication with the web server behind the scenes.

If you have a website, that is built atop JavaScript frameworks, such as AngularJS, Ember.js, ExtJS, Knockout.js, Meteor.js, React or Vue.js, your site has likely adopted SPA principles.

Important: You cannot mix JS API and Session API. You need to use either or. If you are not sure which one to use, please contact Nosto's support.

Note: The examples in the documentation are written in ES5 and leverage advanced browser features such as Promises.

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.

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

• NostoProduct and NostoSkuOptions 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

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

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

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.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  upsertCategories(categories: [{
    id: "123",
    name: "Shoes",
    parentId: "456",
    urlPath: "/categories/mens/shoes",
    fullName: "/Mens/Shoes",
    available: true
  }]) {
    categoryResult {
      errors {
        field
        message
      }
      category {
        id
        name
        parentId
        urlPath
        fullName
        available
      }
    }
  }
}
EOF

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

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

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

Granting consent

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

Revoking consent

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

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

mutation {
  updateStatus(number: "ORD102-33", params: {
    orderStatus: "fraud"
    paymentProvider: "klarna"
    statusDate: "2011-12-03T10:17:30"
  }) {
    number
    statuses {
      date
      orderStatus
      paymentProvider
    }
  }
}

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.

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.

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

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

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.

<span class="nosto_tag" style="display:none" translate="no">color: Red</span>
<span class="nosto_tag" style="display:none" translate="no">gender: Mens</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.

<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

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.

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, query rules and other settings. Synonyms for search queries can also be configured here.

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 here

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.

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

While Nosto's crawler attempts to keep its copy of your catalog as fresh as possible, there are scenarios where we may not be able to update all the information as quickly as needed.

In these scenarios, we recommend that you implement our Discontinue API which allows you to push all your product identifiers to discontinue them and have the changed instantly reflect across our entire engine.

Here's an example of a Curl request.

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the

How many items can I update at a time?

The Discontinue API takes an array of product metadata and has no hard limit on the number of items that you can specify and is only limited by the maximum size of the payload of 2 MB.

How often can I discontinue products?

You can discontinue products as often as you need.

When should I make an API call?

You should make an API call when any product is discontinued and removed from your catalog. If a product has simply gone out of stock, we recommend making an API to update the product with the correct availability.

Is there any additional benefit of using the Discontinue API?

While Nosto crawls your site and automatically discontinues products that are no longer available, it may lag behind when your site has a large catalog. In these environments, it is recommended to use the Discontinue API to immediately discontinue the product.

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.

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 a valid TLD as using localhost is not supported.

We recommend using a valid 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.

Setting up the catalog sync

While Nosto crawls sites to replicate the product catalog, it is unable to do so on SPAs. In order to synchronise your product catalog with Nosto, you'll need to to keep the Nosto catalog in sync.

Note: This step must be completed prior to proceeding with the implementation. Without this step, it will be troublesome to preview and debug the recommendations.

Including the script

To start tracking visits and content the Nosto script needs to be active on all pages within the store. Replace the account-id in the snippet below with your own account-id and place the code within the <head> section of your DOM. You can find your account-id from the admin.

The JS comprises of three parts - the first is the "stub" (which allows API usage prior to the script being loaded), the second is the "autoload" configuration (which prevents Nosto from automatically initiating once loaded.) and finally the Nosto script is loaded.

Note: The script and the snippet should be added as high up in the <head> portion of the page so the connection is initialised 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

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:

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

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.

While Nosto's crawler attempts to keep its copy of your catalog as fresh as possible, there are scenarios where we may not be able to update all the information as quickly as needed.

In these scenarios, we recommend that you implement our lightweight Recrawl API which allows you programmatically instruct our crawler to reindex a given URL.

For example, if you add a discount of -10% to all the products in your "Shirts" category, you can use the Recrawl API to recrawl all the given URLs and update the prices.

Here's an example of a Curl request.

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the

How many items can I recrawl at a time?

The Recrawl API takes an array of product ids and URLs and has no hard limit on the number of items that you can specify.

How often can I invoke a recrawl?

You can recrawl as often as you need but bear in mind that every recrawl adds an extra page load to your server.

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

When using multi-currency, this endpoint is used to update the exchange rates for your account. When new rates are sent via this endpoint, the changes will reflect instantly on your store as the product prices are multiplied with the provided rates in real-time.

Note: This endpoint should only be used when using multi-currency. Please refer to our multi-currency guide prior to using this endpoint. Incorrect usage of these endpoints will result in a total outage of your personalization setup.

Token

This endpoint requires a Rates token.

Usage

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the

How often should I send exchange-rates?

You can send exchange rates as often as you like but at the bare minimum, the exchange rates should be sent when they are changed.

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:

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.

$!product.imageUrl

The Nosto CDN thumbnails are accessible via

$!product.thumb(size)

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:

$!product.image.getThumb(300, 300)

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

$!product.alternateImages[0].getThumb(300, 300)

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:

$!product.image.getThumb(300, null)

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

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

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

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:

submit: async (query, config, options) => {
    if (
        query.length >= config.minQueryLength
    ) {
        const response = await search(
            {
                query,
            },
            {
                redirect: true,
                track: config.nostoAnalytics ? "serp" : undefined,
                ...options
            }
        )
        // Do something with response. For example, update Search Engine Results Page products state.
    }
},

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 Nosto Tech Docs 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:

googleAnalytics: {
    serpPath: "search-results",
    queryParamName: "query",
    enabled: true
}

To disable Google Analytics, set googleAnalytics: false.

If you want to attach stateful logic as event handlers to your template elements, petite-vue 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

<script type="module">
import { createApp } from "https://unpkg.com/petite-vue?module"

createApp({ 
  addToCart(productId) {
    // call platform specific add to cart API  
  }    
 }).mount("#$divId")
</script>

Usage from template

<span @click="addToCart('$product.productId')">Add to cart</span>

Product selection for bundle creation and related total

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

<script type="module">
import { createApp } from "https://unpkg.com/petite-vue?module"

const prices = {
#foreach($product in $!products)
  "$product.productId": $product.price.asNumber(),
#end
}

createApp({  
  selected: [],
  toggle(id) {
    const idx = this.selected.indexOf(id)
    if (idx > -1) {
      this.selected.splice(idx, 1)
    } else {
      this.selected.push(id)
    }
  },
  get total() {
    return this.selected
      .map(id => prices[id] ?? 0)
      .reduce((acc, curr) => acc + curr, 0)
  }
}).mount("#$divId")
</script>

template usage

<div class="product-grid">
#foreach($product in $!products)
  <div class="product" @click="toggle("$product.productId")">
    ...
  </div>
#end
</div>

<div>Total: {{ total }}

You can disable Nosto for a given customer if they don't give consent for data processing or if legal reasons such as COPPA requires to disable Nosto for an individual.

This method disables the initialization of Nosto entirely, meaning that all associated Nosto features on your web store for that user are also disabled.

You will need to wrap the Nosto script in a conditional that activates only if the customer has accepted to activate Nosto. Below is an example that simply checks for the existence of a cookie called accepts_marketing but you should change the conditional to match your consent management implementation.

<script type="text/javascript">
if (document.cookie.indexOf('accepts_marketing') >= 0) {
  var head = document.getElementsByTagName('head')[0];
  var js = document.createElement("script");
  js.type = "text/javascript";
  js.src = "//connect.nosto.com/include/$accountID";
  head.appendChild(js);
}
</script>

Opting out of session tracking

Normally Nosto uses a cookie to identify browsers between their visits to the site. The purpose and usage of this cookie is very similar to how web analytics tools, such as Google Analytics, work.

You can use opting out of session tracking in case you want to enable Nosto's features in a limited manner where Nosto doesn't track browser sessions. When users opt out of session tracking, Nosto treats each request like it would be a new session that is then immediately discarded. In this mode, Nosto can still serve generic trend based recommendations, but any feature that relies on users actions over multiple requests will never activate.

Nosto supports opting out of session tracking via the "Do Not Track" feature. If you leverage Nosto's "Do Not Track", Nosto will avoid setting a session identifier.

You can opt-out of tracking by using the setDoNotTrack method. You must do so before making any requests to Nosto.

nostojs(api => api.visit.setDoNotTrack(true));

Having done so, you can also verify that you have opted out by using the isDoNotTrack() method

nostojs(api => console.log(api.visit.isDoNotTrack()));

Impact on features

This section lists the impact of enabled doNoTrack mode on various Nosto features.

Recommendations and Onsite Content Personalization

Normally served but taking only the current request information into account (Customer history or profile won't be available)

Segments

Taking only the current request information into account (Customer history or profile won't be available)

Popups

Fully disabled

Search and Category Merchandising (Universal)

Analytics tracking disabled

Category Merchandising (Platform)

Segmentation and A/B testing logic is disabled for CM (Platform) Only the main sorting will be applied to categories

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

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

<div class="nosto_page_type" style="display:none" translate="no">order</div>
<div class="nosto_purchase_order" style="display:none" translate="no">
    <span class="order_number">1445</span>

    <div class="buyer">
        <span class="email">[email protected]</span>
        <span class="first_name">John</span>
        <span class="last_name">Doe</span>
        <span class="marketing_permission">false</span>
    </div>

    <span class="payment_provider">checkmo</span>
    <span class="order_status_code">pending</span>

    <div class="purchased_items">
        <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>
</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.

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

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

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.

Nosto Search uses product and user behavior data from the Nosto Platform, so if you are implementing Nosto Search, first of all, you need to implement Nosto Platform to your website.

Your search engine will be ready after the Nosto representative enables the Search module for your account. Then you will need to integrate Nosto Search to the website.

Implementation methods

Search Templates

By using a pre-built template that can be customized to fully match a website's design using built-in code editor directly in https://my.nosto.com/. In the code editor, you can fully customize the pre-built template's JavaScript, HTML, and CSS code. Changes to the template can be implemented either by client’s developers or Nosto team. Frontend integration uses Preact and JSX templates and renders search results page dynamically in website’s frontend, so no additional integration is needed to the backend. When using Nosto services, no development is needed from the client.

API

API integration - a robust Search GraphQL API allows to implement Nosto Search into any website or app and gives complete flexibility for developers to build frontend and backend features.

JavaScript Library

For frontend integrations you can also use our JavaScript library. This library wraps the Search GraphQL API and provides its functionality in a programmatic way.

Compare implementations

If you are looking for a fast launch without much effort we recommend going with the fully customizable pre-built templates. This type of integration does not support full API access but comes complete with an out-of-the-box search result page and autocomplete templates that can easily be customized to match most website designs and integrate even advanced custom functionality.

If however you need full control over the search frontend or require complex custom functionality we recommend to go with the API or JavaScript integrations. These integrations do not provide out-of-the-box templates but provide direct access to the Search API, allowing you use the data in whatever way is required for your use cases.

Autocomplete provides keyword suggestions to assist users in completing their queries, supplemented by a selection of the most relevant products with the ability to see all products on the search results page.

Check out .

API Requests

Example

Query

Response

Highlight

API can return highlights indicating which parts of a keyword match the search query. This HTML can be used to render and emphasize the matching sections during display.

Redirects

Redirects are configured in the search dashboard and can be used to forward users to specific pages depending on what they type into the search field. For example, users searching for "shipping" could be directed to .

Analytics

Nosto Analytics

To analyze user behavior you need to implement tracking. This can be achieved using our . You need to implement the following methods with type = autocomplete:

• to track users typing in the search field and viewing suggestions

• to track clicks on autocomplete suggestions

Additionally, see the .

Google Analytics

Each autocomplete product click should be tracked as a search page virtual view to ensure that the Google Analytics search feature displays the correct conversion rate. For example, if you click any product when the typed query is phone it should track a virtual page view with the URL /search?q=phone (adjust the search path and query parameter to match your search page).

Since a product link click would redirect to a new page, to ensure that Google Analytics has time to send the tracking request, it's recommended to save the search query to local storage and track it on page load.

Basic tagging

Nosto also supports multiple optional values which may enrich the usage of the service, but are not required. These span elements should be inserted into the "nosto_product" parent container.

Tagging attribute extension

Tagging the prices

Prices must always be denoted in a simple numerical form using dot as the decimal separator. For example, 1.234,45 is invalid while 1234.45 is valid.

Tagging the categories

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

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 availability

The availability of a product is represented by InStock or http://schema.org/InStock for products that are in stock and saleable. For products that are out of stock or you don't want to be recommended, you can use OutOfStock or http://schema.org/OutOfStock

Tagging the Google Categories

The category of your item based on the Google product taxonomy. Use the schema provided by Google here ()

Tagging the Rating

The rating of a product must be represented as a number between 0.0 and 5.0. For example, a product cannot be rated 9.1. You must normalize your rating value to fit our specified range.

Tagging the Tags and/or Custom fields

The three tag fields, tags1, tags2 and tags3 are simply labels that can be used to annotate tags like discounted, limited collection or other use cases where you might want to filter your Nosto recommendations by certain product groupings.

Custom fields accept a key:value pair where the class of the attribute is the key. Common use cases are material, color or other similar unique identifiers.

Tagging the currently viewed sku

It is possible to tag also the currently viewed product sku. Typically, this would be done on a product detail page when the user chooses a specific color or size and you would like to update recommendations to highlight other products with similar attributes. Most common approach would be to implement it by calling the or the from a click-listener to send the sku information and update the recommendations. If, however, the preference is to use tagging to specify the selected sku instead, that can be done through tagging by adding a span under product with the class name selected_sku_id, for example: <span class="selected_sku_id">40822930473153</span>

Fields that are not exposable in tagging

Nosto also supports two attributes that are not crawlable through tagging. This is due to the sensitive nature of the attributes. Those are: supplier_cost and inventory_level. To send these two values to Nosto you will need to use the .

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

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

Supplier Cost / Margin Filter

If you want to use Nosto’s margin filter, you need to send supplier cost via since it's a sensitive data that you might not want to expose in the product tagging.

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 the Catalog Explorer: https://my.nosto.com/admin/$accountID/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.

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.

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

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.

, , ,

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

On the Order-Confirmation Page

To fetch the recommendations for the order-confirmation page, simply use the GraphQL field called forOrderPage to fetch all the recommendations for the order-confirmation page.

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.

An additional span tag must be placed within the product page tagging with a class name variation_id. The tag is a child element of the nosto_product element.

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?

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 emails such as abandoned cart or order followup.

Specifying the active variation

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 segment of the customer.

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.

Enabling multi-variants 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 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.

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.

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.

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.

Onsite features such content and recommendations are injected into what we call "placements".

Nosto requires that you specify an array of placements and will respond with the response for those specified placements. There are two types of placements and it is possible to leverage either of them when implementing Nosto on an SPA:

Static Placements

These are defined as empty hidden elements in the DOM with the class nosto_element. The identifier of the element denotes the placement identifier. An example placement is as follows:

The Div element remains hidden until Nosto injects content into it.

Dynamic Placements

These are defined in the administration panel and are CSS and URL rules to define where content is to be injected. In order to allow these dynamic placements to be usable, you should follow the guide below for managing placements automatically.

Managing Placements Automatically

When using the Session API, the placements are set through a function call setPlacements which expects an array of strings. In order to support dynamic placements setup in the Nosto backend, we recommend that instead of setting the placements array contents directly from your application, you use the following API to get a list of placements for the page:

The function scans the current page (document object) for any valid placements at the time of execution and returns them in an array suitable for the setPlacements-function. As long as it is called after the targeted elements have been rendered into the document, it will return both the static and the dynamic CSS and URL rules based placements on the page. Dynamic placements are picked up regardless of them being rendered or not. Static placements are always obtained through scanning the page. Freshly created Nosto accounts come with static placements only. ( In case you have programmatic placement codes that are not in the page document at all, you can add them to the array to combine both manual and automatic approaches. )

Here's an example call where placements are scanned automatically:

To continue with the example, let's assume the api.placements.getPlacements() returned an array with 2 placements: ['frontpage-center-1', 'frontpage-banner'] and then let's assume that we would have set up in the backend a recommendation campaign for frontpage-center-1 and a content campaign for frontpage-banner.

Here is an example of a sample response.

The response object will contain a campaigns field which has both content and recommendations under their own fields and within those the keys are the placement identifiers and the value will be an object containing the payload and parameters used for click attribution.

Rendering campaign results

By default the API returns campaigns data in JSON format. Product recommendation campaigns contain an array of recommended products and content campaigns contain an html field. To ensure correct attribution HTML campaign results should always be injected via Nosto API functions. Nosto provides a function to inject the HTML based campaign results into the right place: api.placements.injectCampaigns(). The function expects an object where the field keys are the placements to be injected and values are either a string or an object with a string field named html. The function will scan the document to find the active placements and insert the HTML to the right location. Any javascript blocks within the HTML content will be executed as well.

Here is an example of rendering campaign results.

This example assumes the implementing application has a utility function to transform products JSON into HTML to be inserted, alternatively there could also be a function that gets the product JSON and renders them itself directly.

Offloading campaign rendering and injection fully to Nosto

For HTML based campaign results we recommend to offload the campaign injection fully to Nosto. For HTML based results you can skip transforming the products JSON to HTML and instead use the recommendation templates in the Nosto backend to produce HTML. In that case you would set the response mode in the Session API to be 'HTML' and enable campaign injection via enableCampaignInjection().

Here's an example call

Testing

How to use debug toolbar to preview search

With the , 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

• Pagination is working

Test both mobile & desktop view using Chrome .

Deployment

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

How to deploy?

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

2. Click on Deploy latest and launch live

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.

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.

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 .

Share search templates code between multiple accounts

The functionality enables the sharing of a single instance of search templates across multiple dashboard accounts through linking. This feature proves particularly advantageous in scenarios where there are multiple websites with identical or similar characteristics that necessitate the creation of multiple dashboard accounts (such as supporting multiple languages or environments).

How to implement some differences between websites?

Even if multiple websites share the same search templates code, we can easily have different logic based on website host or language (or other criteria).

function detectWebsite() {
    if (location.hostname === 'de.website.com') {
        return 'de'
    } else if (document.documentElement.lang === 'de') {
        return 'de'
    }
    return 'en'
}

const helloText = {
    de: 'Hallo',
    en: 'Hello'
}[detectWebsite()]

Different CSS between websites

Since it's not possible to target CSS rules by domain, it's recommended to add a special class to the page body and use it to target CSS rules.

Example JS

init({
    ...
}).then(() => {
    if (location.hostname === 'de.website.com') {
        document.body.classList.add('nosto-search-de')
    }
})

Example CSS:

.nosto-search-de .my-title {
    color: black;
}

Show specific SKU when searching by SKU color or ID

By default, the search indexes all SKUs as a single product. Therefore, even when searching by a specific SKU attribute (like SKU color or ID), the search will return the main product along with all SKUs.

However, because the search returns all SKUs, SKU selection logic can be implemented on the frontend side. This is achieved by checking each SKU to see if it contains text from the search query.

Implementation

These is an example on how to implement SKU selection:

function getSku(query, product) {
    const words = query.toLowerCase().split(/\s+/)

    return product?.skus?.find((sku) => {
        // If the query is a SKU ID, return the SKU
        if (sku.id == query) {
            return true
        }
        const color = sku?.customFields?.color?.toLowerCase()?.split(/\s+/)

        return words.some((word) => color.includes(word))
    })
}

export default ({ product }) => {
    const query = useAppStateSelector((state) => state.query.query)
    const sku = getSku(query, product)

    return <a href={sku?.url || product.url}>
        <img src={sku?.imageUrl || product.imageUrl}/>

        {sku?.name || product.name}
    </a>
}

Use more than 100 facet values

By default, the search API returns 100 values for each facet, and it's not possible to control that limit in the dashboard. However, it is possible to override the facet configuration directly from the code.

Get facet ID from the dashboard

The first step is to know the facet ID of the facet you want to overwrite. The facet ID is stored in the dashboard URL. For example, if you open the facet in the facet manager, the URL should be https://my.nosto.com/admin/shopify-123/search/settings/facetManager/6406df867f8beb629fc0dfb9. This means the facet ID is 6406df867f8beb629fc0dfb9.

Override facet settings

Once the ID is known, it's possible to override any facet setting by specifying overwrite properties in the customFacets parameter:

init({
    serpQuery: {
        products: {
            customFacets: [
                {
                    "id": "6406df867f8beb629fc0dfb9",
                    "size": 10
                }
            ]
        },
    }
})

SEO

Although search engines can understand some JavaScript-rendered code, they often miss search templates. The reason for this is that the rendering of search templates is delayed in order not to hinder the page loading speed.

However, it's still possible to achieve great SEO results while using the code editor:

• Category pages - Ensure that the category page already returns the correct meta tags and page title according to SEO recommendations, they bring the biggest impact to the SEO. In category page search templates render only products, so it doesn't significantly impact SEO. Most search engines support structured data (the category page backend should generate these tags using original products). However it does not have any big impact to the SEO. Furthermore, search engines may not favor the discrepancy between structured data and the actual rendered products (cause search engine will see either empty page with loader or nosto search results that are different compared to original).

• Search pages - Most search engines don't index search pages, so no optimizations are needed.

If you still have concerns regarding SEO, please consider using API integration.

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

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

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:

Analytics

Nosto Analytics

To analyze user behavior you need to implement tracking. This can be achieved using our JavaScript library. You need to implement the following methods with type = category:

• recordSearch to track category page visits

• recordSearchClick to track clicks on category results

Nosto supports individual product SKUs under parent products. If you have not set up you should start there and extend the tagging if needed.

The SKU attributes should be listed on the last row of the nosto_product block that you have already implemented on the product pages.

What is a SKU?

Many e-commerce stores have a parent product with individual child products. The parent product is usually something along the lines of "Ski Jacket" whereas the SKUs would then be "Ski Jacket, Blue, Small", "Ski Jacket, Red, Medium". If your store uses SKUs you should add the following attributes to extend your product tagging.

Note: The attribute custom_fields can contain whatever unique information for individual SKUs that you can >consider helpful. Frequently used attributes would be size, color, material.

Extending the cart tagging with SKU metadata

When tagging the cart contents as outlined here, you can also tag information of the actual SKU that was added to cart. Notice the extra <span class="sku_id"> attribute.

Extending the order tagging with SKU metadata

When tagging the order contents as outlined here, you can also tag information of the actual SKU that was added to cart. Notice the extra <span class="sku_id"> attribute inside each of the purchased_items.

Validating

Once included you can review if the SKUs are picked up by using the . If you can see individual SKUs being picked up below the original product details then this is correctly set up.

You can further verify that products are being indexed to the catalogue under the Nosto admin by navigating to Tools → Products ()

FAQ

Do I need to view events for when an SKU is viewed?

No, Nosto does no recommend individual SKUs. While this is something on our roadmap, at the moment, you do not need to send any events when an SKU is selected.

For example, assume you had a product page selling a shoe. In this case, the product tagging would always point to the id of the shoe. No events should be dispatched when the customer selects a particular size such as S, M, L.

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.

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

Setting the cart

The cart content must updated whenever the cart contents change. The cart contents are the 1:1 representation of the user's cart. Also note that the cart contents is only send to Nosto when you perform an action. If you want to send the cart contents to Nosto right away, you add .viewCart().update() to your call.

You may also pass null or undefined to signify that there was no change in the cart. The default state of the cart in the session is empty.

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.defaultSession()
   .setCart({
     items: [
      {
        name: "Men's Running Shirt",
        price_currency_code: "EUR",
        product_id: "181503",
        quantity: 2,
        sku_id: "181505",
        unit_price: 123.45
      },
      {
        name: "Men's Training Shoe",
        price_currency_code: "EUR",
        product_id: "34552",
        quantity: 1,
        sku_id: "39912",
        unit_price: 999.00
      }
    ]
   })
});

or when sending the contents to Nosto right away

nostojs(api => {
  api.defaultSession()
   .setCart({
     items: [
      {
        name: "Men's Running Shirt",
        price_currency_code: "EUR",
        product_id: "181503",
        quantity: 2,
        sku_id: "181505",
        unit_price: 123.45
      },
      {
        name: "Men's Training Shoe",
        price_currency_code: "EUR",
        product_id: "34552",
        quantity: 1,
        sku_id: "39912",
        unit_price: 999.00
      }
    ]
   })
   .viewCart()
   .update()
});

Note: Passing null or undefined will prevent the cart contents from being mutated on Nosto. Passing an empty object {} will reset the cart contents.

Setting the customer

When a visitor logs in customer information should be passed. If the customer isn't logged in, this can be omitted. Similar to setting the cart contents, customer data is only sent to Nosto when an action is performed.

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

nostojs(api => {
  api.defaultSession()
    .setCustomer({
      customer_reference: "b369f1235cf4f08153c560.82515936",
      email: "[email protected]",
      first_name: "Nosto",
      last_name: "Test",
      newsletter: true
    })
});

or when sending the contents to Nosto right away

nostojs(api => {
  api.defaultSession()
   .setCustomer({
      customer_reference: "b369f1235cf4f08153c560.82515936",
      email: "[email protected]",
      first_name: "Nosto",
      last_name: "Test",
      newsletter: true
    })
   .viewCart()
   .update()
});

Note:

1. Passing null or undefined will prevent the customer information from being mutated on Nosto. Passing an empty object {} will reset the customer information.

2. Here viewCart is only provided as an example. But the actual tracking method to be invoked will depend on customer's current page. For more information on this, please refer Tracking Events

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.

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 Tagging - Essentials

  • Adding the Nosto Script

  • Adding the Product Tagging

  • Adding the Category/Brand Tagging

  • Adding the Cart Tagging

  • Adding the Order Tagging

  • Adding the Customer information

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

• Manual Tagging - Advanced

  • Extending tagging with SKUs

  • Adding support for multi-currency

  • Adding support for customer group pricing

Session view in the debug toolbar

1. Navigate to your site in incognito mode.

2. Load the debug toolbar by appending nostodebug=true to your store's URL e.g. https://example.com?nostodebug=true

3. Click the login link and navigate to the session view.

View Category

Navigate to a category page and verify that the View Category event is tracked with the following details:

• Target matches the viewed category.

If the category doesn't appear in the session, these pages might help

• Tagging: category

• Session API: category

View Product

Navigate to a product page and verify that the View Product event is tracked with the following details:

• Target matches the viewed product ID.

If the product doesn't appear in the session, these pages might help:

• Tagging: product

• JS API: product

• Session API: product

View a Recommended Product

Click on a product recommendation and verify that the View Product event is tracked with the following details:

• Target matches the viewed product ID.

• Ref matches the previously viewed recommendation slot ID.

If the product id and recommendation slot id don't appear in the session, these pages might help:

• JS API: Attribution for recommended Products

• JS API: Sending Add to Cart-Events

• Session API: handling attribution

Cart

Add the product to cart and verify that the cart’s contents are correct. Ensure that the product details in the cart match the product that was previously viewed.

• Product ID

• Price & Currency

• Quantity

If the cart doesn't correctly show in the session view, these pages might help:

• Tagging: cart

• JS API: cart

• Session API: cart

Order

Purchase the product and verify that the Buy Product event is tracked with the following details:

• Ref matches the recommendation slot id

• Target matches the product id

Wait 30 minutes for the session to expire and then verify that the order shows up in the orders page of the Nosto admin UI.

If the order doesn't correctly show in the session view, these pages might help:

• Tagging: order

• Session API: order

Measuring Performance

We’ve integrated with the User Timing API to be able to show some performance measurements of our client script. The supported measurements are:

• nosto.get_dynamic_placements Parse the DOM and find placements on the page. Performed before a recommendations request is sent.

• nosto.load_recommendations Send the recommendations request and handle the recommendation result. This encompasses measuring the recommendations request and nosto.inject_campaigns.

• nosto.inject_campaigns Inject both dynamic and static campaigns into the DOM. This encompasses both nosto.inject_static_campaigns and nosto.inject_dynamic_campaigns.

• nosto.inject_static_campaigns Inject static campaigns into the DOM.

• nosto.inject_dynamic_campaigns Inject dynamic campaigns into the DOM.

• nosto.evaluate_js Extract and evaluate embedded JavaScript from recommendation templates.

Lighthouse

Chrome's lighthouse tool can be opened by doing the following:

1. Right click and select Inspect.

2. Navigate to the Lighthouse tab.

3. Ensure the Performance category is enabled.

4. Click Generate Report

Once the report is generated, you can expand the “User Timing marks and measures” section under the Diagnostics section to see some basic information like how long after the page started to load the measurements start and how long each measurement took.

You can scroll back up and click the View Original Trace button to view a timeline of the measurements. You may need to expand the Timings section to view the client script’s recorded measurements. You can zoom in an out of this graph and swipe side to side to get a better view of things.

Working with recommendations

The load method returns a promise, which can be consumed to get the raw recommendation data. The raw recommendation data is an object containing the recommendation data.

Reporting correct page views - load() vs update()

Recommendation results are returned in a promise by calling either load() or update(). The difference between these two methods is:

• load() causes the load count of the most recently tracked page view to be incremented.

• update() does not automatically increment the page load count.

In order to achieve an accurate reach statistic for recommendations, load() should be called once per page view when fetching recommendations and all proceeding recommendation requests should use update().

Reporting correct product views - requesting product recommendations outside product detail page

Normally requesting product related recommendations happens in relation to viewing a product detail page, so a typical product related recommendation request looks like this:

The above will also add a product view event for the user. In some cases there are needs to request product related recommendations even when the user is not looking at a product. In these cases, to avoid reporting the user event, include a { trackEvents: false } flag to the load function, for example:

If for implementation specific reasons there are multiple calls for product related recommendations on the product page, only the first request should track the event and subsequent requests should have the { trackEvents: false } flag include.

Handling attribution

When a recommended product is viewed, the result_id from the recommendation result should be used. Below is an example recommendation result (some fields have been omitted).

The snippet of code below attributes product1 to the result id nosto-frontpage-1-fallback from the recommendation result above and fetches recommendations for nosto-productpage-1.

Letting Nosto render the HTML

If you wish Nosto to render the recommendations and returns HTML for the recommendations you can set the response mode to HTML by adding .setResponseMode('HTML') into your call. A full example for 404 page would look like this

Please note that Nosto will not inject the returned HTML into the DOM even if the response mode is set to HTML. The logic for injecting the recommendations must be implemented in the application side.

Including Add to Cart-buttons into Recommendations

Usually adding an Add to cart button directly into the recommendation which lists multiple products is fairly straightforward, the website just needs to have an appropriate javascript function to do the operation. Nosto provides ready-made functions for multiple platforms so check the Nosto documentation specific to your e-commerce platform or if needed look into your e-commerce platform's documentation and support on how to create such a function.

Once the Add to cart button is pressed it should call that function to add the products to the cart, but it should also additionally let Nosto know that the button was pressed so Nosto can track the sales from the recommendation. This can be done with the reportAddToCart function as follows:

⚠️ The api call is only for informing Nosto about the attribution (that the product was added from the recommendation), setCart function in the Session API should be used to tell Nosto the user’s cart contents.

Working with content

The load method returns a promise which can be consumed to get the raw placement data. The raw recommendation data is an object containing the placement data.

Working with popups

Popups are handled automatically and you do not need to control the rendering of the popups. As events are dispatched, popups will show and hide automatically. If you would like to have programmatic control over the popups, see .

Working with affinities

Customer affinities are taken into account by the recommendation engine and matched with the affinities defined on the products. The affinities are determined automatically, but the API allows for a more granular manual control when required.

In case addAffinity is called multiple times, the provided values will all be merged together.

Note: If the same key is provided more than once, the latest encountered value is used, and the earlier keys are overridden.

It's possible to provide multiple affinities in a single call to addAffinity.

If the current state of the request needs to be cleared, a second parameter can be provided to the addAffinity call. In the example below, sku.size key will be removed from the request.

Note: This only affects the current local state of the request. It will not remove user's affinities already saved on the backend.