Algolia AI / Shopping Guides / Guides

Integrating Algolia Shopping Guides into your website

On this page

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:

Copy 
$
$
$

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:

Copy 
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.

Copy 
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.
Copy 
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

Copy 
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.

Copy 
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.

Copy 
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

Copy 
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.

Copy 
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',
};

Gathering feedback

To gather feedback on the Shopping Guides you can use the <Feedback /> component from the @algolia/commerce-ai client library. You can add this component in a Shopping Guide Content page, or when you are displaying the Shopping Guides Headlines.

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

Copy 
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

import {
  createClient,
} from '@algolia/commerce-ai';

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

function Page() {
  [...]

  return (
    [...]

    <Feedback
      objectIDs={[objectID]}
      userToken={userToken}
      voteTarget="content"
    />
  )
}

Parameters

  • objectIDs (required). An array of object IDs of the guides for which you want to gather feedback.
  • userToken (required). The user token.
  • voteTarget ("content"|"headline"). The target of a user’s feedback. It can be content if the feedback is gathered on the Shopping Guide content, or headline if you are gathering feedback on the Shopping Guides headlines (default: content).

Gathering feedback with a custom component

You can also gather users’ feedback using your own custom components, by using the @algolia/commerce-ai client /vote method to send feedback for your Shopping Guides.

Copy 
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

import {
  createClient,
} from '@algolia/commerce-ai';

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

function Page() {
  [...]

  return (
    [...]

    <MyCustomUpvoteFeedback
      onClick={(vote) =>
        client.vote({
          objectIDs,
          voteType: 'upvote',
          voteTarget,
          userToken,
        })
      }
    />
  )
}

Parameters

  • objectIDs (required). An array of object IDs of the guides for which you want to gather feedback.
  • userToken (required). The user token.
  • voteTarget ("content"|"headline"). The target of a user’s feedback. It can be content, if the feedback is gathered on the Shopping Guide content, or headline if you are gathering feedback on the Shopping Guides headlines (default: content).
  • voteType (required)(upvote downvote). The type of feedback. It can be upvote for a positive feedback, or downvote for a negative feedback.

Add the shopping guides using JavaScript

To integrate the shopping guides in your project, use the methods available in the Algolia Commerce client.

Installation and initialization

Start by installing the @algolia/commerce-ai package and set up the Algolia Commerce client.

Next, reference and add the shopping guides in your home page, search pages, or product details pages with the getHeadlines() method:

Copy 
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

import { createClient } from '@algolia/commerce-ai';

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

[...]

client.getHeadlines({
  category,
  nbHeadlines,
  searchParams,
  onlyPublished
}).then((data) => {
  // display the shopping guides headlines
})

Parameters

  • category (required). Category of the Shopping Guides you want to display (for example, “accessories”).
  • nbHeadlines. Number of headlines you want to fetch (default: 4).
  • searchParams. Search parameters to pass to the Algolia search for headlines.
  • onlyPublished. Whether to fetch only guides that are published (default: true).

Display guide body content

To display the content of a shopping guide, use the getContent() method:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import { createClient } from '@algolia/commerce-ai';

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

[...]

client.getContent({
  objectID,
  onlyPublished
}).then((data) => {
  // display the shopping guide content
})

Parameters

  • objectID (required). The object ID of the guide you want to display.
  • onlyPublished. Whether to fetch only guides that are published (default: true).

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?