A website built using React + Sitecore Search SDK for React
Demo »

This repository has an example implementation of a content website using the Sitecore Search JS SDK which integrates with Sitecore Search services and supports event tracking.

• Prerequisites
• Quick start
• Pages
  • Home
  • Search
  • Content detail page
• Events
  • Monitoring example
• Documentation

The Search Starter Kit needs to have Node.js installed to build the project. We recommend using the LTS version of Node.js. You can find the latest version of Node.js here.

The Sitecore Search Starter Kit needs some environment variables to work. You can get the values for them in the Developers resources section of Customer Engagement Console (CEC). For full functionality, create a .env file in the root of the project and add the following environment variables.

The following variables should exist within the .env file:

VITE_SEARCH_ENV=<environment - Expected values: prod, staging, prodEu or apse2 >
VITE_SEARCH_CUSTOMER_KEY=<customer key>
VITE_SEARCH_API_KEY=<API key provided in CEC>
VITE_SEARCH_PATH=<Path for the site>. This variable is optional, use it only if the site domain also includes an extra path.

The account that will be used must have an initial configuration that needs to be made on CEC:

Information sources must be entered and processed in CEC, to populate the content catalog.

Suggestions blocks must have a field named title_context_aware (this needs to be configured for the preview search widget). The following picture shows a sample configuration:

Sorting options must include featured_desc and featured_asc criteria pre-configured. The picture shows how it should look on CEC:

Remember to reindex the relevant sources after configuring a new sorting option.

The account must have the following widgets created before:

Please, check our demo website to check and visualize the different widgets.

To start using Sitecore Search Starter Kit:

1. Install Node.js. We recommend the LTS version.
2. Clone the repository: git clone [email protected]:Sitecore/Sitecore-Search-JS-SDK-Starter-Kit.git.
3. In the repository, to install all dependencies, run npm install.
4. In the root of the project, create a .env file then add the following environment variables to it:

VITE_SEARCH_ENV=<environment - Expected values: prod, staging or prodEu >
VITE_SEARCH_CUSTOMER_KEY=<customer key>
VITE_SEARCH_API_KEY=<API key provided in CEC>
VITE_SEARCH_PATH=<Path for the site> (optional)

5. To start the development server, run npm run dev.
6. To view the site, open your browser to http://localhost:5173
7. To build the app for production, run: npm run build

The JS SDK uses React Router to perform page navigation. Each page is a React component with a useEffect hook used to register uri change.

For example, for home page we have:

useEffect(() => {
    PageController.getContext().setPageUri('/');
}.[]);

With this, the SDK can change browser context and customize tracking/service response.

Route: / shows the main page of the site. The home page has the following configuration:

• 1st section: it is a content block with a locale rule to change the content if you switch the language.
• 2nd section: a content block with the title (Frequently asked questions) with the same rule than 1st section. It also has a questions widget below that only shows some questions based on a specific keyphrase.
• 3rd section: a content block with the title (same mechanism than 2nd section) and a search widget with a filter applied (type = blogs).

Events tracked are:

• A widget appear event per widget that appears on the page.

Route: /search shows the results returned after submitting the form in the header. It contains:

• a questions widget in case that the application recognizes that the filtering term is a question (e.g.: What is XM Cloud ). Otherwise, if it is not recognizing the search term as a question won't show anything
• A search results widget that will show on any case.

Events tracked are:

• A widget appear event for the questions and answer widget if it is present.
• A widget appear event for the search result widget present on the page.

Route: /detail/<content id>. E.g.: /detail/content-121212 shows the details of a specific content.

Note: In this example, the content information has been filtered from the SearchResults widget data for demonstration purposes. We do not recommend this approach in production. Restrict Search services to search and recommendations and create separate services for other data.

Events tracked are:

• A widget appear event for the search result.

Events are an important part of the Search platform. The JS SDK automatically fires events it can infer when they happen. To register other events, you have to verbosely dispatch them.

Refer to the JS SDK documentation for more about dispatching events.

An example of monitoring could be debug event tracking in the CEC. The following video shows how you can verify the events that the SDK trigger:

The starter kit comes with the @sitecore-search/cli as a dev dependency. We also added a package.json script as a short cut to create a widget based on the templates available.

For widget creation, open a terminal in the root of the project and execute the following command: npm run create-widget Then follow the instructions from the wizard.

More documentation for the cli can be found here.

Discover documentation is written for both developers and business users.

JS SDK for React documentation includes:

• Components, functions, and query hooks.
• Templates and ui primitives.

For data feeds and URL configuration, refer to the Discover developer guide.

We are very grateful to the community for contributing bug fixes and improvements. We welcome all efforts to evolve and improve the Discover Starter Kit. The following sections explain how you can participate in these efforts.

You can use GitHub to submit bug reports for Discover Starter Kit.

You can use GitHub to submit feature requests for Discover Starter Kit.

Sitecore has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

If you want to make changes to the code, follow these steps:

1. Fork the Discover Starter Kit Repo GitHub repo.
2. Clone the forked repo to your local machine.
3. Create a feature branch from main for your changes. e.g. git checkout -b my-feature-branch
4. Run npm install
5. Run npm run dev (to preview your changes locally)
6. Commit, push to your remote fork of the Discover Starter Kit repo, then open a pull request (PR) to the main branch of the Developer Portal repo.

Your changes will be reviewed and merged if appropriate.