klevultd / frontend-sdk

Monorepository for Klevu headless

Headless product discovery, for every body

With Klevu’s brand new SDK, you can pull the power of AI product discovery into anything.

A traditional website, a single page application (SPA), progressive web app (PWA), a mobile app, a campaign website, an in-store kiosk, a spaceship… whatever.

Simpler for developers, faster to innovate.

Klevu headless monorepository

Here are the links to different projects.

• @klevu/core package that can be used to build modern frontends with Klevu search.
• React example React, React Router, Material UI example.
• Vue example Vue 3, Vue-Router, TailwindCSS example.
• Nuxt example Nuxt 3 example.
• Remix example Remix is a React-based example of using Klevu with Server Side Rendering.
• Vanilla JavaScript example - Minimal JavaScript example.
• Shopify Hydrogen example - Small Hydrogen example

Integrate Klevu into your application with ease. We do all the heavy lifting.

Klevu SDK brings smart search, category merchandising and recommendations solution to your ecommerce store. Klevu makes it easy to create the best product browsing experience for your customers.

Klevu already has a simple to implement JavaScript library that is perfect for most users, so who is this library good for?

TypeScript SDK

The Klevu SDK is written in TypeScript which gives you:

• Full auto-completion support of integrated development environments (IDEs)
• Full documenation from the code comments!
• Easy and fast way to integrate Klevu to your custom UI

SPA (Single Page Applications)

This library supports all the major frontend libraries like React and Vue. This SDK however gives you the ability to plugin Klevu smart search, category merchandizing and recommendations any way that you would like. Including event tracking of product clicks, searches, and purchases that drive the AI at Klevu's core.

PWA (Progressive Web Applications)

PWAs are designed to give users an experience on par with native apps. With the Klevu SDK, you can also bring the power of Klevu AI into your PWA.

SSR & SSG (Server Side Rendering & Static Site Generation)

SSR & SSG are quickly becoming standard features in all of the most popular frontend frameworks such as NextJS and NuxtJS. With the Klevu SDK you can both increase your store's SEO and your user's experience by requesting search results, category pages, and recommendations before the page loads.

Full Creative Control, on Full Power

The Klevu SDK gives developers maximum control over the way they want to display and allow users to interact with your product catalog. When you add the SDK library to your project you have all the building blocks necessary to create trully unique user experiences that perfectly fit your brand.

Klevu SDK Feature List

We've packed a lot of features into the React Example included with this SDK. Here are many of the features and where to find a working example. You can also take a look a the React Example README for more information on what is implemented in the example and click here to:

View a Live Demo

Search

Feature	Description	Example
Quick Search	Example used to display search results as you type into a text field.	quicksearch.tsx
Search Results Landing Page	Example to show search results based on a keyword passed in the URL.	SearchResultPage.tsx
Category Navigation	Example display of products in a Category/Collection.	CategoryPage.tsx
Single Product Search	Example of using search to query the data for a single product.	ProductPage.tsx
Filters	Examples of filters to narrow down products based on product facets.	SearchResultPage.tsx CategoryPage.tsx
Load More Results	Example of a Load More button to request more products.	SearchResultPage.tsx

Analytics

Analytics drive the Machine Learning Klevu uses to provide users the best results.

Feature	Description	Example
SearchEvent	Track what was searched.	quicksearch.tsx
Search Product Click Event	Track the products that are clicked from search results.	SearchResultPage.tsx
Category Navigation Product Click Event	Track the products that are clicked from category pages.	CategoryPage.tsx
Buy/Purchase Event	Track the products that are purchased.	CheckoutPage.tsx

Recommendations

Feature	Description	Example
Klevu Merchant Center Recommendations	Add recommendations created within KMC. 1	HomePage.tsx CategoryPage.tsx ProductPage.tsx
Similar Products		ProductPage.tsx

Personalization

Feature	Description	Example
Personalisation	Easily add personlization to your klevuFetch searches by adding a modifier.	HomePage.tsx

Utilities

Feature	Description	Example
KlevuKMCSettings	Load your Klevu Merchant Center settings into the browser's localstorage.	index.tsx

Internal development

Node.js and npm is required to be installed on your system before starting. This should be done once before starting development.

Core

