sitecore-discover-starter-kit v1.0.0

Sitecore Discover Starter Kit

This repository has an example implementation of an e-commerce platform using the Sitecore Discover JS SDK which integrates with Discover services and supports event tracking.

Table of contents

• Prerequisites
• Quick start
• Pages
  • Home
  • Search
  • Category pages
  • Product detail page
  • Cart page
  • Order confirm page
• Events
  • Monitoring example
• Documentation

Prerequisites

Node.js

The Discover 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 Discover 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.local file in the root of the project and add the following environment variables.

The following variables should exist within the .env.local file:

REACT_APP_ENV="<environment - Expected values: prod, staging or prodEu >"
REACT_APP_CUSTOMER_KEY="<customer key>"
REACT_APP_API_KEY="<API key provided in CEC>"

Quick start

To start using Discover Starter Kit: 1. Install Node.js. We recommend the LTS version. 2. Clone the repository: git clone https://github.com/Sitecore/Discover-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.local file then add the following environment variables to it:

REACT_APP_ENV="<environment - Expected values: prod, staging or prodEu >"
REACT_APP_CUSTOMER_KEY="<customer key>"
REACT_APP_API_KEY="<API key provided in CEC>"

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

Widget configurations

The application renders widgets based on page or URL, as configured in the CEC. It loads a custom page widgets component that uses the PageWidgets component or the usePageWidgets hook. The index.jsx imports a configuration file called sitecoreWidgetsConfig.js that registers all the components used for each widget type.

You can access the documentation for details on components, functions, query hooks, templates, and ui primitives.

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.

In the starter kit, we use a higher order function called withPageTracking in each page to register page uri and track the page view event.

Home

Route: / shows the main page of the site. This page is an example of how you can render widgets configured for the page in the CEC. The page component uses the usePageWidgets query hook and other recommendation widgets.

Events tracked are:

• A page view event.
• 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.

Events tracked are:

• A page view event.
• A widget appear event for the search result widget present on the page.

Category pages

Route: /category/<category sanitized name>. E.g.: /category/fan-gear-jerseys Only shows search results for the category.

Events tracked are:

• A page view event.
• A widget appear event for the search result widget present on the page (this page also uses a search results type widget to show the products).

Product detail page

Route: /product/detail/<product sku>/<product id>. E.g.: /product/detail/3107756/prod1100011 shows the details of a product. It also has a recommendation widget for related products.

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

Events tracked are:

• A page view event.
• A PDP view event with the SKU from the product shown (dispatched verbosely).
• A widget appear event for the search result.

Cart page

Route: /cart shows a list of the products added to the cart. The page also has a recommendation widget showing products that were recently purchased together.

Events tracked are:

• A page view event.
• A widget appear event for the recommendation widget.
• add to cart or cart status events.

Order confirm page

Route: /order/confirmation shows the confirmation for the purchase and includes a recommendation widget showing products that were recently purchased.

Events tracked are:

• A page view event.
• A widget appear event for the Recommendation widget present on the page.
• An order confirm event (the user sent on the event is a mock user).

Events

Events are an important part of the Discover 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:

Documentation

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.

Contributions

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.

Bug reports

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

Feature requests

You can use GitHub to submit feature requests for Discover 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 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 start (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.