Integrate Guides into your website

After you’ve created a set of guides, you need to integrate them into your website. This requires:

1. Installation
2. Client setup
3. Widgets to display the guides.

Before you begin

To integrate your guides, you need frontend development proficiency with HTML, CSS, JavaScript, and React. You should also have created your guides.

On this page, React is used to illustrate the integration process. However, the generative experiences client offers widgets for React and JavaScript. For more information, see Alternative implementations.

Installation

Install the @algolia/generative-experiences-react package using npm or yarn:

$
$
$
npm install @algolia/generative-experiences-react
# or
yarn add @algolia/generative-experiences-react

Set up the commerce client

The commerce client interacts with the Algolia Commerce API and is crucial for fetching the necessary data for the widgets:

1
2
3
4
5
6
7
8
import { createClient } from '@algolia/generative-experiences-api-client';

const client = createClient({
  appId: 'YourApplicationID',
  indexName: 'your_index_name',
  searchOnlyAPIKey: 'YourSearchOnlyAPIKey',
  region: 'us',
});

Parameters

• appId. Your Algolia application ID.
• indexName. The Algolia index used for generating and displaying guides.
• searchOnlyAPIKey. The Algolia search API key needed for reading index data. ACLs needed: search.
• region. The region of your Algolia application, either eu or us. Default: us.

Display guide

Guides contain content and headlines.

Display guide content

To show the content of a guide, use the GuideContent widget. For more information, see GuideContent.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import { createClient } from '@algolia/generative-experiences-api-client';
import { GuideContent } from '@algolia/generative-experiences-react';

const client = createClient({
  appId: 'YourApplicationID',
  indexName: 'your_index_name',
  searchOnlyAPIKey: 'YourSearchOnlyAPIKey',
});

const HitComponent = ({ hit }: { hit: any }) => {
  return (
    <div>
      <p>{hit.name}</p>
      <img src={hit.image} alt="" />
    </div>
  );
}

function App({ currentObjectID, userToken }) {
  //...
  return (
    <GuideContent
      client={client}
      showFeedback
      userToken={userToken}
      objectID={currentObjectID}
      itemComponent={({ hit }) => <HitComponent hit={hit} />}
    />
  )
}

Display guide headlines

To reference your website’s guides, use the GuidesHeadlines widget. This widget can be embedded in your home page, product detail page, or search pages, and customized to display headlines based on categories or specific records.

For more information, see GuidesHeadlines.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import { createClient } from '@algolia/generative-experiences-api-client';
import { GuidesHeadlines } from '@algolia/generative-experiences-react';

const client = createClient({
  appId: 'YourApplicationID',
  indexName: 'your_index_name',
  searchOnlyAPIKey: 'YourSearchOnlyAPIKey',
});

function App({ userToken, category }) {
  //...
  return (
    <GuidesHeadlines
      showFeedback
      userToken={userToken}
      client={client}
      category={category}
      showImmediate
    />
  )
}

Gather feedback

To gather feedback on the Guides you can use the GuidesFeedback widget. You can use this widget directly in a Guide Content page, or when you are displaying the Guide Headlines, by passing showFeedback parameters in the GuideContent or GuidesHeadlines widgets. Or you can add it and customize it separately, using the GuidesFeedback.

For more information, see GuidesFeedback.

This feature uses the Insights API to gather events related to Guides feedback. You will need to set up a User Token.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { createClient } from '@algolia/generative-experiences-api-client';
import { GuidesFeedback } from '@algolia/generative-experiences-react';

const client = createClient({
  appId: 'YourApplicationID',
  indexName: 'your_index_name',
  searchOnlyAPIKey: 'YourSearchOnlyAPIKey',
});

function Page({ objectID, userToken }) {
  //...
  return (
    //...
    <GuidesFeedback
      client={client}
      objectIDs={[objectID]}
      userToken={userToken}
    />
  )
}

Displaying website-specific content

Some of the generated guides may contain placeholders for website-specific content. These are used for the links to the product pages, guide pages as well as images.

To replace these placeholders with your website-specific content, use the getters parameter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
import { createClient } from '@algolia/generative-experiences-api-client';
import {
  GuideContent,
} from '@algolia/generative-experiences-react';

const gseClient = createClient({
  appId: 'YourApplicationID',
  indexName: 'your_index_name',
  searchOnlyAPIKey: 'YourSearchOnlyAPIKey',
});

const customGetters = {
  /**
   * URL for a specific guide.
   */
  guideURL: (objectID) => `/shopping-guide/${objectID}`,
  /**
   * URL for a specific product.
   */
  objectURL: (objectID) => `/product/${objectID}`,
  /**
   * List of images for a product.
   */
  images: (object) =>
    object.images.map((image) => ({ src: image.url, alt: image.alt })),
};

const HitComponent = ({ hit }: { hit: any }) => {
  return (
    <div>
      <p>{hit.name}</p>
      <img src={hit.image} alt="" />
    </div>
  );
}

