Skip to main content
After creating a set of guides, you need to integrate them into your website.

​
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: 
npm install @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:
JavaScript
import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "your_index_name",
  searchOnlyAPIKey: "ALGOLIA_SEARCH_API_KEY",
  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.
React
import { createClient } from "@algolia/generative-experiences-api-client";
import { GuideContent } from "@algolia/generative-experiences-react";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "your_index_name",
  searchOnlyAPIKey: "ALGOLIA_SEARCH_API_KEY",
});

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} />}
    />
  );
}
Guide Content component

​
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.
React
import { createClient } from "@algolia/generative-experiences-api-client";
import { GuidesHeadlines } from "@algolia/generative-experiences-react";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "your_index_name",
  searchOnlyAPIKey: "ALGOLIA_SEARCH_API_KEY",
});

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

​
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 widget. For more information, see GuidesFeedback.
This feature uses the Insights API to gather events related to Guides feedback. This requires a user token.
React
import { createClient } from "@algolia/generative-experiences-api-client";
import { GuidesFeedback } from "@algolia/generative-experiences-react";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "your_index_name",
  searchOnlyAPIKey: "ALGOLIA_SEARCH_API_KEY",
});

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

​
Display 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.
React
import { createClient } from "@algolia/generative-experiences-api-client";
import { GuideContent } from "@algolia/generative-experiences-react";

const gseClient = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "your_index_name",
  searchOnlyAPIKey: "ALGOLIA_SEARCH_API_KEY",
});

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 unstyled by default. You can style them with the classNames property or by applying your CSS to the existing classes.

​
With the classNames property

Use the classNames property to add classes to the widgets.
React
<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.

​
With 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.
CSS
.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

After creating the mechanism for displaying your guides, publish them to show them in your live environment.