Algolia AI / Shopping Guides / Guides

Integrating Algolia Shopping Guides into your website

After you’ve created a set of shopping 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 shopping guides, you need frontend development proficiency with HTML, CSS, JavaScript, and React. You should also have created your shopping guides.

Installation

Install the @algolia/commerce-ai package using npm or yarn:

$
$
$
npm install @algolia/commerce-ai@npm:project-qsdf
# or
yarn add @algolia/commerce-ai@npm:project-qsdf

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
9
10
11
12
13
14
15
import { createClient } from '@algolia/commerce-ai';

const client = createClient({
  host: 'API_HOST_URL',
  content: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_API_KEY',
    indexName: 'YOUR_CONTENT_INDEX_NAME',
  },
  source: {
    appId: 'YOUR_SOURCE_APP_ID',
    apiKey: 'YOUR_SOURCE_API_KEY',
    indexName: 'YOUR_SOURCE_INDEX_NAME',
  },
});

Parameters

  • host. Fetches data from the API. By default, this is set to https://generative-ai.algolia.com but you may set it, for example, to /proxy to proxy the requests to the API through your server.
  • content. The Algolia credentials for the index that contains the shopping guide content.
  • source. The Algolia credentials for the index that contains the source data for the shopping guides. This is only used when any of the generation methods are used.

Provide the client across your app

To provide the client to the whole app, wrap your application in the AiCommerce component.

1
2
3
4
5
6
7
8
9
10
11
12
13
import { AiCommerce, createClient } from '@algolia/commerce-ai';

const client = createClient({
  // ...
});

function Layout({ children }) {
  return (
    <AiCommerce client={client}>
      <App />
    </AiCommerce>
  );
}

Linking to shopping guides

Referencing different shopping guides on your website can be achieved using the ShoppingGuideHeadlines widget. This can be embedded in your home page, product detail page or search pages, and can be customized to display headlines based on categories or specific objects.

  • ShoppingGuideHeadlines Wrapper for retrieving headlines. Can be used standalone
  • ShoppingGuideHeadlinesContent displays the headlines.
  • ShoppingGuideHeadlinesButton lets users hide or show headlines.
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
import {
  ShoppingGuideHeadlines,
  ShoppingGuideHeadlinesButton,
  ShoppingGuideHeadlinesContent,
  useShoppingGuideHeadlines,
  AiCommerce,
  createClient,
} from '@algolia/commerce-ai';

const client = createClient({
  content: {
    appId: '...',
    apiKey: '...',
    indexName: '...',
  },
  source: {
    appId: '...',
    apiKey: '...',
    indexName: '...',
  },
});

<AiCommerce client={client}>
  <ShoppingGuideHeadlines category={category} nbHeadlines={3}>
    <ShoppingGuideHeadlinesButton />
    <ShoppingGuideHeadlinesContent />
  </ShoppingGuideHealdines>
</AiCommerce>;

Shopping guides button

Guides cells

Displaying guide body content

To show the body content of a shopping guide:

  1. Use the useShoppingGuideContent hook to retrieve the content from the generated guides.
  2. Display this content with the ShoppingGuideContent widget.

To show related products in a guide, use the HitComponent function to define the visual representation of these products.

Guide content related

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
import {
  ShoppingGuideContent,
  useShoppingGuideContent,
  createClient,
} from '@algolia/commerce-ai';

const client = createClient({
  host: '...',
  content: {
    appId: '...',
    apiKey: '...',
    indexName: '...',
  },
  source: {
    appId: '...',
    apiKey: '...',
    indexName: '...',
  },
});

function Page() {
  const { content, error } = useShoppingGuideContent({
    objectID: '123',
    immediate: true,
    initialContent: null,
    client,
  });

  return <ShoppingGuideContent {...content} hitComponent={HitComponent} />;
}

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

Guide content related

Displaying website-specific content

Some of the generated shopping 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 functions.

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
import {
  AiCommerce,
  createClient,
  type CommerceGetters,
} from '@algolia/commerce-ai';

const client = createClient({
  // ...
});