function App({ currentObjectID, userToken }) {
  //...

  return (
    <GuideContent
      client={gseClient}
      showFeedback
      userToken={userToken}
      objectID={currentObjectID}
      itemComponent={({ hit }) => <HitComponent hit={hit} />}
      getters={customGetters}
    />
  )
}

Parameters

• guideURL. Returns the URL for a specific guide. This is used to link to the guide page from the guide headlines widget. The expected output is a string that represents the URL of the guide page.

• objectURL. Returns the URL for a specific product. This is used to link to the product page from the guide content widget. The expected output is a string that represents the URL of the product page.

• images. Returns a list of images for a product. This is used to display images in the guide headlines and guide content widgets. The expected output is an array of objects, each containing the src and alt properties.

Customize styles

The widgets are not styled by default. However, you can style them with the classNames property or by applying your CSS to the existing classes.

Using classNames property

Use the classNames property to add classes to the widgets.

1
2
3
4
5
6
7
<ShoppingGuideHeadlines
  classNames={{
    wrapper: 'YOUR_WRAPPER_CLASS',
    container: 'YOUR_CONTAINER_CLASS',
    item: 'YOUR_ITEM_CLASS',
  }}
/>

You can also use the class names that are already set to style the widget.

Using Tailwind CSS

To integrate the widgets with Tailwind, include the @tailwindcss/typography plugin in your tailwind.config.js and add the following CSS to your project.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
.ais-NoWrap {
  @apply whitespace-nowrap;
}

.ais-ScreenReaderOnly {
  @apply sr-only;
}

/* display headlines */
.ais-GuideHeadlinesContent-wrapper {
  @apply rounded p-4 border border-gray-100 shadow gap-2;
}

.ais-GuideHeadlinesContent-container {
  @apply flex flex-col items-end;
}

.ais-GuideHeadlinesContent-itemsContainer {
  @apply flex items-center gap-6;
}

.ais-GuideHeadlinesContent-readMore {
  @apply flex text-white py-2 mt-8 border-2 bg-blue-700 rounded-md items-center w-full justify-center;
}

.ais-GuideHeadlinesContent-item {
  @apply bg-neutral-100 rounded p-4 space-y-3 flex justify-between min-h-[420px];
}

.ais-GuideHeadlinesContent-itemContent {
  @apply mt-5;
}

.ais-GuideHeadlinesContent-itemTitle {
  @apply text-blue-800 font-semibold line-clamp-2 h-12;
}

.ais-GuideHeadlinesContent-itemDescription {
  @apply line-clamp-4 text-base mt-2;
}

.ais-GuideHeadlinesContent-itemImage {
  @apply relative min-h-[120px] max-h-[120px] w-auto overflow-hidden mx-auto mt-4 aspect-square;
}

/* display content */
.ais-GuideContent-contentSection {
  @apply prose max-w-prose mx-auto px-4;
}

.ais-GuideContent {
  @apply mb-10 w-full;
}

.ais-GuideContent-heroImage {
  @apply mx-auto min-h-[200px] max-h-[250px] my-12;
}

.ais-GuideContent .ais-Feedback {
  @apply flex items-end justify-end mx-auto;
}

.ais-GuideContent-factorsList {
  @apply flex flex-wrap list-disc gap-x-2 justify-between w-full;
}

.ais-GuideContent-factorItem {
  @apply w-[45%];
}

.ais-GuideContent-relatedItemsSection {
  @apply prose max-w-none mx-auto px-4;
}

.ais-GuideContent-relatedItemsTitle {
  @apply max-w-prose mx-auto px-4;
}

.ais-GuideContent-relatedItemsListContainer {
  @apply max-w-prose mx-auto px-4;
}

.ais-GuideContent-relatedItemsList {
  @apply p-2 flex justify-between flex-wrap list-none;
}

/* display feedback */
.ais-Feedback {
  @apply text-gray-500 text-base max-w-prose mt-10;
}

.ais-feedbackContainer {
  @apply flex items-center gap-4;
}

.ais-Feedback-thanksWrapper {
  @apply flex items-center;
}

.ais-Feedback-labelWrapper {
  @apply flex space-x-2 items-center;
}

.ais-Feedback-labelIcon {
  @apply h-6 w-6 flex-shrink-0;
}

.ais-Feedback-button {
  @apply inline-block rounded font-semibold text-center shadow-sm transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 bg-white hover:bg-white border-2 border-gray-400 hover:border-gray-500 focus-visible:outline-gray-500 text-gray-400 hover:text-gray-500 px-2.5 py-1.5;
}

.ais-Feedback-buttonsWrapper {
  @apply flex space-x-3 items-center;
}

.ais-Feedback-buttonIcon {
  @apply h-4 w-4 stroke-2 flex-shrink-0;
}

/* error loading guide */
.ais-GuideContentError {
  @apply flex flex-col items-center text-center gap-y-4 max-w-prose mx-auto my-6;
}

.ais-GuideContentErrorTitle {
  @apply text-lg font-semibold;
}

Next step

Once you’ve created the mechanism for displaying your guides, make them display live by publishing them.