Sitecore Search Starter Kit

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

Sitecore Search Starter Kit

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.

Table of contents

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

Prerequisites

Node.js

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.

Environment variables

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.

CEC configuration

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

Sources

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

Suggestion Blocks

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

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

Pre configured widgets

The account must have the following widgets created before:

Name	ID	Type	Description	Used in
[Search Results Page] Search Results	rfkid_7	Search Results	Search results widget. Will include a grid with the results together with the avility to filter results by different facets.	/search, /detail/*
Preview Search	rfkid_6	Preview Search	It is an input that does a quick search over the content. It is included on the page header.	Every page
SEO	search_seo	SEO	A SEO widget.	Every page
Home Hero	home_hero	HTML Block	An html block that appears at the home hero. It has rules to show content dependending on the language selected.	/
FAQs Title	faqs_title	HTML Block	An html block with the title of the "Frequently asked questions" section.	/
Highlight Title	highlight_title	HTML Block	An html block with the title of the "Highlighted Articles" section.	/
Search Home Highlights Articles	search_home_highlights_articles	Search Results	Search Results widget used on the "Highlighted Articles section".	/
N/A	rfkid_qa	Questions	This widget appears on the home page, used on the "Frequently Asked Questions" or in the search page. Please ask for support if this does not appears as it is still an experimental feature (This type of widget can't be created on CEC as well).	/ , /search

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

Quick start

To start using Sitecore Search Starter Kit:

1. Install Node.js. We recommend the LTS version.
2. Clone the repository: git clone git@github.com: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:5174
7. To build the app for production, run: npm run build

Pages

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.

Home

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.

Search

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.

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

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.

Monitoring example

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:

Adding a new widget

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.

Documentation

Sitecore Search SDK 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 Search developer guide.

Contributions

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

Bug reports

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

Feature requests

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

Code of Conduct

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.

Contributing Guide

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

1. Fork the Sitecore Search 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 Search 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.