const getters: CommerceGetters = {
  /**
   * 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 })),
};

function App() {
  return (
    <AiCommerce client={client} getters={getters}>
      {/* Your app */}
    </AiCommerce>
  );
}

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 aren’t 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={{
    root: 'YOUR_ROOT_CLASS',
    button: 'YOUR_BUTTON_CLASS',
    content: 'YOUR_CONTENT_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, add the following CSS to your project:

Applying CSS to the existing classes

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
128
129
130
131
132
133
134
135
136
137
.ais-ShoppingGuideHeadlinesButton-button {
  @apply flex items-center space-x-2 whitespace-nowrap inline-block rounded font-semibold text-center shadow-sm transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 px-3.5 py-2.5;
}

.ais-ShoppingGuideHeadlinesButton-buttonNotShowing {
  @apply bg-orange-400 hover:bg-orange-500 focus-visible:outline-orange-500 text-white;
}

.ais-ShoppingGuideHeadlinesButton-buttonShowing {
  @apply 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;
}

.ais-ShoppingGuideHeadlinesButton-buttonLoading {
  @apply opacity-50 cursor-not-allowed;
}

.ais-ShoppingGuideHeadlinesButton-icon {
  @apply w-5 h-5 flex-shrink-0;
}

.ais-ShoppingGuideHeadlinesButton-iconLoading {
  @apply animate-spin;
}

.ais-NoWrap {
  @apply whitespace-nowrap;
}

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

.ais-ShoppingGuideHeadlinesContent-wrapper {
  @apply flex flex-col items-end rounded p-4 border border-gray-200 shadow gap-2;
}

.ais-ShoppingGuideHeadlinesContent-container {
  @apply grid grid-cols-2 lg:grid-cols-4 gap-4;
}

.ais-ShoppingGuideHeadlinesContent-readMore {
  @apply text-orange-500 font-semibold;
}

.ais-ShoppingGuideHeadlinesContent-item {
  @apply bg-gray-100 rounded p-4 space-y-3 flex flex-col justify-between;
}

.ais-ShoppingGuideHeadlinesContent-itemContent {
  @apply space-y-3;
}

.ais-ShoppingGuideHeadlinesContent-itemTitle {
  @apply text-orange-500 font-semibold;
}

.ais-ShoppingGuideHeadlinesContent-itemImage {
  @apply relative aspect-video overflow-hidden;
}

.ais-ShoppingGuideContent-contentSection {
  @apply prose max-w-prose mx-auto px-4;
}

.ais-ShoppingGuideContent-heroImage {
  @apply mx-auto;
}

.ais-ShoppingGuideContent-productLink {
  @apply bg-blue-900 text-white rounded inline-block px-3 py-1 no-underline;
}

.ais-ShoppingGuideContent-feedbackContainer {
  @apply flex flex-col;
}

.ais-ShoppingGuideContent .ais-Feedback {
  @apply self-end;
}

.ais-ShoppingGuideContent-relatedItemsSection {
  @apply prose max-w-none;
}

.ais-ShoppingGuideContent-factorSection {
  @apply grid;
  grid-template-columns: 1fr 11fr;
}

.ais-ShoppingGuideContent-factorSection [aria-hidden] {
  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
}

.ais-ShoppingGuideContent-heroImage {
  @apply mx-auto;
}

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

.ais-ShoppingGuideContent-relatedItemsListContainer {
  @apply max-w-none px-4;
}

.ais-ShoppingGuideContent-relatedItemsList {
  @apply p-0 grid gap-6 grid-cols-2 md:grid-cols-2 lg:grid-cols-4;
}

.ais-Feedback {
  @apply text-gray-500 text-sm flex items-center space-x-4;
}

.ais-Feedback-thanksWrapper {
  @apply flex space-x-2 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-5 w-5 stroke-2 flex-shrink-0;
}

Adding classes to the widgets

If you’ve configured Tailwind CSS to keep certain classes from being purged, you can also use the classNames property to dynamically apply these classes to your elements.

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
const theme = {
  ShoppingGuideHeadlinesButton: {
    button:
      'flex items-center space-x-2 whitespace-nowrap inline-block rounded font-semibold text-center shadow-sm transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 px-3.5 py-2.5',
    buttonNotShowing:
      'bg-orange-400 hover:bg-orange-500 focus-visible:outline-orange-500 text-white',
    buttonShowing:
      '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',
    buttonLoading: 'opacity-50 cursor-not-allowed',
    icon: 'w-5 h-5 flex-shrink-0',
    iconLoading: 'animate-spin',
  },
  ShoppingGuideHeadlinesContent: {
    wrapper:
      'flex flex-col items-end rounded p-4 border border-gray-200 shadow gap-2',
    container: 'grid grid-cols-2 lg:grid-cols-4 gap-4',
    item: 'bg-gray-100 rounded p-4 space-y-3 flex flex-col justify-between',
    itemContent: 'space-y-3',
    itemTitle: 'text-orange-500 font-semibold',
    itemImage: 'relative aspect-video overflow-hidden',
  },
  ShoppingGuideContent: {
    contentSection: 'prose max-w-prose mx-auto px-4',
    heroImage: 'mx-auto',
    productLink:
      'bg-blue-900 text-white rounded inline-block px-3 py-1 no-underline',
    feedbackContainer: 'flex flex-col',
    Feedback: { root: 'self-end' },
    relatedItemsSection: 'prose max-w-none',
    relatedItemsTitle: 'max-w-prose mx-auto px-4',
    relatedItemsListContainer: 'max-w-none px-4',
    relatedItemsList:
      'p-0 grid gap-6 grid-cols-2 md:grid-cols-2 lg:grid-cols-4',
  },
  Feedback: {
    root: 'text-gray-500 text-sm flex items-center space-x-4',
    thanksWrapper: 'flex space-x-2 items-center',
    labelWrapper: 'flex space-x-2 items-center',
    labelIcon: 'h-6 w-6 flex-shrink-0',
    buttonsWrapper: 'flex space-x-3 items-center',
    button:
      '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',
    buttonIcon: 'h-5 w-5 stroke-2 flex-shrink-0',
  },
  NoWrap: 'whitespace-nowrap',
  ScreenReaderOnly: 'sr-only',
};

Next step

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

Did you find this page helpful?