To run build and test @klevu/core you need to first go to packages/klevu-core.

Before starting you need to have all packages installed with npm install

Creating release version

npm run build creates production version of the @klevu/core. It does a clean build every time it runned.

To actually release there is CI/CD script utils/release-klevu-core.js. Use Node.JS to run it.

Developing core

npm run build:watch

build:watch runs build in watch mode rebuilding application every time there is changes. It doesn't do clean build, but incremental builds and it doesn't do all tricks required for the release. It is good if you wish make changes to library while developing other package like @klevu/ui that require changes to core.

npm run qoc

This checks that quality of code is good enough. Will be automatically run by GitHub.

npm run test

Runs big suite of tests for core. Doesn't require building. It can be possible just to develop and run test once in a while to see everything works perfectly. Will be automatically run by GitHub.

UI

To start building @klevu/ui you first need to go to packages/klevu-ui folder and do the npm install. To make build work correctly you need to run npm install also in packages/klevu-ui-react and packages/klevu-ui-vue.

React and Vue packages do not need any other changes. Their contens are automatically generated by klevu-ui project.

Creating release version

npm run build creates a distributed version of @klevu/ui. But to create proper version and release all three UI libraries there is a CI/CD node script in utils/update-klevu-ui.js.

Developing

Easiest way to develop and test components is by running Storybook. For that you need to watch build the ui project and run the storybook.

npm run build:watch

And in separate window

npm run storybook

This should open the development environment.

To create generate components you can use the command:

npm run generate

VSCode extensions

It is recommened to have ESLint and Prettier extensions installed in order to produce clean code.

Footnotes

1. Klevu's Merchant Center allows you to create recommendations for specific uses that take into account the context of the pages they are added into. ↩

frontend-sdk's Issues

Create hyva.io demo

Updated all documentation to call out not adding search analytics to quick search requests

sendSearchEvent() modifier should not be used when issuing a search request for quick search.

Clean example UI so that it is presentable

Events (analytics)

Implement class for easier event reporting.

Filter Manager toggle options doesn't work when clicking same option again

Steps to reproduce:

1. Go to https://headlessdemo.klevu.com
2. Click filter option
3. Click filter option again -> doesn't uncheck and state is wrong.

Unreal Engine Demo

bring the Klevu SDK into an Unreal game

Create PWA Magento studio demo

Create tools to work with filters

Create a tool that can take filters and handle their current selection. This model should be passable to search queries in order to make handling easier.

Create shogun demo

Add allowed search options to all functions

Some of the query functions do not have all search params definable. For example it is impossible to set fields to trendingCategoryProducts()

create Hydrogen example

Implement A/B testing feature

• Create ability to run AB test with library
• Bonus: Think of a way that it could be done in server side

Create Next demo

Crete a demo based on react app that is for next.

Create Nuxt demo

Create nuxt demo that mimics vue demo.

Adding more complexity to example

• Routing
• Product page
• Category listing

Rename KlevuEvents.searchProductClick to KlevuEvents.productClick

As it's most generic event that we can use to track all click events. Not just the ones that are coming from search.

Load more is present even though there are no more results.

On the QA site, the load more button is still present when no results.

Jira issue: KS-12466

Web component: Product component

A simple product component taking in KlevuRecord from @klevu/core and rendering a HTML output from that.

Component should be as extensible as possible so that developers can easily change the way it renders.

Issue with requesting next results

Hi, there's a problem with next function's offset property, instead of adding the offset value as a number it gets appended as a string

view screenshots below:

How to create documentation to the project

Create deity.io demo

Familiarize current state of the library

Create Gatsby demo

Request fails when personalisation enabled and no previous data

If personalisation() modifier is used and there is no previous user click data available then request will fail.

Update documentation about clickSendEvents to be more comprehensive

https://headless.developers.klevu.com/sdk/result-object#jk-click-events

Write TSDOC for all public facing variables, functions and classes

trendingCategoryProducts function id parameter doesn't work

Default id persists even though custom id is defined.

For example:

await KlevuFetch(
  trendingCategoryProducts("cat", { id: "test" })
)

Results will be with id trendingCategoryProducts

Data formatter for incoming data

We need to clean and format incoming data. For example slider filter min/max values are coming in as string even though they are numbers in reality.

