alby-generative-qa

Prerequisites

Ensure alby is installed to unlock these elements and elevate your storefront. Learn more here.

Usage

The alby-generative-qa component can be embedded in your webpage with various attributes to customize its behavior.

Basic Example

<alby-generative-qa 
  widget-id="widget-id"   
  product-id="product-id"
</alby-generative-qa>

Properties

Attribute	Description	Type	Default	Required
product-id	The external product ID, matching the identifier provided in your product feed. Important:* If this product ID is not found in our system, Alby will not render. Ensure all product IDs match those in your product feed.	string	`undefined`	Yes
variant-id	The unique identifier for a specific product variant, matching the variant ID in your product feed. This helps the AI provide more accurate responses by referencing the exact variant a shopper is viewing—such as different sizes, colors, or configurations of a product. Important:* If the provided variant ID does not exist in our system for the associated product ID, Alby will not render. Ensure that all variant IDs in your implementation match those in your product feed.	string	`undefined`	No
widget-id	The unique identifier for the widget, found on the Widget Embed page in the alby Dashboard. Required for correctly loading the designated widget instance.	string	`undefined`	Yes
test-mode	Enables internal testing of the widget. When enabled, conversations created will not appear in the inbox or impact reporting. This is not related to A/B testing.	string	`false`	No
thread-id	Resumes a previous conversation by referencing an existing thread. If provided, the AI will continue from where the conversation left off instead of starting a new session. See the browser events guide on how to retrieve a thread ID.	string	`undefined`	No
test-id	A unique identifier for the test instance. See the A/B Testing Attributes Guide for usage details.	string	`undefined`	No
test-version	Defines the A/B test version (`alby` or `control`). See the A/B Testing Attributes Guide for usage details.	string	`undefined`	No
test-description	Optional description for the test setup. See the A/B Testing Attributes Guide for usage details.	sgring	`undefined`	No

Methods

switchProduct

Switches the current product context of the widget. Updates product ID and optionally variant ID, then resets the widget to show relevant questions for the new product.

Note: This will clear any existing conversation and return the widget to its default state.

Parameters

productId: string (required) - The ID of the product to switch to
variantId: string (optional) - The ID of a specific variant of the product

Example

const albyQA = document.querySelector('alby-generative-qa');  
await albyQA.switchProduct('product_123', 'variant_456');

import { useRef, useEffect } from 'react';

function ProductPage() {
  const albyRef = useRef(null);

  const handleProductChange = async (productId, variantId) => {
    if (albyRef.current) {
      await albyRef.current.switchProduct(productId, variantId);
    }
  };

  return (
    <div>
      <alby-generative-qa ref={albyRef} product-id="initial_product"  />
      <button onClick={() => handleProductChange('product_123', 'variant_456')}>
        Switch Product
      </button>
    </div>
  );
}

updateCategory

Updates the current category context of the widget. Updates category and product IDs, then resets the widget to show relevant questions for the new category.

Note: This will clear any existing conversation and return the widget to its default state.

Parameters

category: string (required) - The category to switch to
productIds: string (required) - Comma-separated list of product IDs associated with the category

Example

const albyQA = document.querySelector('alby-generative-qa');  
await albyQA.updateCategory('electronics', 'product_123,product_456,product_789');

import { useRef, useEffect } from 'react';

function CategoryPage() {
  const albyRef = useRef(null);

  const handleCategoryChange = async (category, productIds) => {
    if (albyRef.current) {
      await albyRef.current.updateCategory(category, productIds);
    }
  };

  return (
    <div>
      <alby-generative-qa ref={albyRef} category="initial_category" product-ids="product_1,product_2" />
      <button onClick={() => handleCategoryChange('electronics', 'product_123,product_456,product_789')}>
        Switch to Electronics
      </button>
    </div>
  );
}