1 of 8

Using the JavaScript Library

Search

For client-side/frontend integrations, Nosto's JavaScript library can be used to simplify the integration. It provides a programming interface to access the Search & Categories API.

For the most basic search the fields parameter should be provided to specify what product/keyword fields should be returned. Both products and keywords can be used separately and together, depending on the use case. For all parameters, see the .

The api.search function also accepts the following options:

Option

Default

Description

The function automatically loads session parameters required for personalization & segments in the background.

In order to request custom fields, add the entries "customFields.key" and "customFields.value" to the requested product fields. This changes the example above like this

Search page

For a search page in most cases the facets parameter should be provided.

Also redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.

isKeyword should be set to true if search is submitted by clicking a keyword, suggested in the autocomplete.

Autocomplete

track should be enabled to automatically track searches to Nosto analytics.

Category page

Furthermore redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.

Session parameters

For some of the search features to work properly, such as personalised results and segments, the search function needs to be able to access information about the user's session from the front-end.

The search function of the JS API already includes session state automatically.

To get all session data the following snippet can be used:

The function accepts the following options:

Analytics

Tracking search events to analytics can be divided into three parts: search, search submit, search product click. These are user behaviours that should be tracked:

search submit (type = serp)
faceting, paginating, sorting (type = serp) or (type = category)
autocomplete input (type = autocomplete)
search results product click (type = serp), (type = autocomplete) or (type = category)
autocomplete keyword click (type = autocomplete)
category merchandising results (type = category)

JS API library provides tracking helpers for all of these cases.

Error Handling

Search

User actions that lead to search results should be tracked with api.recordSearch() after search request is done:

search submit (type = serp) - user submits search query in autocomplete component and is landed to SERP
faceting, paginating, sorting (type = serp) or (type = category) - user adjusts current search results by filtering (e.g. brand), selecting search page, sorting results
autocomplete input (type = autocomplete) - user sees partial results while typing in search input
category merchandising results (type = category) - user sees specific category results when category is selected (category merchandising must be implemented)

You don't need to execute api.recordSearch()if you call api.search(query, { track: 'serp'|'autocomplete'|'category'}) function from JS API, becauseapi.search()already calls api.recordSearch() when track option is provided.

Example:

Keyword click tracking

Example:

Category results tracking

Example:

Search queries are categorised into two groups: organic and non-organic searches. In order to mark a search query as an organic search you need to call api.recordSearchSubmit(query: string). You should call it on search input submit only, before search request is sent.

Organic search - is a search query submitted through search input and which lead to SERP (search engine results page). Following faceting, paginating, sorting queries on organic query is also counted as organic.

Search product click

Product clicks should be tracked in autocomplete component, SERP, category page with api.recordSearchClick() by providing component (type), where click occurred, and clicked product data:

Example:

When tracking events, adherence to the following criteria is essential for capturing detailed and valid data:

query parameter:
- The query string is an essential component for event tracking.
- If present, include products.sort to track sorting behavior.
- If applicable, incorporate products.filter.
searchResults parameter:
- products.hits array containing objects with a productId is mandatory.
- products.total number to identify if the search has results.
- For accurate pagination tracking, products.from and product.size must be included.
- For identifying if the request was autocorrected include products.fuzzy.
- For category requests, either products.categoryId or products.categoryPathis mandatory.

Bear in mind that search queries are split between organic and non-organic searches. To classify a search as organic, it is crucial to invoke api.recordSearchSubmit() upon the search input submission, before the actual search request is dispatched. This step is pivotal in ensuring the seamless tracking of organic searches through to the SERP.

Tracking product clicks is fundamental for understanding user interaction. Use api.recordSearchClick() to monitor this actions correctly, specifying the type and relevant hit data.

Implement Autocomplete using Nosto JavaScript library

Nosto Autocomplete library is designed to simplify the implementation of Search Autocomplete functionality by providing: 🌟 Autocomplete products, keywords and history visualization. 🔄 Automatic bindings to Nosto Search API. 🧩 Autocomplete component state management. 📊 Nosto Analytics out of the box, Google Analytics support. 🏗️ Default Autocomplete components and templates. 🎮 Keyboard navigation.

Installation

You can install the Nosto Autocomplete library via npm:

npm install @nosto/autocomplete

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

Framework

Import Statement

Base

import { autocomplete } from "@nosto/autocomplete"

Mustache

import { autocomplete, fromMustacheTemplate, defaultMustacheTemplate } from "@nosto/autocomplete/mustache"

Liquid

