Full Text Search

Usage

Search Results Page Search Use the following code for a given shopper search query.. The callback function will contain the relevant products and filters matching the shopper term:

Example

window.FastSimonSDK.fullTextSearch({
    term: "yes please",
    onFacetsLoaded: (response) => {
        // handling facets using response.facets
    },
    onProductsLoaded: (response) => {
        // handling products using response.products
    }
})

/* example with narrow & sort */
window.FastSimonSDK.fullTextSearch({
    term: "yes please",
    narrowBy: [["Colour","colour:white"],["Colour","colour:green"],["Size","S"],["Price_from_to","36-95"]],
    sortBy: window.FastSimonSortBy.AtoZ,
    onFacetsLoaded: (response) => {
        // handling facets using response.facets
    },
    onProductsLoaded: (response) => {
        // handling products using response.products
    }
})

/* example with range facet slider */
window.FastSimonSDK.fullTextSearch({
    term: "diamonds",
    narrowBy: [["Diamond details.size_from_to","0.3-10"]],
    onFacetsLoaded: (response) => {
        // handling facets using response.facets
    },
    onProductsLoaded: (response) => {
        // handling products using response.products
    }
})

Options

Option	Type	Description
term	string (required)	the term you want results for
callback	(Response) => void (required)	callback to handle the results
page	number (default=1)	use for pagination
productsPerPage	number	use for custom product count
sortBy	sortBy	the sort order for the results. Pass this only when the shopper explicitly selects a sort — if omitted, Fast Simon applies the default sort configured in the Dashboard
narrowBy	Narrow []	use for filtering
facets	boolean (default=true)	use facets:false if you do not need filters
withAttributes	boolean (default=false)	use withAttributes:true if you want to include attributes in the product response
withBadges	boolean (default=false)	when true, appends a badges array to each product with the matched site badges. Automatically enables withAttributes.

caution

• Make sure that the productsPerPage is the same across all pages
• withAttributes:true might slow serving so only use if you need product tags or attributes

Response

Note: the callback might run twice to optimize speed, there are two scenarios:

1. Products and facets were fetched together - callback runs once with be called only once with action "product and facets".
2. Products were fetched but facets are still fetching - callback will run twice:
   • action "products" will come first and call the callback for the first time
   • action "product and facets" will call the callback again once facet fetch is completed

Turbolinks

fullTextSearch may also return a turbolink (a query-based redirect). It can be delivered two ways:

• with action: "turbolink" — when the term matches a turbolink already cached on the client (fired before the network request, on the unified callback), or
• with a populated turbolink on a normal "products" / "facets and products" response — when the turbolink is resolved by the server.

Where to read it depends on which callback style you use:

• Unified callback → response.payload.turbolink?.u
• Split onProductsLoaded / onFacetsLoaded (recommended) → response.turbolink?.u (the result is passed unwrapped, without a payload envelope)

Redirect whenever the turbolink URL is present. See Turbo Links for full handling.

TypeScript Typing

interface Response {
    action: "products" | "facets and products" | "turbolink"
    payload: {
        query: string
        products?: Array<Product | PromoTile>
        facets?: Facet[]
        totalResults: number
        narrow?: Narrow[]
        sortBy?: SortBy
        isNoResults?: boolean
        page?: number
        pageCount?: number
        ancestors?: CategoryAncestor[]
        avoidPrefixList?: string[]
        turbolink?: Turbolink // { l: string, t: string, u: string } — present for turbolink redirects
    }
}

Product Special Sizing

When a product has been configured for special grid placement in the Fast Simon Merchandising Editor, it will include an sp_s field in the response. Use this field to render the product card at a larger size in your grid layout.

.product-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr); /* adjust columns to match your layout */
    gap: 16px;
}

.product-card[data-sp-s="large"] {
    grid-column: span 2;
    grid-row: span 2;
}

.product-card[data-sp-s="horizontal"] {
    grid-column: span 2;
    grid-row: span 1;
}

onProductsLoaded: (response) => {
    const grid = document.querySelector('.product-grid');
    response.products.forEach(product => {
        const card = document.createElement('div');
        card.classList.add('product-card');
        if (product.sp_s) {
            card.dataset.spS = product.sp_s; // sets data-sp-s="large" or "horizontal"
        }
        card.innerHTML = `<img src="${product.t}" alt="${product.l}" />
                          <p>${product.l}</p>
                          <p>${product.p}</p>`;
        grid.appendChild(card);
    });
}

See the sp_s field in the Product type reference for the full type definition.

Reporting Implementation (must for analytics)

Please follow the guideline to report shopper behaviour on the recommendation widget in order to get accurate Analytics in the Fast Simon dashboard as well as greater personalized accuracy

1. Search Events - report whenever you call fullTextSearch...
2. Products Viewport Impression From Search - report products in the viewport
3. Products Viewed From Search - report whenever product is clicked
4. Quick View - if implement report "used" whenever quick view button is clicked