There are multiple cases this happens. There are also boolean values coming from API "true" or "false" strings.

Search

Simple SDK to do search to Klevu API

Required features

• Search
• Pagination
• Getting filters
• Applying filters to search

Pagination should have easy to use API that takes caches and applies filters automatically for better performance.

Can we add the boiler plate code for adding and removing KlevuDomEvents.FilterSelectionUpdate to core?

Instead of having add:

document.addEventListener(
    KlevuDomEvents.FilterSelectionUpdate,
    handleFilterUpdate
)

onBeforeRouteLeave((to, from, next) => {
    document.removeEventListener(
        KlevuDomEvents.FilterSelectionUpdate,
        handleFilterUpdate
    )
})

Could we do something like:

const removeFilterSelectionUpdate = KlevuDomEvents.addFilterSelectionUpdate(usersFilterUpdateHandler)

usersFilterUpdateHandler & removeFilterSelectionUpdate can be called anything, and this would allow the implementation to require less boiler plate.

Basic core structure

Create frontastic demo

Web component: Recommendation app

Recommendation web component pulls data from given KMC recommendation ID and it creates horizontal swiper component from products fetched by @klevu/core

It is preferred that no external UI libraries is used to create this component.

Required UI web component

• #85

Implement visual search query function

Move next() page function from upper level of results to individual query results

Currently calling next() page will automatically try to detect which of the queries should be paginated. That is not optimal way of it working.

We need to move next() to same level as sendEvent functions in the result so that developer explicitly selects which of the queries they wish get next page from.

Old function should be @deprecated in documentation and then removed in next version.

Next() function in category merchandising returns 5 results instead of original request amount

As described in title.

Only save last search when user clicks a product

Web component: Product grid component

A grid component that places given product components in a grid.

Required components

• #85

Recommendations

Implement simple to use functions to get recommendations from the Klevu API

Implement modifier to boost queries with another

Klevu Api supports to boost queries with another queries.

Use Beacon api instead of window.fetch to send V2 events

Currently Axios is used to send analytical events to server. Axios support should be kept for Node.js functionality, but for browser side Beacon API should be used to prevent missing events.

https://calendar.perfplanet.com/2020/beaconing-in-practice/

V1 cannot use Beacon API as it requires POST message to be sent.

Make axios dependency optional

Make change to KlevuFetch in a way that it allows to use window.fetch instead of axios library.

Create proper Readme

Recommendation templates and banners.

Currently recommendations are created in Klevu Merchant Center and the data coming in is plain HTML and Javascript that should be injected using Klevu JSv2 library.

In milestone 1.0.0 we support only fetching recommendations through the API and KMC based builder is not available.
In milestone 2.0.0 we give a way to inject JSv2 into website and init these banners. Banners are loaded through the library.

After these in the next version we should build up provide JSON output from KMC that it's easier to build UI builder with any library.

Filters are not reset while switching the categories (still happening)

When you enable a filter (say color: blue) and change to a different category, the blue filter is still selected.

There was a fix submitted, but after QA the same issue is still there.

In addition:

• there seems to be a problem with the color swatch for "oliv". sometimes it's white, sometimes it burgundy, etc. My guess is that its having a hard time because it does not actually match a real color without the full spelling.
• there seems to be a problem with the price slider filtering.

There are videos that show these issues in Jira.

Jira: KS-12397

Getting to contact with commerce tools

Category Navigation

Simple API to fetch data for category navigation.

Should implement helper function that fetches filters has ability to paginate category navigation fetches.

Create cache of requests and return them when query is exactly the same

If the whole KlevuFetch function is the same as before we should return result from local memory cache.

Issue with Filters

Hi, we are using the @klevu-core v1.1.0 for the project, developed using React, as a dependency and we have a problem with filter options.

1. issue with price range filters, we could not find the detailed info and examples for it. using the updateSlider, filters were sent in payload but in the result the values ( end and start ) were returning null and records were empty.
2. the issue with filter toggle. filters get applied correctly and product records get updated, but the value ( selected ) isn't updated correctly, there are some issues with FilterManager. the same issue is noticeable on the demo page.

I wanted to ask for some suggestions or information about these issues if they are currently in development

Query feature for popular searches

see KMC