import { autocomplete, fromLiquidTemplate, defaultLiquidTemplate } from "@nosto/autocomplete/liquid"

Preact

import { autocomplete, Autocomplete } from "@nosto/autocomplete/preact"

React

import { autocomplete, Autocomplete } from "@nosto/autocomplete/react"

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

Initialization

After installation, you can import and use the library in your JavaScript or TypeScript files. Library attaches to existing search input element. Once a search input is loaded, autocomplete function can initialize event listeners for the Search Autocomplete.

❗autocomplete should be called once.❗

Render results

Once the autocomplete component binds to input via inputSelector and dropdownSelector, it then renders autocomplete provided in a render function. It is called on input focus and change events, and renders a dropdown element with the current search result state:

if input is empty and history entries exist, it renders dropdown with history list,
if input is not empty and it passes minQueryLength rule, it render dropdown with keywords and products.

Render can be adjusted to the desired framework. Moreover, the library provides helpers for Mustache/Liquid template languages.

Examples

Suppose index.html is

List of autocomplete initialization examples:

Liquid Example below uses fromLiquidTemplate helper which renders string template. Library provides default autocomplete template via defaultLiquidTemplate and default css for default template:

The template also can be loaded from a file. The library includes a default template, equivalent to string template in above example:

Mustache Mustache template is rendered similarly as Liquid template in the above example:

Or from a file:

React/Preact One way to initialize autocomplete in a React app, is to call autocomplete from the useEffect on component mount, using default <Autocomplete /> component and styles:

The Preact solution does not differ from React a lot:

Submit search

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

Enter key press.
Submit button click.
Keyword click.

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

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

To disable submit pass undefined value. \

📊 Nosto Analytics (enabled by default)

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

📈 Google Analytics (enabled by default)

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

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

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

To disable Google Analytics, set googleAnalytics: false.

Create Autocomplete template

The library handles events through dataset properties to avoid handling logic in a template. These data-* attributes are used:

data-ns-hit - this attribute should be used on clickable keyword, product, history list elements. Stringified unmodified JSON object (product, keyword or history hit) from the search response should be provided as a value. You will need to escape it in Liquid and Mustache templates. This attribute handles submit keyword/history as search, redirect to product, analytics (if enabled) request.
data-ns-remove-history - 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.
To delete all history entries, add data-ns-remove-history="all" to clear button.

Template examples: Mustache, Liquid, React/Preact

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

Render results

if input is empty and history entries exist, it renders dropdown with history list,
if input is not empty and it passes minQueryLength rule, it render dropdown with keywords and products.

Render can be adjusted to the desired framework. Moreover, the library provides helpers for Mustache/Liquid template languages.

Examples

Suppose index.html is

List of autocomplete initialization examples:

Liquid Example below uses fromLiquidTemplate helper which renders string template. Library provides default autocomplete template via defaultLiquidTemplate and default css for default template:

The template also can be loaded from a file. The library includes a default template, equivalent to string template in above example:

import {
    autocomplete,
    search,
    fromRemoteLiquidTemplate,
} from "@nosto/autocomplete/liquid"
import "@nosto/autocomplete/styles.css"

autocomplete({
    // ...
    render: fromRemoteLiquidTemplate(
        `./node_modules/@nosto/autocomplete/dist/liquid/autocomplete.liquid`
    ),
})

Mustache Mustache template is rendered similarly as Liquid template in the above example:

import {
    autocomplete,
    search,
    fromMustacheTemplate,
    defaultMustacheTemplate,
} from "@nosto/autocomplete/mustache"
import "@nosto/autocomplete/styles.css"

autocomplete({
    // ...
    render: fromMustacheTemplate(defaultMustacheTemplate),
})

Or from a file:

import {
    autocomplete,
    search,
    fromRemoteMustacheTemplate,
} from "@nosto/autocomplete/mustache"
import "@nosto/autocomplete/styles.css"

autocomplete({
    // ...
    render: fromRemoteMustacheTemplate(
        `./node_modules/@nosto/autocomplete/dist/mustache/autocomplete.mustache`
    ),
})

React/Preact One way to initialize autocomplete in a React app, is to call autocomplete from the useEffect on component mount, using default <Autocomplete /> component and styles:

import { useEffect } from "react"
import { createRoot } from "react-dom/client"
import {
    autocomplete,
    search,
    Autocomplete,
} from "@nosto/autocomplete/react"
import "@nosto/autocomplete/styles"

let reactRoot = null

