Integrate Guides into your website
On this page
After you’ve created a set of guides, you need to integrate them into your website. This requires:
- Installation
- Client setup
- 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, eithereu
orus
. 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 thesrc
andalt
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.