export function Search() {
    useEffect(() => {
        autocomplete({
            fetch: {
                products: {
                    fields: [
                        "name",
                        "url",
                        "imageUrl",
                        "price",
                        "listPrice",
                        "brand",
                    ],
                    size: 5,
                },
                keywords: {
                    size: 5,
                    fields: ["keyword", "_highlight.keyword"],
                    highlight: {
                        preTag: `<strong>`,
                        postTag: "</strong>",
                    },
                },
            },
            inputSelector: "#search",
            dropdownSelector: "#search-results",
            render: function (container, state) {
                if (!reactRoot) {
                    reactRoot = createRoot(container)
                }

                reactRoot.render(<Autocomplete {...state} />)
            },
            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.
                }
            },
        })
    }, [])

    return (
        <form id="search-form">
            <input type="text" id="search" placeholder="search" />
            <button type="submit" id="search-button">
                Search
            </button>
            <div id="search-results" className="ns-autocomplete"></div>
        </form>
    )
}

The Preact solution does not differ from React a lot:

import { render } from "preact/compat"
import { useEffect } from "preact/hooks"
import {
    Autocomplete,
    autocomplete,
    search,
} from "@nosto/autocomplete/preact"
import "@nosto/autocomplete/styles.css"

export function Search() {
    useEffect(() => {
        autocomplete({
            // ...
            render: function (container, state) {
                render(<Autocomplete {...state} />, container)
            },
        })
    }, [])

    return <form id="search-form">{/* ... */}</form>
}

Using the JavaScript Library

Search

For client-side/frontend integrations, Nosto's JavaScript library can be used to simplify the integration. It provides a programming interface to access the Search & Categories API.

The api.search function also accepts the following options:

Option

Default

Description

The function automatically loads session parameters required for personalization & segments in the background.

In order to request custom fields, add the entries "customFields.key" and "customFields.value" to the requested product fields. This changes the example above like this

// ...
        products: { fields: ["name", "customFields.key", "customFields.value"] },
// ...

Search page

For a search page in most cases the facets parameter should be provided.

Also redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.

isKeyword should be set to true if search is submitted by clicking a keyword, suggested in the autocomplete.

nostojs(api => {
    api.search({
        query: 'my search',
        products: {
            facets: ['*'],
            fields: ['name'],
            size: 10
        }
    }, {
        redirect: true,
        track: 'serp',
        isKeyword: true
    }).then(response => {
        console.log(response);
    });
});

Autocomplete

track should be enabled to automatically track searches to Nosto analytics.

nostojs(api => {
    api.search({
        query: 'my search',
        products: {
            fields: ['name'],
            size: 10
        },
        keywords: {
            fields: ['keyword'],
            size: 5
        }
    }, {
        track: 'autocomplete'
    }).then(response => {
        console.log(response);
    });
});

Category page

For category pages in most cases the facets parameter should be provided. Additionally (for Shopify) and should be also provided.

Furthermore redirect & track should be enabled to automatically track searches to Nosto analytics & redirect if API returns a redirect request.

nostojs(api => {
    api.search({
        products: {
            categoryId: '12345',
            categoryPath: 'Pants',
            fields: ['name'],
            size: 10
        }
    }, {
        track: 'category',
        redirect: true
    }).then(response => {
        console.log(response);
    });
});

Session parameters

For some of the search features to work properly, such as personalised results and segments, the search function needs to be able to access information about the user's session from the front-end.

The search function of the JS API already includes session state automatically.

To get all session data the following snippet can be used:

nostojs(api => {
    api.getSearchSessionParams(options).then(response => {
        console.log(response);
    });
});

The results of this function should be passed to search query parameter. In case search is called from backend, it should pass this data to backend (e.g. using ).

The function accepts the following options:

Option

Default

Description

Analytics

Tracking search events to analytics can be divided into three parts: search, search submit, search product click. These are user behaviours that should be tracked:

search submit (type = serp)
faceting, paginating, sorting (type = serp) or (type = category)
autocomplete input (type = autocomplete)
search results product click (type = serp), (type = autocomplete) or (type = category)
autocomplete keyword click (type = autocomplete)
category merchandising results (type = category)

JS API library provides tracking helpers for all of these cases.

Error Handling

On errors from api.search calls the error object contains a status field that has the HTTP response status which can be used to determine the cause of the error in addition to the error message. The ranges of the status codes used for errors are 400-499 and 500-599. For details on these error codes, go to

Search

User actions that lead to search results should be tracked with api.recordSearch() after search request is done:

search submit (type = serp) - user submits search query in autocomplete component and is landed to SERP
faceting, paginating, sorting (type = serp) or (type = category) - user adjusts current search results by filtering (e.g. brand), selecting search page, sorting results
autocomplete input (type = autocomplete) - user sees partial results while typing in search input
category merchandising results (type = category) - user sees specific category results when category is selected (category merchandising must be implemented)

nostojs(async (api) => {

    const searchRequest = {
      query: "shoes",
      products: {
        sort: [{ field: "price", order: "asc" }],
        filter: [{ "field": "brand", "value": "Nike" }]
      }
    }
    const response = await sendGraphQlRequest(searchRequest)
    const searchResult = response.data.search

    api.recordSearch(
        type,
        searchRequest,
        searchResult,
        options
      )
})

Parameter

Description

Example:

api.recordSearch(
    "serp",
    {
        query: "shoes",
        products: {
            sort: [{ field: "price", order: "asc" }],
            filter: [{ "field": "brand", "value": "Nike" }]
        }
    },
    {
        products: {
            hits: [{ productId: "123" }, { productId: "124" }],
            fuzzy: true,
            total: 2,
            size: 2,
            from: 0
        }
    },
    {
        isKeyword: false
    }
)

Keyword click tracking

Example:

api.recordSearch(
    'autocomplete', 
    searchRequest,
    searchResult,
    { 
        isKeyword: true
    } 
)

Category results tracking

Example:

api.recordSearch(
    'category',
    {
        products: {
            categoryId: "123456",
            categoryPath: "Pants",
            sort: [{ field: "price", order: "asc" }]
            size: 24,
            from: 0,
        }
    },
    {
        products: {
            categoryId: "123456",
            categoryPath: "Pants",
            hits: [{ productId: "123" }, { productId: "124" }],
            fuzzy: true,
            total: 18,
            size: 24,
            from: 0
        }
    },
    {
        isKeyword: false
    }
)

The tracking metadata is primarily taken from the third parameter. The and objects must be provided in the api.recordSearch call instead of partials.

nostojs(api => {
    const query = 'shoes'
    api.recordSearchSubmit(query)
})

Search product click

Product clicks should be tracked in autocomplete component, SERP, category page with api.recordSearchClick() by providing component (type), where click occurred, and clicked product data:

nostojs(api => {
    api.recordSearchClick(type, hit)
})

Parameter

Example:

api.recordSearchClick(
    "autocomplete", 
    { productId: "123", url: "https://myshop.com/product123" }
)

Event Tracking Requirements

When tracking events, adherence to the following criteria is essential for capturing detailed and valid data:

query parameter:
- The query string is an essential component for event tracking.
- If present, include products.sort to track sorting behavior.
- If applicable, incorporate products.filter.
searchResults parameter:
- products.hits array containing objects with a productId is mandatory.
- products.total number to identify if the search has results.
- For accurate pagination tracking, products.from and product.size must be included.
- For identifying if the request was autocorrected include products.fuzzy.
- For category requests, either products.categoryId or products.categoryPathis mandatory.

Tip: In case of API integration, use this example GraphQL partial query to integrate with the API and retrieve the necessary response data for precise event tracking.

query {
  search(
    accountId: "YOUR_ACCOUNT_ID"
    query: "green"
    products: { size: 10, from: 10 }
  ) {
    products {
      hits {
        productId
      }
      total
      size
      from
      fuzzy
      categoryId
      categoryPath
    }
  }
}

Accurate Click Tracking

Tracking product clicks is fundamental for understanding user interaction. Use api.recordSearchClick() to monitor this actions correctly, specifying the type and relevant hit data.

Using the JavaScript Library

Search

Search page

Autocomplete

Category page

Session parameters

Analytics

Error Handling

Search

Keyword click tracking

Category results tracking

Search form submit

Search product click

Implement Autocomplete using Nosto JavaScript library

Installation

Initialization

Render results

Submit search

📊 Nosto Analytics (enabled by default)

📈 Google Analytics (enabled by default)

Create Autocomplete template

Further reading

Installation

Implement Autocomplete using Nosto JavaScript library

Initialization

Submit search

📊 Nosto Analytics (enabled by default)

📈 Google Analytics (enabled by default)

Render results

Using the JavaScript Library

Search

Search page

Autocomplete

Category page

Session parameters

Analytics

Error Handling

Search

Keyword click tracking

Category results tracking

Search form submit

Search product click

Event Tracking Requirements

Search Form Submit

Accurate Click Tracking

Further reading

Create Autocomplete template

Event Tracking Requirements

Search Form Submit

Accurate Click Tracking