# Autocomplete Clicks Source: https://help.experro.com/analytics_sdk/builtin_events/ac_click ## Autocomplete Clicks (`ac_click`) **Purpose:** Track when a user selects or clicks on a suggestion in the autocomplete dropdown whether it’s a recent search, popular search, product recommendation, category, or other suggestion type. **When to Fire:** In the click handler for your autocomplete suggestions, immediately after the user selects one. **Payload Schema:** | Field | Type | Description | | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `ac_source` | string | Type of suggestion clicked (e.g. `"search_suggestion"`, `"popular_search"`, `"recent_search"`, `"category"`, `"product"`, `"content"`). | | `used_suggestion` | string | The actual suggestion text or identifier the user clicked (e.g. `"jeans"`). | | `search_term` | string | The user’s input at the time of click (e.g. `"shi"`). | **Example:** ```js theme={null} // In your autocomplete click handler: const clickedSuggestion = 'jeans'; const searchTerm = 'jea'; const suggestionType = 'search_suggestion'; ExpAnalyticsService.trackAcClick({ used_suggestion: clickedSuggestion, ac_source: suggestionType, search_term: searchTerm }); ``` # Autocomplete Impressions Source: https://help.experro.com/analytics_sdk/builtin_events/ac_impressions ## Autocomplete Impression (`ac_impression`) **Purpose:** Track when a user is shown autocomplete or suggestion data whether it’s recent searches, popular searches, category or product suggestions, or other content from your search‑suggestion API. **When to Fire:** Immediately after your autocomplete/suggestion API returns its response or before you render the suggestion dropdown or list. **Payload Schema:** | Field | Type | Description | | --------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `no_of_results` | number | Total number of suggestions length. | | `ac_source` | string | Source of suggestions (e.g. `"search_suggestion"`, `"popular_search"`, `"recent_search"`, `"category"`, `"product"`, `"content"`). | | `search_term` | string | The user’s current search input. | | `items` | array of strings | Array of suggestion identifiers (e.g. SKUs, category IDs, or free‑form suggestion strings). | **Example:** ```js theme={null} // After your autocomplete API returns: const sourceType = 'popular_search'; const searchTerm = 'running shoes'; const suggestionCount = suggestions.length; // e.g. 3 const suggestions = suggestions.items; // e.g. ['shirts','jeans','shoes'] ExpAnalyticsService.trackAcImpression({ ac_source: sourceType, search_term: searchTerm, no_of_results: suggestionCount, items: suggestions }); ``` # Authentication Events Source: https://help.experro.com/analytics_sdk/builtin_events/auth_events These calls let you tie anonymous sessions to real users and keep their profile data up to date. ## Identify the User on Login **What happens?** When a visitor logs in, you replace the SDK’s anonymous session ID with their known user ID (often their email). From that point on, every event they generate is attributed to that ID. **When to call it?** Right after your login flow succeeds. **How to call it:** ```js theme={null} ExpAnalyticsService.login(userEmail); ``` * `userEmail`: a unique string for this user. ## Revert to Anonymous on Logout **What happens?** When they log out, you discard the user’s ID and switch back to a fresh anonymous identifier, so further events aren’t tied to their account. **When to call it?** Right after your logout flow completes. **How to call it:** ```js theme={null} ExpAnalyticsService.logout(); ``` ## Send or Update User Profile **What happens?** You upload the user’s metadata—name, email, organization, phone, plus any custom fields to the analytics backend so you can segment on those attributes. **When to call it?** * Immediately after login (to set up the profile). * Any time the user updates their account info. **How to call it:** ```js theme={null} const userDetails = { name: 'Jane Doe', username: 'jdoe', email: 'jane.doe@example.com', organization: 'Acme Corp', phone: '+1-555-1234', custom: { plan: 'premium', signupDate: '2025-07-01' } }; // Enqueue the profile-update event ExpAnalyticsService.updateUserDetails(userDetails); ``` ### Putting It All Together 1. **Anonymous browsing**: SDK uses a generated session/device ID. 2. **Login**: * Call `login` → switches to the user’s ID. * Call `updateUserDetails` → uploads their profile attributes. 3. **Logout**: * Call `logout` → switches back to anonymous. This flow ensures every event is correctly tagged with the right user context, and that you always have their latest profile data for reporting and analysis. # Cart Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/cart_viewed ## Cart Viewed (`cart_viewed`) **Purpose:** Track when a user views their shopping cart page, capturing overall cart metrics and detailed per-item context. **When to Fire:** Immediately upon rendering the cart page or when the cart modal is opened. **Payload Schema:** | Field | Type | Description | | ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | `total_value` | number | Total cart value (`totalValue`, typically `cart_amount`). | | `total_quantity` | number | Total number of items in the cart. | | `cart_id` | string | Unique identifier for the cart session. | | `base_amount` | number | Sum of item list prices before discounts. | | `cart_amount` | number | Final payable amount after discounts and fees. | | `products` | array of objects | List of cart items, each with detailed fields: | |   – `sku` | string | Product SKU. | |   – `variant_sku` | string | Selected variant SKU. | |   – `product_category` | array of objects | Category hierarchy, each `{ id, name, provider_id }`. | |   – `mode` | string | Origin of the item addition (`"widget"`, `"search"`, `"category"`, `"collection"`, `"direct"`). | |   – `search_term` | string | User search input if applicable. | |   – `search_location` | string | `"quick"` or `"page"` if from search. | |   – `category` | string | Category ID or name if from category. | |   – `collection` | string | Collection ID or name if from collection. | |   – `total_value` | number | Extended sale price (`quantity * sale_price`). | |   – `quantity` | number | Units of this SKU in the cart. | |   – `widget_rule` | string | Rule ID that applied. | |   – `widget_rule_type` | string | Type of rule. | |   – `widget_id` | string | Widget instance ID if relevant. | |   – `widget_context_type` | string | Context entity type. | |   – `widget_context_data` | string | Additional context payload. | |   – `facets` | array | Active filters on the cart page. | |   – `product_option` | array of objects | Selected product options per item, each `{ name, value }`. | |  – `request_id` | string | Unique identifier | |  – `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // After the cart data loads: const cart = { id: 'CART-789', base_amount: 200.00, cart_amount: 180.00, total_quantity: 1, items: [ { sku: 'PROD-001', variant_sku: 'PROD-001-BLUE', product_category: [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }], total_value: 129.99, quantity: 1, mode: 'direct', mode_details: { search_term: 'jack', search_location: 'page', search_source: 'search_suggestion', used_suggestion: 'jacket', category: null, collection: null, widget_rule: null, widget_rule_type: null, widget_id: null, widget_context_type: 'direct', widget_context_data: '', request_id: requestId, page_depth: currentPage, facets: [], }, product_option: [{ name: 'Size', value: 'M' }] } ] }; ExpAnalyticsService.trackCartViewed({ total_value: cart.cart_amount, total_quantity: cart.total_quantity, cart_id: cart.id, base_amount: cart.base_amount, cart_amount: cart.cart_amount, products: cart.items || [], }); ``` # Category Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/category_viewed ## Category Viewed (`category_viewed`) **Purpose:** Track when a user lands on or refreshes a category listing page to view products in that category. **When to Fire:** After your page or API loads the category data and product SKUs typically on page load or when your view changes to a category view. **Payload Schema:** | Field | Type | Description | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------- | | `category_id` | string or number | Unique identifier of the category. | | `category_name` | string | Human‑readable category name. | | `sku` | array of strings | Flat array of SKUs for all products in this category. | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"category"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `facets` | array | Active filters (e.g. size, brand)—each `{ field, value }`. Use an empty array if none. | | `request_id` | string | Unique identifier for the search request (x-request-id from response headers). | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // Assume these variables are populated from your category response and UI state: const categoryId = 'cat123'; const categoryName = 'Running Shoes'; const selectedFacets = []; // e.g. [{ field: 'size', value: '10' }] const requestId = categoryResponse.headers.get('x-request-id'); const currentPage = 1; // Current page number (1, 2, 3, etc.) const products = [ { sku: 'RS-001', name: 'Lightweight Runner' }, { sku: 'RS-002', name: 'Marathon Pro' } ]; ExpAnalyticsService.trackCategoryViewed({ category_id: categoryId, category_name: categoryName, sku: products.map(p => p.sku), used_suggestion: usedSuggestion, search_source: searchSource, facets: selectedFacets, request_id: requestId, page_depth: currentPage }); ``` # Checkout Completed Source: https://help.experro.com/analytics_sdk/builtin_events/checkout_completed ## Checkout Completed (`checkout_completed`) **Purpose:** Track when a user successfully completes their order, capturing final transaction details and full line-item breakdown. **When to Fire:** Immediately after the confirmation or “Thank You” page renders — as soon as the order is finalized in your system. **Payload Schema:** | Field | Type | Description | | ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | `total_value` | number | Total order value (`totalValue`). | | `total_quantity` | number | Total number of items purchased (`totalQuantity`). | | `cart_id` | string | Identifier of the cart session prior to purchase. | | `order_id` | string | Unique identifier of the completed order. | | `currency_code` | string | Currency code for the transaction (e.g. `"USD"`). | | `total_ex_tax` | number | Total order amount excluding tax. | | `products` | array of objects | List of cart items, each with detailed fields: | |   – `sku` | string | Product SKU. | |   – `variant_sku` | string | Selected variant SKU. | |   – `product_category` | array of objects | Category hierarchy, each `{ id, name, provider_id }`. | |   – `mode` | string | Origin of the item addition (`"widget"`, `"search"`, `"category"`, `"collection"`, `"direct"`). | |   – `search_term` | string | User search input if applicable. | |   – `search_location` | string | `"quick"` or `"page"` if from search. | |   – `category` | string | Category ID or name if from category. | |   – `collection` | string | Collection ID or name if from collection. | |   – `total_value` | number | Extended sale price (`quantity * sale_price`). | |   – `quantity` | number | Units of this SKU in the cart. | |   – `widget_rule` | string | Rule ID that applied. | |   – `widget_rule_type` | string | Type of rule. | |   – `widget_id` | string | Widget instance ID if relevant. | |   – `widget_context_type` | string | Context entity type. | |   – `widget_context_data` | string | Additional context payload. | |   – `facets` | array | Active filters on the cart page. | |   – `product_option` | array of objects | Selected product options per item, each `{ name, value }`. | |  – `request_id` | string | Unique identifier | |  – `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // After order confirmation: const order = { totalValue: 250.00, total_quantity: 2, cart_id: 'CART-789', order_id: 'ORDER-456', currency_code: 'USD', total_ex_tax: 230.00, items: [ { sku: 'PROD-001', variant_sku: 'PROD-001-BLUE', product_category: [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }], total_value: 129.99, quantity: 1, mode: 'direct', mode_details: { search_term: 'jack', search_location: 'page', search_source: 'search_suggestion', used_suggestion: 'jacket', category: null, collection: null, widget_rule: null, widget_rule_type: null, widget_id: null, widget_context_type: 'direct', widget_context_data: '', request_id: requestId, page_depth: currentPage, facets: [], }, product_option: [{ name: 'Size', value: 'M' }] } ] }; ExpAnalyticsService.trackCheckoutCompleted({ total_value: order.totalValue, total_quantity: order.total_quantity, order_id: order.order_id, cart_id: order.cart_id, currency_code: order.currency_code, total_ex_tax: order.total_ex_tax, products: order.items || [], }); ``` # Checkout Initiated Source: https://help.experro.com/analytics_sdk/builtin_events/checkout_initiated ## Checkout Initiated (`checkout_initiated`) **Purpose:** Track when a user begins the checkout process by viewing the checkout page or proceeding to the payment step. **When to Fire:** Immediately upon rendering the checkout page or opening the checkout modal. **Payload Schema:** | Field | Type | Description | | ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- | | `total_value` | number | Total cart value (`totalValue`, typically `cart_amount`). | | `total_quantity` | number | Total number of items in the cart. | | `cart_id` | string | Unique identifier for the cart session. | | `products` | array of objects | List of cart items, each with detailed fields: | |   – `sku` | string | Product SKU. | |   – `variant_sku` | string | Selected variant SKU. | |   – `product_category` | array of objects | Category hierarchy, each `{ id, name, provider_id }`. | |   – `mode` | string | Origin of the item addition (`"widget"`, `"search"`, `"category"`, `"collection"`, `"direct"`). | |   – `search_term` | string | User search input if applicable. | |   – `search_location` | string | `"quick"` or `"page"` if from search. | |   – `category` | string | Category ID or name if from category. | |   – `collection` | string | Collection ID or name if from collection. | |   – `total_value` | number | Extended sale price (`quantity * sale_price`). | |   – `quantity` | number | Units of this SKU in the cart. | |   – `widget_rule` | string | Rule ID that applied. | |   – `widget_rule_type` | string | Type of rule. | |   – `widget_id` | string | Widget instance ID if relevant. | |   – `widget_context_type` | string | Context entity type. | |   – `widget_context_data` | string | Additional context payload. | |   – `facets` | array | Active filters on the cart page. | |   – `product_option` | array of objects | Selected product options per item, each `{ name, value }`. | |  – `request_id` | string | Unique identifier | |  – `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // After loading checkout data: const cart = { id: 'CART-789', cart_amount: 180.00, total_quantity: 1, items: [ { sku: 'PROD-001', variant_sku: 'PROD-001-BLUE', product_category: [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }], total_value: 129.99, quantity: 1, mode: 'direct', mode_details: { search_term: 'jack', search_location: 'page', search_source: 'search_suggestion', used_suggestion: 'jacket', category: null, collection: null, widget_rule: null, widget_rule_type: null, widget_id: null, widget_context_type: 'direct', widget_context_data: '', request_id: requestId, page_depth: currentPage, facets: [], }, product_option: [{ name: 'Size', value: 'M' }] } ] }; ExpAnalyticsService.trackCheckoutInitiated({ total_value: cart.cart_amount, total_quantity: cart.total_quantity, cart_id: cart.id, products: cart.items || [], }); ``` # Collection Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/collection_viewed ## Collection Viewed (`collection_viewed`) **Purpose:** Track when a user lands on a collection listing page to browse a specific grouping of products. **When to Fire:** After your page or API loads the collection data and the associated product SKUs typically on page load or when your view changes to a collection view. **Payload Schema:** | Field | Type | Description | | ----------------- | ---------------- | -------------------------------------------------------------------------------------- | | `collection_id` | string or number | Unique identifier of the collection. | | `collection_name` | string | Human‑readable collection name. | | `sku` | array of strings | Flat array of SKUs for all products in this collection. | | `facets` | array | Active filters (e.g. size, brand)—each `{ field, value }`. Use an empty array if none. | | `request_id` | string | Unique identifier for the search request (x-request-id from response headers). | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // Assume these variables are populated from your collection response and UI state: const collectionId = 'cat123'; const collectionName = 'Running Shoes'; const selectedFacets = []; // e.g. [{ field: 'size', value: '10' }] const requestId = collectionResponse.headers.get('x-request-id'); const currentPage = 1; // Current page number (1, 2, 3, etc.) const products = [ { sku: 'RS-001', name: 'Lightweight Runner' }, { sku: 'RS-002', name: 'Marathon Pro' } ]; ExpAnalyticsService.trackCollectionViewed({ collection_id: collectionId, collection_name: collectionName, sku: products.map(p => p.sku), facets: selectedFacets, request_id: requestId, page_depth: currentPage }); ``` # Product Added to Cart Source: https://help.experro.com/analytics_sdk/builtin_events/product_add_to_cart ## Product Added to Cart (`product_added_to_cart`) **Purpose:** Track when a user adds a product (or variant) to their shopping cart, capturing both quantity and context of where the action originated. **When to Fire:** Immediately after the “Add to Cart” action completes whether from a product page, quick-view modal, recommendation widget, or any listing. **Payload Schema:** | Field | Type | Description | | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | `sku` | string | The SKU of the product being viewed. | | `variant_sku` | string | The SKU of the selected variant (if any); otherwise the default variant SKU. | | `quantity` | number | Number of units added. | | `total_value` | number | Total value of items added (`totalValue`, e.g. `price * quantity`). | | `mode` | string | Where the view originated: | |    | | – `"widget"` | |    | | – `"search"` | |    | | – `"category"` | |    | | – `"collection"` | |    | | – `"direct"` (e.g. bookmarked or deep link) | | `search_term` | string | Current search term (if mode is `"search"`). | | `search_location` | string | `"quick"` or `"page"` (if mode is `"search"`). | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"popular_search"`, `"recent_search"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `category` | string | name (if mode is `"category"`). | | `collection` | string | Collection ID (if mode is `"collection"`). | | `widget_rule` | string | Rule ID that generated this view context. | | `widget_rule_type` | string | Type of rule. | | `widget_id` | string | Widget instance ID (if mode is `"widget"`). | | `widget_context_type` | string | Entity type for context. | | `widget_context_data` | string | Additional context payload. | | `mode_details` | object | Nested object repeating the above fields specific to the chosen `mode`. | | `product_option` | array of objects | Selected product options, each `{ name: , value: }`. | | `product_categories` | array of objects | Category hierarchy for this product, each `{ id, name, provider_id }`. | | `facets` | array | Active filters when navigating to the product (each `{ field, value }`). | | `request_id` | string | Unique identifier | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // After the user clicks “Add to Cart”: const sku = 'PROD-001'; const variantSku = 'PROD-001-BLUE'; const quantity = 2; const totalValue = price * quantity; const mode = 'search'; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) const modeDetails = { search_term: 'jack', search_location: 'page', used_suggestion: 'jacket', search_source: 'search_suggestion', category: null, collection: null, widget_rule: 'rule42', widget_rule_type: 'personalization', widget_id: null, widget_context_type: 'search', widget_context_data: '', facets: facets, request_id: requestId, page_depth: currentPage }; const productOptions = [{ name: 'Size', value: 'M' }]; const productCategory = [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }]; ExpAnalyticsService.trackProductAddedToCart({ sku, variant_sku: variantSku, total_value: totalValue, quantity, mode, mode_details: modeDetails, product_option: productOptions, product_categories: productCategory, }); ``` # Product Removed from Cart Source: https://help.experro.com/analytics_sdk/builtin_events/product_remove_from_cart ## Product Removed from Cart (`product_removed_from_cart`) **Purpose:** Track when a user removes one or more units of a product (or variant) from their shopping cart, capturing both quantity removed and contextual metadata. **When to Fire:** Immediately after the “Remove from Cart” action completes. **Payload Schema:** | Field | Type | Description | | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | `sku` | string | The SKU of the product being viewed. | | `variant_sku` | string | The SKU of the selected variant (if any); otherwise the default variant SKU. | | `quantity` | number | Number of units added. | | `total_value` | number | Total value of items added (`totalValue`, e.g. `price * quantity`). | | `mode` | string | Where the view originated: | |    | | – `"widget"` | |    | | – `"search"` | |    | | – `"category"` | |    | | – `"collection"` | |    | | – `"direct"` (e.g. bookmarked or deep link) | | `search_term` | string | Current search term (if mode is `"search"`). | | `search_location` | string | `"quick"` or `"page"` (if mode is `"search"`). | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"popular_search"`, `"recent_search"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `category` | string | name (if mode is `"category"`). | | `collection` | string | Collection ID (if mode is `"collection"`). | | `widget_rule` | string | Rule ID that generated this view context. | | `widget_rule_type` | string | Type of rule. | | `widget_id` | string | Widget instance ID (if mode is `"widget"`). | | `widget_context_type` | string | Entity type for context. | | `widget_context_data` | string | Additional context payload. | | `mode_details` | object | Nested object repeating the above fields specific to the chosen `mode`. | | `product_option` | array of objects | Selected product options, each `{ name: , value: }`. | | `product_categories` | array of objects | Category hierarchy for this product, each `{ id, name, provider_id }`. | | `facets` | array | Active filters when navigating to the product (each `{ field, value }`). | | `request_id` | string | Unique identifier | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // After the user removes items from their cart: const sku = 'PROD-001'; const variantSku = 'PROD-001-BLUE'; const quantity = 2; const totalValue = price * quantity; const mode = 'search'; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) const modeDetails = { search_term: 'jack', search_location: 'page', used_suggestion: 'jacket', search_source: 'search_suggestion', category: null, collection: null, widget_rule: 'rule42', widget_rule_type: 'personalization', widget_id: null, widget_context_type: 'search', widget_context_data: '', facets: facets, request_id: requestId, page_depth: currentPage }; const productOptions = [{ name: 'Size', value: 'M' }]; const productCategory = [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }]; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) ExpAnalyticsService.trackProductRemovedFromCart({ sku, variant_sku: variantSku, total_value: totalValue, quantity, mode, mode_details: modeDetails, product_option: productOptions, product_categories: productCategory, }); ``` # Product Variant Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/product_variant_viewed ## Product Variant Viewed (`product_variant_viewed`) **Purpose:** Track when a user switches to or views a specific variant of a product whether on the product page or within a quick-view. **When to Fire:** Immediately after the variant change action completes (e.g. user selects a size/color option). **Payload Schema:** | Field | Type | Description | | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | `sku` | string | The SKU of the product being viewed. | | `variant_sku` | string | The SKU of the selected variant (if any); otherwise the default variant SKU. | | `name` | string | Product name. | | `mode` | string | Where the view originated: | |    | | – `"widget"` | |    | | – `"search"` | |    | | – `"category"` | |    | | – `"collection"` | |    | | – `"direct"` (e.g. bookmarked or deep link) | | `search_term` | string | Current search term (if mode is `"search"`). | | `search_location` | string | `"quick"` or `"page"` (if mode is `"search"`). | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"popular_search"`, `"recent_search"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `category` | string | name (if mode is `"category"`). | | `collection` | string | Collection ID (if mode is `"collection"`). | | `widget_rule` | string | Rule ID that generated this view context. | | `widget_rule_type` | string | Type of rule. | | `widget_id` | string | Widget instance ID (if mode is `"widget"`). | | `widget_context_type` | string | Entity type for context. | | `widget_context_data` | string | Additional context payload. | | `mode_details` | object | Nested object repeating the above fields specific to the chosen `mode`. | | `product_option` | array of objects | Selected product options, each `{ name: , value: }`. | | `product_categories` | array of objects | Category hierarchy for this product, each `{ id, name, provider_id }`. | | `facets` | array | Active filters when navigating to the product (each `{ field, value }`). | | `request_id` | string | Unique identifier | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // Data after user selects a new variant: const sku = 'PROD-001'; const variantSku = 'PROD-001-BLUE'; const name = 'Performance Jacket'; const mode = 'search'; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) const modeDetails = { search_term: 'jack', search_location: 'page', used_suggestion: 'jacket', search_source: 'search_suggestion', category: null, collection: null, widget_rule: 'rule42', widget_rule_type: 'personalization', widget_id: null, widget_context_type: 'search', widget_context_data: '', facets: facets, request_id: requestId, page_depth: currentPage }; const productOptions = [{ name: 'Size', value: 'M' }]; const productCategory = [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }]; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) ExpAnalyticsService.trackProductVariantViewed({ sku, variant_sku: variantSku, name, mode, mode_details: modeDetails, product_option: productOptions, product_categories: productCategory, }); ``` # Product Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/product_viewed ## Product Viewed (`product_viewed`) **Purpose:** Track when a user views a product detail page or uses a quick-view from a product listing cell. **When to Fire:** Immediately upon rendering the full product page or opening a quick-view modal for a specific SKU. **Payload Schema:** | Field | Type | Description | | --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | `sku` | string | The SKU of the product being viewed. | | `variant_sku` | string | The SKU of the selected variant (if any); otherwise the default variant SKU. | | `name` | string | Product name. | | `mode` | string | Where the view originated: | |    | | – `"widget"` | |    | | – `"search"` | |    | | – `"category"` | |    | | – `"collection"` | |    | | – `"direct"` (e.g. bookmarked or deep link) | | `search_term` | string | Current search term (if mode is `"search"`). | | `search_location` | string | `"quick"` or `"page"` (if mode is `"search"`). | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"popular_search"`, `"recent_search"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `category` | string | name (if mode is `"category"`). | | `collection` | string | Collection ID (if mode is `"collection"`). | | `widget_rule` | string | Rule ID that generated this view context. | | `widget_rule_type` | string | Type of rule. | | `widget_id` | string | Widget instance ID (if mode is `"widget"`). | | `widget_context_type` | string | Entity type for context. | | `widget_context_data` | string | Additional context payload. | | `mode_details` | object | Nested object repeating the above fields specific to the chosen `mode`. | | `product_option` | array of objects | Selected product options, each `{ name: , value: }`. | | `product_categories` | array of objects | Category hierarchy for this product, each `{ id, name, provider_id }`. | | `facets` | array | Active filters when navigating to the product (each `{ field, value }`). | | `request_id` | string | Unique identifier | | `page_depth` | string | Current page number (1, 2, 3, etc.). | **Example:** ```js theme={null} // Data from your page or quick-view context: const sku = 'PROD-001'; const variantSku = 'PROD-001-BLUE'; const name = 'Performance Jacket'; const mode = 'search'; const facets = []; const requestId = 'request id'; const currentPage = 1; // Current page number (1, 2, 3, etc.) const modeDetails = { search_term: 'jack', search_location: 'page', used_suggestion: 'jacket', search_source: 'search_suggestion', category: null, collection: null, widget_rule: 'rule42', widget_rule_type: 'personalization', widget_id: null, widget_context_type: 'search', widget_context_data: '', facets: facets, request_id: requestId, page_depth: currentPage }; const productOptions = [{ name: 'Size', value: 'M' }]; const productCategory = [{ id: 'apparel', name: 'Apparel', provider_id: 'prov1' }]; ExpAnalyticsService.trackProductViewed({ sku, variant_sku: variantSku, name, mode, mode_details: modeDetails, product_option: productOptions, product_categories: productCategory, }); ``` # Products Searched Source: https://help.experro.com/analytics_sdk/builtin_events/products_searched ## Products Searched (`product_searched`) **Purpose:** Track whenever a user performs a search either from the header search bar or the on‑page search interface. **When to Fire:** After you receive the search API response, immediately log how many results were returned along with contextual details (search term, location, filters, etc.). **Payload Schema:** | Field | Type | Description | | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | | `search_location` | string | Either `"quick"` (header autocomplete) or `"page"`. | | `search_term` | string | The text the user searched for. | | `no_of_results` | number | Total number of search results (`searchResponse.Data.total_count`). | | `sku` | array of strings | Flat array of all result SKUs. | | `search_source` | string | For suggestion clicks, pass the autocomplete category key from the response (e.g., `"popular_search"`, `"recent_search"`). | | `used_suggestion` | string | The exact suggestion text the user clicked (e.g., "shirts", "jeans"). | | `facets` | array of objects | Active filters, each `{ field: , value: }`. | | `request_id` | string | Unique identifier for the search request (x-request-id from response headers). | | `page_depth` | string | Current page number (1, 2, 3, etc.). | #### Clarification: autocomplete suggestions * `search_source`: set this to the suggestion category key returned by your autocomplete API for the clicked item (e.g., `"popular_search"`, `"recent_search"`, `"category"`, `"search_suggestion"`, etc.). * `used_suggestion`: set this to the exact suggestion text the user clicked (e.g., `"shirts"`, `"jeans"`). **Example:** ```js theme={null} // Assume these variables are populated from your search response and UI state: const totalCount = searchResponse.Data.total_count; const searchTerm = 'running shoes'; const searchLocation = 'page'; // or 'quick' const products = searchResponse.Data.records; const selectedFacets = [{ field: 'size', value: '10' }, { field: 'brand', value: 'BrandX' }]; const requestId = searchResponse.headers.get('x-request-id'); const currentPage = 1; // Current page number (1, 2, 3, etc.) ExpAnalyticsService.trackProductSearched({ search_location: searchLocation, search_term: searchTerm, no_of_results: totalCount, sku: products.map(item => item.sku), search_source: searchSource, used_suggestion: usedSuggestion, facets: selectedFacets, request_id: requestId, page_depth: currentPage }); ``` # Widget Viewed Source: https://help.experro.com/analytics_sdk/builtin_events/widget_viewed ## Widget Viewed (`widget_viewed`) **Purpose:** Track when a recommendation widget is rendered, capturing both the number of items displayed and contextual rule and algorithm metadata. **When to Fire:** After your widget API loads its data and before rendering the widget on the page. **Payload Schema:** | Field | Type | Description | | --------------------- | ---------------- | ------------------------------------------------------------------------------ | | `no_of_results` | number | Total number of items in the widget (`widgetData.Data.total_count`). | | `products_detail` | array of objects | List of product objects, each containing: | |  – `sku` | string | Product SKU. | |  – `product_category` | array of objects | Category hierarchy, each `{ id, name, provider_id }`. | | `rule` | string | Overall rule ID (`rule_details.rule_id`). | | `rule_type` | string | Overall rule type (`rule_details.rule_type`). | | `widget_id` | string | Overall widget ID (`rule_details.widget_id`). | | `context_type` | string | Overall context type (`rule_details.context_type`). | | `context_data` | string | Overall context data (`rule_details.context_data`). | | `page_type` | string | Page type where widget appears (e.g. `"web_page"`, `"product"`, `"category"`). | | `page_meta_id` | string | Page metadata ID (e.g. `page.content_model_data_id`). | | `page_display_name` | string | Page display name (e.g. `page.title`). | **Example:** ```js theme={null} // After fetching widget data: const widgetData = { Data: { total_count: 2, items: [ { sku: 'ABC123', name: 'Sneakers Pro', price: 79.99, brand: 'FitBrand', product_category: [ { id: 'cat1', name: 'Shoes', provider_id: 'prov1' } ], }, // …other items ], rule_details: { rule_id: "ABC", rule_name: "Global Rule for All Instances", rule_type: "global", algorithm: "popular_items", widget_id: "ABC123", context_type: "global", context_data: "", } } }; const products = widgetData.Data.items; const themeCurrency = 'USD'; const pageType = 'product'; const pageMetaId = 'P123'; const pageTitle = 'Sneakers Pro'; ExpAnalyticsService.trackWidgetViewed({ no_of_results: widgetData.Data.total_count, products_detail: products.map(item => ({ sku: item.sku, product_category: item.product_category, })), rule: widgetData.rule_details.rule_id, rule_type: widgetData.rule_details.rule_type, widget_id: widgetData.rule_details.widget_id, context_type: widgetData.rule_details.context_type, context_data: widgetData.rule_details.context_data, category: widgetData.rule_details.category, page_type: pageType, page_meta_id: pageMetaId, page_display_name: pageDisplayName, }); ``` # Installation Source: https://help.experro.com/analytics_sdk/installation ## Include the SDK Add the following ` ``` Once the script is loaded and ready, it dispatches an `exp-analytics-loaded` event on both the `document` and `window` objects. You can listen to this event to begin tracking analytics events. ```javascript theme={null} document.addEventListener('exp-analytics-loaded', function() { console.log('Experro Analytics SDK is ready!'); // Proceed with initialization or tracking }); ``` - Placing it in `` ensures tracking begins as soon as possible.

- If you’re concerned about page‑render performance, you can move it just before ``, but make sure your initialization code runs after the script has loaded. ## Prerequisites Before initializing the SDK, you’ll need the following from the Experro admin panel: * **Tenant ID** (`tenantId`) Your unique identifier for billing and data partitioning. * **Workspace ID** (`workspaceId`) Choose or create a workspace to segment events by functional area. * **Environment ID** (`environmentId`) Use distinct values (e.g. `dev`, `staging`, `prod`) to isolate test data from production. * **Channel ID** (`channelId`) Typically `"web"`, but you can define custom channels (e.g. `"mobile-web"`, `"kiosk-app"`). * **Language / Locale** (`language`) A locale code (e.g. `"en-US"`, `"fr-FR"`) to help you segment by user region. Make sure you have these five values handy in your application’s configuration before moving on to next step. # Manual Event Logging Source: https://help.experro.com/analytics_sdk/manual_events For interactions or data points beyond the built‑ins (sessions, links, orientation), use the **Manual Events API** to push any custom event to Experro Analytics. ## Pushing an Event If you need to track custom events, call the following snippet after listening to the `exp-analytics-loaded` event: ```js theme={null} ExpAnalyticsService.trackEvent({ event_name: "Event Name", // String: your custom event key count: count, // Number: integer occurrences sum: sum, // Number: numeric value to aggregate (default 0) dur: dur, // Number: duration in seconds (default 0) event_data: eventData // Object: arbitrary key/value pairs }); ``` * **`event_name`** A unique string identifier for your event (e.g. `"product_clicked"`, `"checkout_started"`). * **`count`** How many times this event should be counted (often `1` for discrete actions). * **`sum`** A numeric value to aggregate—useful for revenue, scores, or any measurable metric. * **`dur`** Duration in seconds—track time‑on‑task, video playtime, or other time‑based metrics. * **`event_data`** An object of custom dimensions or attributes (strings, numbers, or arrays). For example: ```js theme={null} event_data: { product_id: 'SKU-123', category: 't-shirts', price: 19.99, promo: ['summer_sale', 'vip_user'] } ``` *** ## Example: Tracking a Button Click ```html theme={null} ``` This pushes a single `purchase_initiated` event, increments its count by 1, adds the purchase amount to your `sum` metric, and attaches product details via segmentation. Once you’ve got custom events flowing, you can review them in the Experro Analytics dashboard or proceed to the next section to see our built‑in E‑Commerce and Auth event keys and their expected payloads. # Overview Source: https://help.experro.com/analytics_sdk/overview ### What Is Experro Analytics Pixel? Experro Analytics SDK is a lightweight JavaScript library for capturing user interactions on your website — page views, link clicks, eCommerce actions, authentication events, and any custom events you define — and streaming them in real time to your Experro Analytics service for reporting and insights. It’s a self‑hosted, tenant‑scoped solution that gives you full control over your data pipeline and event schema. ### Key Concepts * **Tenant ID** Every organization in Experro Analytics is scoped under a tenant. The `tenantId` you pass to the SDK determines which account your events are billed to and which workspace configurations apply. * **Workspace ID** A tenant can host multiple workspaces (for example, “Shopping”, “Blog”, “Support”). The `workspaceId` enables you to segment events by area, with independent dashboards and settings. * **Environment ID** Use separate `environmentId`s (for example, “dev”, “staging”, “prod”) so that development‑time events don’t mix with your production analytics. * **Channel ID** A channel represents the delivery medium—typically “web” for browser‑based tracking, but you can define other channels (for example, “kiosk‑app”, “mobile‑web”) to split out traffic sources in your reporting. * **Locale / Language** The `language` tag on each event helps you filter or segment your analytics by user locale, useful for internationalized sites. ### How It Works at a High Level 1. **Include the SDK** Add a single script tag pointing to our CDN: ```html theme={null} ``` 2. **Automatic Event Capture** By default, the SDK will: * Begin a new session (`track_sessions`) * Track clicks on `` elements (`track_links`) * Optionally capture device orientation if enabled 3. **Manual Event Logging** Use the `add_event` function to push any custom event with counts, sums, durations, and segmentation to your dashboard. 4. **Payload Delivery** Events are sent immediately (or buffered if offline/batching is enabled), with the appropriate headers (`x-tenant-id`, `x-workspace-id`, etc.) so your backend can authenticate and route them correctly. # Authentication Source: https://help.experro.com/api-reference/authbaseurl Experro uses two authentication models, depending on which part of the API you are calling. This page covers both, how to create an access token, and how to choose the right base URL. ## Authentication Models ### Access token Used by the **Management APIs** and the **Content Delivery APIs**. Every request carries a token plus the identifiers for what you are targeting. | Header | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | `accesstoken` | Your API access token. Create one in the Admin Panel — see [Creating an Access Token](#creating-an-access-token). | | `x-tenant-id` | Identifies your organization. | | `x-workspace-id` | Identifies the workspace within your organization. | | `x-environment-id` | Identifies the environment you are targeting. | ### Storefront headers Used by the **Discovery APIs**. These endpoints are designed to be called directly from your storefront's browser code, so they identify you with headers instead of a token. | Header | Description | | ------------------ | -------------------------------------------------- | | `x-tenant-id` | Identifies your organization. | | `x-workspace-id` | Identifies the workspace within your organization. | | `x-environment-id` | Identifies the environment you are targeting. | ## Which API Uses Which | API | Access token | Headers | | ------------------ | ------------ | --------------------------------------------------- | | Content Management | Required | `x-tenant-id`, `x-workspace-id`, `x-environment-id` | | Content Delivery | Required | `x-tenant-id`, `x-workspace-id`, `x-environment-id` | | Discovery | Not required | `x-tenant-id`, `x-workspace-id`, `x-environment-id` | | Forms | Not required | None | ## Creating an Access Token You need administrator privileges in the Experro Admin Panel to create and manage tokens. 1. **Log in** to the Experro Admin Panel. 2. Go to **Workspace Settings → API & CLI Tokens**. 3. The **API Tokens** tab is selected by default. API Tokens Screen Then create the token: 1. Click **Create Token**. 2. Fill in: * **Name (required):** Descriptive name for your app or integration. * **Description (optional):** Purpose of the token. * **Permissions (required):** *Read-Only* (GET only) or *Full Access* (GET, POST, PUT, DELETE). * **Expiration (optional):** Expiry date. Leave blank for no expiry. 3. Click **Save**. 4. **Copy** or **download** the token when prompted. 5. Click **Done**. Create API Token Dialog The token value is shown **only once**. Copy or download it immediately. ### Viewing Existing Tokens The **API Tokens** screen lists every token with its **Token Name**, **Created By**, **Created At**, **Permissions**, and **Expiration**. A blank expiration means the token never expires. ## Finding Your Header Values | Value | Where to find it | | ------------------ | ------------------------------------------------------------------------- | | `x-tenant-id` | In the token file you downloaded, as **Tenant ID**. | | `x-workspace-id` | In the token file you downloaded, as **Workspace ID**. | | `x-environment-id` | **Workspace Settings → Channels**, in the **ID** column for your channel. | ## Base URLs Which base URL you use depends on the API. ### Management and Content Delivery APIs Always use the Experro-hosted domain: ``` https://apis.experro.app/{service}/{version}/... ``` **Examples** ``` https://apis.experro.app/content/v2/content-models https://apis.experro.app/content/v2/records ``` ### Discovery APIs Call these on your storefront domain: ``` https://{base-address}/discovery/... ``` To find the base address: 1. Go to **Workspace Settings → Channels**. 2. Open **Channel Settings**. 3. Go to the **Languages** tab. 4. Copy the URL from **Language URLs** that matches the language and environment you need. Until you have pointed your custom domain, use the Experro-hosted domain. Once your own domain is configured both will work, but we strongly recommend your custom domain for production. # Get All Assets Source: https://help.experro.com/api-reference/content-delivery/get-all-assets/get GET /assets/v2 Retrieve a paginated list of all media assets (images, videos, documents, etc.) stored in your workspace. Use sorting, pagination, and locale options to tailor the response according to your requirement. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Asset By Id Source: https://help.experro.com/api-reference/content-delivery/get-asset-by-id/get GET /assets/v2/{id} Fetch detailed metadata for one media asset by its unique ID. This allows you to access detailed information about a specific asset by providing its unique asset ID. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Model Detail By Id Source: https://help.experro.com/api-reference/content-delivery/get-model-detail-by-id/get GET /content/v2/content-models/{id} Fetch detailed metadata and field definitions for one content model by its unique ID. Ideal for dynamically generating forms, UIs, or validating data against the model schema. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Model Detail By Internal Name Source: https://help.experro.com/api-reference/content-delivery/get-model-detail-by-internal-name/get GET /content/v2/content-models/by_internal_name/{modelInternalName} Retrieve the full definition and metadata of a content model by its internal name. Use this when you know the model’s identifier and you need to access field definitions and other properties associated with the content model using this endpoint. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Models List Source: https://help.experro.com/api-reference/content-delivery/get-models-list/get GET /content/v2/content-models Retrieve a complete list of every content model defined in your workspace. Content models define the structure and fields of your content types (e.g. blog posts, products, landing pages). Use the optional `locale` parameter to fetch localized model definitions. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Record By Id Source: https://help.experro.com/api-reference/content-delivery/get-record-by-id/get GET /content/v2/content-models/{modelInternalName}/records/{recordId} Fetch detailed information for one record in the specified content model by its unique ID. Supports field selection, localization, and optional metadata for each field. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Search Records Source: https://help.experro.com/api-reference/content-delivery/search-records/get GET /content/v2/content-models/{modelInternalName}/records Retrieve records from a specific content model using advanced filtering, sorting, and pagination. Ideal for tailored content queries in dynamic UIs. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Search Records Source: https://help.experro.com/api-reference/content-delivery/search-records/post POST /content/v2/content-models/{modelInternalName}/records/search Perform an advanced search on a content model’s records using structured filter groups, sorting, pagination, and localization. Ideal for UIs that need dynamic, multi-criteria record retrieval. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Add Record Source: https://help.experro.com/api-reference/content-management/create-record/post POST /content/v2/content-models/{modelInternalName}/records Create a new record for a content model with this API. It allows you to specify details like title, page slug (if the content model has 'act_as_web_page' enabled), version data, and relation fields. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Delete Records Source: https://help.experro.com/api-reference/content-management/delete-records/delete DELETE /content/v2/content-models/{modelInternalName}/records Remove one or more records by their IDs from the specified content model. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Publish Record Source: https://help.experro.com/api-reference/content-management/publish-record/patch PATCH /content/v2/content-models/{modelInternalName}/records/{contentModelDataId}/versions/publish Publish one or more versions of a content record to specified environments. Provide mappings of environment IDs to version IDs. Returns lists of which verson publish succeeded or failed. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Unpublish Record Source: https://help.experro.com/api-reference/content-management/unpublish-record/patch PATCH /content/v2/content-models/{modelInternalName}/records/{contentModelDataId}/versions/unpublish Remove one or more versions of a content record from specified environments. Supply mappings of environment IDs to version IDs to unpublish. Returns lists of successfully unpublished and failed version IDs. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Update Record Source: https://help.experro.com/api-reference/content-management/update-record/patch PATCH /content/v2/content-models/{modelInternalName}/records/{contentModelDataId}/versions/{versionId} Apply partial updates to specific fields of a given record version. Use this to modify draft or published content — set `is_force_update=true` to overwrite the live version directly Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Auto-Suggestions Source: https://help.experro.com/api-reference/discovery/auto-suggestions/get GET /discovery/search/auto-suggestions Returns typeahead term suggestions for a partial query, with optional auto-spell-correction and a "did you mean" list. If `catalog_id` parses as a UUID, terms configured as autocomplete exclusions for that catalog are filtered out. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). Use this for typeahead as the shopper types. To run the actual product search, use [Search Products](/api-reference/discovery/search/post). # Overview Source: https://help.experro.com/api-reference/discovery/autocomplete/overview Four endpoints that populate the search box before and while a shopper types. Each one answers a different question, and a typical search box uses more than one. None of these run a product search. They return terms and categories to show as suggestions. Once the shopper picks one, call [Search Products](/api-reference/discovery/search/post) to fetch the actual results. ## When to Call Each **Before the shopper types** — the search box is empty and you want to fill the dropdown: * [Popular Terms](/api-reference/discovery/popular-terms/get) gives you the catalog's trending searches. They are precomputed, so there is no query to pass — the same ranked list comes back every time. * [Recent Searches](/api-reference/discovery/recent-searches/get) gives you what this particular shopper searched for before, keyed on `user_id`. **While the shopper types** — you have a partial query and want to complete it: * [Auto-Suggestions](/api-reference/discovery/auto-suggestions/get) completes the term itself, and can also return "did you mean" alternatives when the query looks misspelled. * [Categories](/api-reference/discovery/categories/get) finds matching categories, so you can offer "jump straight to Men's Shoes" alongside the term suggestions. ## Endpoints | Endpoint | Route | Returns | Use it for | | ----------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------- | | [Auto-Suggestions](/api-reference/discovery/auto-suggestions/get) | `GET /discovery/search/auto-suggestions` | `terms` and `did_you_mean`, both arrays of strings | Completing a partial query, with optional spell correction | | [Categories](/api-reference/discovery/categories/get) | `GET /discovery/search/categories` | `categories` with an id, name, and URL for each, plus `total_count` | Linking a query straight to a category page | | [Popular Terms](/api-reference/discovery/popular-terms/get) | `GET /discovery/search/popular-terms` | An array of terms, most popular first | Filling an empty search box | | [Recent Searches](/api-reference/discovery/recent-searches/get) | `GET /discovery/search/recent-searches` | An array of the shopper's previous terms | Letting a returning shopper repeat a search | All four take `catalog_id` and support `limit` and `skip`. Auto-Suggestions and Categories also take `q`, which is required on Categories. # Categories Source: https://help.experro.com/api-reference/discovery/categories/get GET /discovery/search/categories Returns catalog categories matching a text query, typically used to power a category autocomplete or typeahead UI. Categories configured as autocomplete exclusions in the catalog's search settings are automatically excluded. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). Use this to power a category typeahead. For term suggestions, use [Auto-Suggestions](/api-reference/discovery/auto-suggestions/get); for the product search itself, use [Search Products](/api-reference/discovery/search/post). # Content Search Source: https://help.experro.com/api-reference/discovery/content/get GET /discovery/search/content Searches non-product content indexed for the catalog — CMS pages, articles, blog posts, and similar — with an optional content-type filter. Returns a different result shape than product search: title, URL, image, and summary rather than price, SKU, and inventory. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). This searches CMS content rather than products, so the result shape differs — title, URL, image, and summary instead of price, SKU, and inventory. For products, use [Search Products](/api-reference/discovery/search/post). # Overview Source: https://help.experro.com/api-reference/discovery/content/overview Search over non-product content indexed for the catalog — CMS pages, articles, blog posts, and similar — with an optional content-type filter and sorting by relevance, date, author, or title. The result shape differs from product search: title, URL, image, and summary rather than price, SKU, and inventory. For products, use [Search Products](/api-reference/discovery/search/post). | Method | Route | Endpoint | | ------ | --------------------------- | ------------------------------------------------------ | | `GET` | `/discovery/search/content` | [Content Search](/api-reference/discovery/content/get) | # Popular Terms Source: https://help.experro.com/api-reference/discovery/popular-terms/get GET /discovery/search/popular-terms Returns the catalog's top popular or trending search terms, for a "popular searches" list on an empty search box. The terms are precomputed for the catalog, so this endpoint does not take a query — it always returns the same ranked list, paged with `limit` and `skip`. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). Use this to fill a "popular searches" list before the shopper types anything. # Recent Searches Source: https://help.experro.com/api-reference/discovery/recent-searches/get GET /discovery/search/recent-searches Returns recent search terms for a given shopper within a catalog. The result count is capped at 50 server-side regardless of the requested `limit`. This is the only Search endpoint that identifies the shopper with a query parameter rather than a header. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). This is the only Search endpoint that identifies the shopper with a query parameter (`user_id`) rather than a header. Results are capped at 50 regardless of `limit`. # Search Products Source: https://help.experro.com/api-reference/discovery/search/get GET /discovery/search Query-string form of product search. Returns the matching products, along with facets, banners, and result metadata. Every parameter goes in the query string. Structured fields such as `facets` and `filters` must be JSON-encoded; a malformed value is silently ignored rather than rejected. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). Structured fields such as `facets` and `filters` must be JSON-encoded into the query string; a malformed value is silently ignored rather than rejected, so an encoding mistake looks like the parameter having no effect. To send them as real JSON, use [Search Products (POST)](/api-reference/discovery/search/post). # Overview Source: https://help.experro.com/api-reference/discovery/search/overview Product search over a catalog. Returns the matching products, along with facets, banners, and result metadata. Search is available as two endpoints, `POST /discovery/search` and `GET /discovery/search`. Both take the same parameters and return the same response. Use POST to send `facets`, `filters`, and other structured fields as real JSON. On GET those same fields must be JSON-encoded into the query string. | Method | Route | Endpoint | | ------ | ------------------- | ------------------------------------------------------- | | `POST` | `/discovery/search` | [Search Products](/api-reference/discovery/search/post) | | `GET` | `/discovery/search` | [Search Products](/api-reference/discovery/search/get) | For non-product content, see [Content Search](/api-reference/discovery/content/overview). # Search Products Source: https://help.experro.com/api-reference/discovery/search/post POST /discovery/search Primary product-search endpoint for the storefront. Returns the matching products, along with facets, banners, and result metadata. Facet filters, structured filters, sorting, pagination, out-of-stock handling, variation-map grouping, and personalization context are all set in the request body. Before calling this endpoint, make sure you've generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). Send `facets`, `filters`, and other structured fields as real JSON here. The [GET variant](/api-reference/discovery/search/get) accepts the same fields but requires them JSON-encoded into the query string. # Get Form By ID Source: https://help.experro.com/api-reference/forms/get-form-by-id/get GET /apis/setting-service/public/v1/forms/{form_id} Fetch the full configuration and metadata for a form, including its fields, layout hierarchy, validation rules, and submission settings. Use this endpoint to dynamically render form UIs or integrate with form builders at runtime. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Get Form List Source: https://help.experro.com/api-reference/forms/get-form-list/get GET /apis/setting-service/public/v1/forms Retrieve a paginated list of forms, with optional field selection, locale translations, search by display name, sorting, and pagination controls. Use this endpoint to build form catalogs or search interfaces. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Submit Form Source: https://help.experro.com/api-reference/forms/submit-form/post POST /apis/setting-service/public/v1/forms/{form_id}/submit Submit user-entered data for the specified form. Supports JSON-stringified form mapping in a multipart request, plus optional file uploads for media fields. Returns submission status and any processing result. Before calling this endpoint, make sure you’ve generated an API token and picked the correct domain. See [Authentication & Base URLs](/api-reference/authbaseurl). # Overview Source: https://help.experro.com/api-reference/introduction Welcome to the Experro API. Our RESTful endpoints let you build, manage, and deliver content and commerce experiences programmatically — whether you're driving a dynamic website, a mobile app, or a headless storefront. The API is organized around two areas: | Area | What it does | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Management APIs** | Author and configure. Model your content, and manage records and assets through their publishing lifecycle. | | **Delivery APIs** | Read at runtime. The public-facing endpoints your storefront calls to run searches, fetch published content, and submit forms. | Management APIs are the configuration side — you use them from your server or build pipeline to decide how things should behave. Delivery APIs are the runtime side, queried on every search and page view. ## What You Can Do ### Management APIs * **Content Management** — Define content types ("models") with fields, relationships, versioning, and localization support. Create, retrieve, update, and delete records, move them through drafts and publishing workflows, and upload and manage media assets with metadata, thumbnails, and secure URLs. ### Delivery APIs * **Discovery** — Faceted product search, autosuggest, category and content search, and popular and recent search terms, returning ranked records with generated facets and banners. * **Content Delivery** — Fetch published records, content models, and assets to render on your front end. * **Forms** — Render forms dynamically and collect user input, complete with file uploads and webhook integrations. ## Getting Help * **API Reference** — Explore each endpoint in this section for parameters, request and response examples, and code snippets. * **Authentication** — Before you call any endpoint, set up your credentials. See [Authentication & Base URLs](/api-reference/authbaseurl). * **Troubleshooting** — Common failures and how to resolve them are covered in [Troubleshooting](/api-reference/troubleshoot). * **Support** — Email [support@experro.com](mailto:support@experro.com) with a description of the issue and the `x-request-id` of a failing call. # Responses & Errors Source: https://help.experro.com/api-reference/responses-errors Every Experro API call returns JSON. This page covers the response shapes you can expect, the error format, and how to report a failing call. ## Responses Most endpoints wrap their result in a consistent envelope: ```json theme={null} { "Status": "success", "Data": { } } ``` The Discovery APIs are the exception — they return their payload at the top level, with no envelope: ```json theme={null} { "records": [], "facets": [], "banners": null, "meta": { "total_count": 206 } } ``` ## Errors Failures use a single error shape: ```json theme={null} { "Status": "failure", "Error": { "code": 400, "message": "Invalid Input", "name": "ValidationError" } } ``` Validation failures may include an additional `Details` field alongside `Error`, describing which field failed and why. | Status | `name` | When it happens | | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------- | | 400 | `ValidationError` | The request body is missing, is not valid JSON, or a field has the wrong type or a blank value. | | 400 | `QueryParseError` | A query parameter is missing or malformed — for example a `catalog_id` that is not a valid UUID. | | 401 | `Unauthorized` | Your access token is missing, invalid, or expired. | | 403 | `Forbidden` | The request is not permitted for the given scope. | | 404 | `NotFound` | The resource does not exist in your tenant, workspace, and environment. | | 409 | `Conflict` | The request conflicts with existing state — for example a duplicate identifier or an already-active resource. | | 500 | `InternalServerError` | An unexpected error occurred. | The two `400` variants are worth telling apart: `ValidationError` points at the request body, `QueryParseError` at the query string. ### Common Causes of `ValidationError` A `400 Invalid Input` almost always means the request body could not be read, rather than a bad field value. Check for: * A missing `Content-Type` header, or one that is not `application/json`. * A body sent as form data instead of raw JSON. * An empty body. Endpoints that take a body require one — send `{}` if you have no fields to set. * An optional field sent **blank rather than omitted**, such as `"sort_order": ""` or `"filters": [{}]`. Omit the field, or send `null` or `[]`. * A numeric field sent as a string, such as `"limit": "24"` instead of `"limit": 24`. # Troubleshooting & Best Practices Source: https://help.experro.com/api-reference/troubleshoot After you’ve set up authentication and chosen the correct domain, these tips will help ensure smooth integration and optimal performance. Experro automatically caches responses at the edge. If you suspect stale data: 1. **Check the `CDN-Cache` response header** * `HIT` → Response served from cache * `MISS` → Response fetched fresh from the origin 2. **Force a cache purge**\ In the Experro Admin Panel, navigate to **Workspace Settings → Cache**, and clear the relevant endpoint or entire cache. For more on caching controls, see the [Cache guide](/content/caching/cache_webpages). The old `x-lang` header has been removed. Instead, specify localization per request via the `locale` **query parameter**: | Parameter | In | Description | | --------- | ----- | ------------------------------------------ | | `locale` | query | Language or region code for response data. | The relevant details are available in the API Documentation for each endpoint wherever applicable Many Delivery APIs offer both `GET` and `POST` variants for full‑text or filtered queries. Our recommendation: * **Use `GET`** whenever your query parameters stay under \~1 KB in total length. * **Switch to `POST`** if your query string (filters, facets, etc.) exceeds \~1 KB to avoid URL length limits in browsers or proxies. • Verify no extra spaces or line breaks were copied.\ • Check if the token has expired in the Admin Panel. • Ensure you selected **Full Access** for write operations.\ • For read‑only calls, confirm **Read‑Only** scope is sufficient. • Tokens cannot be retrieved once created—delete the old one and generate a new token.\ • Update all clients to use the new token immediately. **Still stuck?** Reach out to [Support](https://www.experro.com/contact-us/) with your tenant ID and a description of the issue, and we’ll be happy to assist. # Audit Logs Source: https://help.experro.com/configurations/admin_settings/audit_logs The **Audit Logs** page under **Account Admin** provides a comprehensive record of key events across all workspaces. Use this page to track changes, investigate issues, and meet compliance requirements by filtering and reviewing who did what, where, and when. ### What You Can Do on This Page * **Filter Events** Narrow down the log entries by: * **Workspace**: Select one or more workspaces to scope your view. * **User**: Choose specific users whose actions you want to audit. * **Environment**: Filter by environment (e.g., Development, Staging, Production). * **Timeline**: Pick a date range to focus on a particular period. * **Review Log Entries** See each recorded event in reverse-chronological order, with details about the user, event, module affected, workspace, and timestamp. #### Filtering Your View 1. **Workspace Filter** – Click the dropdown to pick one or more workspaces. 2. **User Filter** – Select users from the list. You can search by name or email. 3. **Environment Filter** – Choose the environment(s) where the events occurred. 4. **Timeline Filter** – Use the date picker to set a start and end date. By regularly reviewing your audit logs, you can maintain visibility into system activity, troubleshoot configuration changes, and ensure that your Experro environment remains secure and compliant. # Billing Source: https://help.experro.com/configurations/admin_settings/billing The **Billing** page under **Account Admin** is where you configure the payment and invoicing information used across all your Experro subscriptions. It consists of two tabs—**Billing Details** and **Card Details**—to collect your organization’s billing address and payment method. ## What You Can Do on This Page * **Enter or Update Billing Information** Provide the contact and address details that will appear on your invoices. * **Manage Payment Method** Securely add or update your credit/debit card for automated payments. ## Billing Details Tab Enter the company and contact information that appears on each invoice: | Field | Description | | ---------------- | ---------------------------------------------------------------- | | **First Name** | Billing contact’s first name. | | **Last Name** | Billing contact’s last name. | | **Email** | Email address to receive invoice PDFs and payment notifications. | | **Mobile** | Phone number for billing inquiries or payment confirmations. | | **Company Name** | Legal or trading name to display on invoices. | | **Address** | Street address, PO Box, or suite information. | | **Country** | Select the billing country. | | **State** | State, province, or region. | | **City** | City or locality. | | **Post Code** | Postal or ZIP code. | Click **Save** to persist any changes.These details will be used for all future invoices. ## Card Details Tab Securely add or update your payment card details for automated billing. All card information is encrypted in transit. Experro does **NOT** store raw card data on its servers. After entering your card details, click **Save**. Your card will then be charged automatically according to your subscription’s billing cycle. # Connect Domain Source: https://help.experro.com/configurations/admin_settings/connect_domain The **Connect Domain** page lets you map verified domains to specific workspace channels and languages. ## What You Can Do on This Page * **View Connected Domains** See all domain-to-channel mappings currently in use, including their base URLs and suffixes. * **Connect a New Domain** Click **Connect Domain**, then follow the form to bind a verified domain to a workspace channel and language. * **Disconnect Domains** Use the **Delete** action to remove mappings you no longer need. ### Connecting a Domain 1. **Select Workspace** Choose which workspace this domain mapping applies to. 2. **Enter Base URL** The foundational portion of the domain, typically your verified domain (e.g., `store.myexperro.com`). 3. **Choose Domain** Pick from the list of **Verified Domains** you added on the **Domain** page. 4. **Set URL Suffix** Define the path or subdirectory suffix (e.g., `/en-us`, `/ca`). This combined with the base URL creates the full storefront URL. 5. **Click Connect Domain** Save the mapping. The new entry appears in your list of connected domains. By completing these steps, you ensure that your custom domains are properly registered, verified, and routed to the correct storefront channels. # Domains Source: https://help.experro.com/configurations/admin_settings/domains The **Domains** page under **Account Admin** lets you register and verify custom domains that you’ll later map to storefront channels. ## What You Can Do on This Page * **View Registered Domains** See a list of all domains you’ve added to Experro, along with their verification status. * **Add a New Domain** Click **Add Domain**, enter your domain name (e.g., `shop.example.com`), and save. * **Verify DNS Settings** After adding, follow the on-screen prompt to configure your DNS and verify ownership. * **Manage Domains** Use **Verify**, **Verify Later**, or **Delete** to update or remove domains. ## Adding & Verifying a Domain 1. **Enter Domain Name and Click Add Domain** Opens a modal to verify your new domain name. 2. **Copy CNAME Record** Copy the CNAME record into your DNS configuration for experro.com 3. **Verify or Defer** * **Verify**: Attempts DNS lookup and, on success, marks the domain as verified. * **Verify Later**: Saves the domain but leaves it unverified until you return. * **Delete Domain**: Removes the entry completely. # Edit Profile Source: https://help.experro.com/configurations/admin_settings/edit_profile The **Edit Profile** page allows each user to view and update their personal settings and preferences. Changes made here will affect how you appear across the workspace and how data is displayed in your UI and reports. ## What You Can Do on This Page * **Update Your Avatar** Click the pencil icon on your profile picture to upload or change your avatar. * **Verify Your Email** View (but not edit) the email address you use to log in. * **Edit Your Name** Update your first and last name to ensure proper identification in notifications and user lists. * **Set Your Timezone** Choose your local timezone—this setting drives all timestamps and scheduling in reports, dashboards, and analytics widgets. * **Choose Your Interface Language** Select the language in which the UI is displayed. Once you’ve made changes, click **Save** to apply them. After saving, your updated profile information will be reflected immediately across the Experro platform. # Groups Source: https://help.experro.com/configurations/admin_settings/groups The **Groups** page under **Account Admin** lets you organize related roles into named collections, making it easier to assign multiple permissions to users at once. Rather than assigning individual roles one by one, you can bundle frequently used role sets into a group and grant that group to any user. ## What You Can Do on This Page * **Browse Existing Groups** View all groups you’ve created, along with the number of users assigned to each. * **Inspect Group Membership** Hover over the **Users** count to see which users belong to that group. * **Edit, Clone, or Delete** Use the **Actions** menu to update a group’s name, description, roles, or membership; duplicate it to create a similar group; or remove it entirely (only if no users depend on it). * **Create New Groups** Click **Add Group** to bundle roles and users into a new group for streamlined assignment. ## Adding a New Group 1. **Click Add Group** 2. **Specify Group Details** * **Group Name**: Enter a clear, descriptive name. * **Description**: Summarize what this group represents. 3. **Assign Roles** * Select one or more roles from the list to bundle into this group. 4. **Select Users** * Choose which existing global users should belong to this group. (You can always add or remove users later.) 5. **Save** * Click **Save** to create the group. It will appear immediately in the group list. Using groups streamlines permission management by allowing you to assign a set of roles to many users in a single action, ensuring consistency and reducing administrative overhead. # Introduction Source: https://help.experro.com/configurations/admin_settings/introduction ## Setup View and manage all your Experro workspaces in one place. Create, edit, or delete workspaces, and see key metrics like channels, languages, and users at a glance. ## Profile Settings Update your personal settings: avatar, name, timezone, and interface language to personalize your Experro experience. Change your password and configure two-factor authentication via email or authenticator app to secure your account. ## Security Invite and manage all users across your Experro instance. Edit profiles, reset passwords, block/unblock, or delete users globally. Define permission sets that apply globally or to individual workspaces. Edit, clone, or delete roles, and view assigned users. Bundle related roles into groups for streamlined assignment. Create, edit, clone, or delete groups and view group membership. Track every system event across workspaces. Filter by workspace, user, environment, and timeline to investigate changes and maintain compliance. ## Domain Manager Register and verify custom domains. Copy the required CNAME record, verify ownership, or delete domains as needed. Map verified domains to specific workspace channels and languages by selecting a workspace, base URL, domain, and URL suffix. ## Billing & Usage View active subscriptions, billing amounts, last payment dates, and expiry. Manage plans or make payments directly from the page. Browse all generated invoices with number, date, amount, and status. Download PDF copies for accounting and record-keeping. Enter your billing contact and address details, and securely add credit/debit card information for automated payments. # Invoices Source: https://help.experro.com/configurations/admin_settings/invoices The **Invoices** page under **Account Admin** provides a centralized list of all billing invoices generated for your Experro subscriptions. Here you can review invoice metadata and download PDF copies for your records. ## What You Can Do on This Page * **Browse Invoice Records** View every invoice issued to your organization, with key details displayed in a sortable table. * **Download PDF Invoices** Click the **Download** action to retrieve a PDF version suitable for accounting or tax purposes. ## Invoice Details | Field | Description | | ------------------ | -------------------------------------------------------------------------- | | **Invoice Number** | Unique identifier assigned to each invoice (e.g., EXP-2025-000123). | | **Date** | The date the invoice was generate. | | **Amount** | Total billed amount, including currency (e.g., \$1,200.00 USD). | | **Status** | Indicates payment status. | | **Action** | - **Download PDF**: Retrieves the official invoice document in PDF format. | By keeping all invoices accessible in one place, you can streamline your financial reconciliation and ensure you always have the necessary documentation for your accounting and compliance needs. # Roles Source: https://help.experro.com/configurations/admin_settings/roles The **Roles** page under **Account Admin → Global Settings** lets you define and manage permission sets that apply across your entire Experro instance or within specific workspaces. Use this page to see which roles exist where, who’s assigned to them, and to create or modify roles at the global level. ### What You Can Do on This Page * **Browse All Roles** View every role defined globally or per workspace, with an indication of where each applies. * **See Assigned Users** In the **Users** column, hover or click to list which users hold that role. * **Edit, Clone, or Delete Roles** Use the **Actions** menu (⋮) next to a role to update its permissions, duplicate it for fast setup, or remove it entirely (if unused). * **Create New Roles** Define roles that apply globally or restrict them to a single workspace. ### Adding a New Global Role 1. **Click Add Role** 2. **Choose Scope, Global or Workspace** * **Global**: Role is available in every workspace. * **Workspace**: Select one workspace from the dropdown to confine this role’s visibility. 3. **Define Role Details** * **Role Name**: Enter a clear, concise name. * **Description**: Summarize the role’s responsibilities. 4. **Save** Click **Save** to create the role. It will immediately appear in the list under its chosen scope. Your new role can now be assigned to users—either globally or within the selected workspace enabling precise access control across your Experro deployment. # Security Source: https://help.experro.com/configurations/admin_settings/security The **Security** page lets you manage your account’s authentication settings, including changing your password and configuring two-factor authentication (2FA). Navigate between the two tabs—**Change Password** and **Two Factor Authentication**—to adjust your security preferences. ## Change Password Use this tab to update your account password at any time. | Field | Description | | -------------------- | ------------------------------------------------------------------------------------------ | | **Old Password** | Enter your current password to verify your identity. | | **New Password** | Choose a strong new password (recommended: at least 8 characters, mix of letters/numbers). | | **Confirm Password** | Re-enter the new password to ensure there are no typos. | | **Save** | Click to persist your new password. | ## Two Factor Authentication Add an extra layer of security by requiring a second form of verification when logging in. | Field / Control | Description | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Enable via Email** | Toggle on to receive a one-time code at your registered email each time you sign in. | | **Enable via Authenticator App** | Toggle on to link an authenticator app (e.g., Google Authenticator, Authy). Scan the displayed QR code to configure. | | **Disable 2FA** | Toggle off and enter your account password to turn off two-factor authentication. | | **Save** | Click to apply changes to your 2FA settings. | Adjust these settings any time to keep your account secure. # Subscription Source: https://help.experro.com/configurations/admin_settings/subscription The **Subscription** page gives you an overview of your current Experro subscriptions, including billing information, renewal dates, and plan management options. ## What You Can Do on This Page * **View Subscription Details** See all the active subscriptions for your workspaces, including: * Subscribed Products * Plan Type * Monthly Price * Yearly Price * Last Payment Date * Plan Expiry Date * **Manage Subscriptions** Click **Manage** next to any workspace subscription to: * Upgrade or downgrade your plan * Add or remove product modules * Update billing cycles or payment methods * **Make Payments** If your subscription has expired or if you've made changes to your current plan, you can initiate payment directly from this screen to activate or renew your subscription. This page helps you keep your workspace access uninterrupted and ensures full visibility into your ongoing billing relationship with Experro. # Users Source: https://help.experro.com/configurations/admin_settings/users The **Users** page under **Account Admin** lets administrators manage all user accounts across your Experro instance i.e., across all the workspaces. Here you can review existing users, adjust their global roles and group memberships, and onboard new team members who can then be assigned to specific workspaces. ## What You Can Do on This Page * **Browse All Users** View every user in the system along with their key details and current assignments. * **Manage User Access** Edit a user’s global roles and group memberships, reset their password, block or unblock them, or delete their account entirely. * **Add New Users** Invite new team members by providing their profile details and assigning them initial roles and groups. ## Field-by-Field Breakdown | Column | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | The user’s full name (First + Last). | | **Email** | The email address they use to log in. | | **Workspace** | Lists the workspaces to which the user already belongs. | | **Roles** | Global role(s) assigned (e.g., Workspace Admin, Super Admin). These roles govern which workspaces they can access and what admin capabilities they have across the system. | | **Groups** | Any user groups they’ve been added to. | | **Status** | Indicates whether the account is **Active**, **Blocked**, or **Invited**. | | **Actions** | - **Edit**: Update name, email, roles, or groups.
- **Reset Password**: Trigger a password reset email.
- **Block/Unblock**: Toggle account access.
- **Delete**: Permanently remove the user. | ### Adding a New User 1. **Click Add User** to open the **Add User** form. 2. **Provide User Details** * **First Name**: Given name. * **Last Name**: Family name. * **Email**: Login address; an invitation email will be sent here. 3. **Assign Global Roles & Groups** * **Roles**: Select one or more roles to define the user’s administrative scope. * **Groups**: Optionally add them to existing user groups for easier bulk management. 4. **Save** Click **Save** to send an invitation email. The user’s status will initially show **Invited** until they accept. Once the user accepts their invitation, they can be added to specific workspaces and granted workspace-level roles as needed. # Workspaces Source: https://help.experro.com/configurations/admin_settings/workspaces The **Workspaces** page under **Account Admin** provides a centralized view of every workspace in your Experro system. From here, you can review the workspaces at a glance, manage existing workspaces, or onboard new ones. ## What You Can Do on This Page * **Browse All Workspaces** See every workspace tile, each summarizing the number of channels, supported languages, and active users. * **Manage a Workspace** Hover over any workspace tile and click the ⋮ icon to access the following options: * **Workspace Settings**: Edit name, timezone, currency, and other core details. * **Delete**: Permanently remove the workspace (irreversible). * **Add a New Workspace** Click **Add Workspace** to launch a flow for provisioning a fresh workspace. ### Workspace Tile Breakdown | Metric | Description | | --------------- | -------------------------------------------------------------------------------------- | | **Channels** | Total storefront channels configured within this workspace. | | **Languages** | Number of locales registered under Internationalization. | | **Users** | Count of active users assigned to this workspace. | | **⋮ (Actions)** | Hover to reveal the three-dot menu with **Workspace Settings** and **Delete** options. | Click the tile itself to enter that workspace’s own **Workspace Settings** section. ## Adding a New Workspace 1. **Click Add Workspace** The **Add Workspace** pop-up appears. 2. **Enter Basic Details** * **Workspace Name**: Unique display name (e.g., “North America Ops”). * **Workspace Timezone**: Select from the dropdown (e.g., UTC+05:30). * **Workspace Type**: Choose a classification (e.g., “CMS”, “APP”). * **Currency**: Set the default currency for billing and reports (e.g., USD, EUR) from the dropdown. 3. **Generate Workspace Link** Click **Next** to automatically generate the workspace’s shareable URL. 4. **Save** Review your settings, then click **Save** to create and provision the new workspace. Your new workspace appears immediately in the global list, ready for channel configuration, user assignment, and integrations. # AI Knowledge Source: https://help.experro.com/configurations/workspace_settings/ai_knowledge The **AI Knowledge** page is where you teach Experro about your storefront’s unique characteristics so that its AI-driven features such as search suggestions, product recommendations, and autocomplete can be fine-tuned for your business. By providing detailed information about your industry, brand, product catalog, and target customers, you enable the platform’s AI model to deliver more accurate, relevant insights. ## What You Can Do on This Page 1. **Specify Your Industry** – Choose the category that best describes your line of business, helping Experro leverage domain-specific language and patterns. 2. **Define Your Brand Identity** – Enter your company name and a succinct brand tone statement so AI suggestions align with your voice and style. 3. **Clarify Your Offerings** – Detail exactly what you sell—and just as importantly, what you don’t sell—to avoid irrelevant recommendations. 4. **Profile Your Customers** – Describe your ideal shoppers, including demographics, interests, and buying behaviors, so AI can tailor product suggestions, messaging, and promotions to them. ### AI Knowledge Settings | Field | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Industry** | Select from the dropdown the sector that most closely matches your business (e.g., “Apparel & Fashion,” “Electronics,” “Home & Garden”). This guides AI in using industry-appropriate terminology. | | **Company Name** | Your official business name (e.g., “Acme Outdoor Supplies”). | | **Business Overview** | A brief summary (2–3 sentences) of your company’s mission, history, and core strengths. Helps the AI contextualize your brand narrative. | | **Brand Tone** | A concise statement of your brand’s voice and tone. | | **What Kind of Products Do You Sell?** | Provide specific details about your catalog (e.g., “We sell camping tents, sleeping bags, and portable stoves designed for lightweight backpacking”). The more precise, the better AI performs. | | **What Do You Not Sell?** | Clarify any product categories you explicitly exclude (e.g., “We do not carry apparel, footwear, or climbing gear”). Ensures AI won’t suggest irrelevant items. | | **Who Are Your Targeted Customers?** | Describe your ideal shopper profiles (e.g., “Outdoor enthusiasts aged 25–45, middle-income, interested in ultralight gear and sustainable products”). Guides AI personalization for promotions. | #### How to Configure 1. **Select Storefront** – Use the dropdown at the top right to pick the channel to which these AI settings should apply. 2. **Complete All Fields** – Ensure every field is filled out with clear, specific information. 3. **Click Save** – Persist your AI knowledge settings. Experro will use this data to train its models and surface better suggestions. # API & CLI Tokens Source: https://help.experro.com/configurations/workspace_settings/api_cli_tokens The **API & CLI Tokens** page lets you manage authentication tokens for both REST API calls and command-line operations. Tokens grant scoped access to your Experro workspace, enabling integrations, scripts, and automation tools to interact with your data securely. ### What You Can Do on This Page 1. **Switch Between Token Types** – Use the **API Tokens** and **CLI Tokens** tabs to view and manage each token category separately. 2. **Review Existing Tokens** – See all active tokens you’ve generated, along with metadata like name, description, permission scope, and expiration date. 3. **Create New Tokens** – Click **Create Token** on the appropriate tab to generate a fresh token for your integrations. 4. **Copy and Store Tokens Securely** – Copy the token value immediately after creation—you won’t be able to view it again. Store it in your secret manager. 5. **Revoke Tokens** – Delete any token that’s no longer needed or that may be compromised to immediately cut off access. ### API Tokens Settings | Field | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | A descriptive label for your token (e.g., “CI/CD Pipeline Token”). Helps you identify its purpose later. | | **Description** | A brief note about where or how this token will be used (e.g., “Used by our internal jobs to deploy dashboards”). | | **Permissions** | Choose **Read Only** (view and list operations) or **Full Access** (create, update, delete). Grant the least privilege needed for your use case. | | **Expiration** | Select a calendar date when the token will automatically expire. Shorter lifespans reduce risk so consider rotating tokens every 30–90 days. | After clicking **Save**, the token string is shown **only once**. Copy it immediately and store it in a secure vault. ### Creating an API Token 1. Navigate to the **API Tokens** tab and click **Create Token**. 2. Fill in **Name**, **Description**, **Permissions**, and **Expiration**. 3. Click **Save**. 4. Copy the generated token value and store it securely; you cannot retrieve it again later. ## CLI Tokens Tab The **CLI Tokens** tab follows the same workflow and fields as **API Tokens**, but generates tokens specifically scoped for use with the Experro CLI tool. Use CLI tokens to develop a theme locally or publish theme using the Experro CLI.. Keep your tokens tightly scoped, rotate them regularly, and revoke any that are no longer in active use to maintain the security of your workspace. # Channels Source: https://help.experro.com/configurations/workspace_settings/channels The **Channels** page is where you manage the distinct storefront channels for your workspace—each channel represents a language- or region-specific entry point to your site. From here, you can review existing channels, create new ones, and perform channel-specific actions like editing settings, deleting channels, or configuring redirects and themes. ## What You Can Do on This Page 1. **Browse Existing Channels** – See every channel you’ve configured, including its code, supported languages, and unique ID. 2. **Create New Channels** – Click **Add Channel** to define a fresh channel, mapping it to one or more languages and setting URL prefixes. 3. **Edit Channel Settings** – Use the **Edit** action to adjust core details, publish themes to different environments, or view theme history. 4. **Manage Redirects** – From **Channel Settings**, add 301 redirects to handle URL changes or route legacy links. 5. **Delete Channels** – Remove channels you no longer need via the **Delete** action in the list (this cannot be undone). ## Field-by-Field Breakdown | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | The human-friendly label for the channel (e.g., “US Storefront”, “French Site”). Visible in the navigation panel and channel selector. | | **Channel Code** | A short identifier (e.g., `us`, `fr`, `ca-en`). Used internally and in URL generation. Must be unique across channels. | | **Languages** | Lists the locale(s) mapped to this channel (e.g., “English – United States”, “Français – France”). These are the languages you added under Internationalization. | | **ID** | The system-generated unique identifier for the channel. This is needed when referring to the channel in API calls or CLI commands. | | **Actions** | - **Edit**: Modify channel name, code, or mapped languages; publish themes; view theme history; configure redirects.
- **Delete**: Permanently remove the channel and its settings. | ## Adding a New Channel 1. Click **Add Channel**. 2. **Enter Basic Details** * **Name**: e.g., “EU Storefront”. * **Channel Code**: e.g., `eu`, `de`, `es`. 3. **Map Languages** * Select a **Language** from the dropdown (populated from your Internationalization settings). * The **Language Code** auto-fills based on your choice. * Enter a **Language URL Prefix** (e.g., `de`, `es`)—this becomes part of the channel’s URLs. * Provide a **Language Label** (e.g., “Deutsch”, “Español”) which visitors will see when switching locales. * Click **Add Language** to map additional locales to the same channel. 4. **Save** the channel via the button at the top of the screen. After saving, your new channel appears in the list, ready to serve content in the mapped languages. # Environments Source: https://help.experro.com/configurations/workspace_settings/environments The **Environments** page lets you view and manage all the deployment environments tied to your current workspace (for example: Development, Staging, Production). From here, you can identify each environment by name and unique ID, and designate which one should serve as the workspace’s default context for running jobs, queries, or automations. ## Environment Settings | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | The human-readable label for the environment (e.g., “Production”, “QA”, “Sandbox”). | | **ID** | A system-generated unique identifier (UUID or numeric) for the environment. | | **Actions** | Contains the **Make Default** button. Clicking **Make Default** will instantly switch the workspace’s default environment to the one in that row. Only one environment can be default at a time. | To designate a new default environment, simply locate the environment you want in the list and click **Make Default** in its Actions column. The UI will instantly update to reflect your new default choice. # GraphQL Source: https://help.experro.com/configurations/workspace_settings/graphql The **GraphQL** page embeds an in-browser GraphiQL tool, giving you an interactive environment to compose, validate, and execute GraphQL queries against your Experro workspace. Rather than manually crafting HTTP requests, you can explore the schema, build queries with auto-completion, and immediately inspect results, all in one place. ## What You Can Do on This Page 1. **Write and Edit Queries** – Use the left pane to author queries. Lines beginning with `#` are treated as comments. 2. **Execute Requests** – Send your query to the server by clicking **Run** (the ▶️ button) or pressing **Ctrl + Enter**. Results appear instantly in the right pane in JSON format. 3. **Format and Compress** – Clean up your query layout with **Prettify** (Shift + Ctrl + P), or condense it into a single line using **Merge** (Shift + Ctrl + M). 4. **Manage Query History** – Revisit past queries via the **History** panel, where you can re-run or copy older requests. 5. **Copy to Clipboard** – Use **Copy** to grab your current query text for sharing or embedding in code. ## Toolbar & Pane Breakdown | UI Element | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Query Editor (Left Pane)** | The text area where you write GraphQL operations. Autocomplete (`Ctrl + Space`) suggests fields and types based on your workspace schema. Comments start with `#`. | | **Results Viewer (Right Pane)** | Displays the JSON response returned by your query. | | **Run** | Executes the current query or mutation. Keyboard shortcut: **Ctrl + Enter**. | | **Prettify** | Reformats your query with consistent indentation and line breaks. Keyboard shortcut: **Shift + Ctrl + P**. | | **Merge** | Removes all extraneous whitespace, condensing your query into a single line. Keyboard shortcut: **Shift + Ctrl + M**. | | **Copy** | Copies the full text of your current query to the clipboard. | | **History** | Opens a panel listing previously executed queries. Click an entry to load it back into the editor. | With this powerful in-browser tool, you can rapidly prototype integrations, debug data models, and explore new GraphQL capabilities in Experro. # Internationalization Source: https://help.experro.com/configurations/workspace_settings/internationalization The **Internationalization** page allows you to manage the languages supported by your storefront. By configuring multiple locales here, you can then create language-specific channels to tailor content and experiences for different regions. ## What You Can Do on This Page 1. **View Supported Languages** – See every language you’ve added, along with its code and any fallback settings. 2. **Add New Languages** – Click **Add Language**, fill out the form to register another locale, and begin using it in your storefront channels. 3. **Configure Fallbacks** – Assign a fallback language so that if content isn’t available in a given locale, the system will gracefully revert to another. 4. **Remove Unneeded Languages** – Delete any non-default entries to keep your language list clean (note that **English – United States** cannot be removed). ## Internationalization Settings | Field | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Language Name** | The display name for the locale (e.g., “French – France”). This appears in dropdowns throughout the UI when selecting a language. | | **Language Code** | The standard two- or five-character code (e.g., `fr`, `fr-FR`) that uniquely identifies the locale. Auto-populated when you choose a language in the add panel. | | **Fallback Language** | If content is missing in this locale, the system will fall back to the chosen language (e.g., fallback from `fr-CA` to `en-US`). Helps ensure a consistent user experience. | | **Actions** | - **Delete**: Remove this language entry (except for the default **English – United States**). Use with caution, as removing a language will disable any channels tied to it. | ## Adding a New Language 1. Click **Add Language**. 2. In the popup form: * **Language**: Choose from the dropdown (e.g., “Spanish – Spain”). * **Language Code**: Automatically fills in based on your selection. * **Fallback Language**: (Optional) Select which existing locale to use as a fallback. 3. Click **Save** to register the new locale. Once saved, your new language appears in the list, ready for use when creating storefront channels. # Introduction Source: https://help.experro.com/configurations/workspace_settings/introduction Welcome to **Workspace Settings**, your central hub for configuring every aspect of your Experro workspace. Here you’ll find three main areas of control: ## General Define your workspace name, logo, timezone, currency, and shareable link. Manage Development, Staging, Production (and more) and choose a default. Register supported locales and set fallbacks. Create language- and region-specific storefronts with custom URL prefixes. Teach Experro about your industry, brand tone, catalog, and customers so our AI can make smarter recommendations. ## Integrations Generate secure tokens to authorize scripts and API calls. Explore and test our GraphQL API in-browser with GraphiQL. Configure one or more mail servers for notifications and transactional emails. Define event-driven HTTP callbacks, custom headers, and failure alerts. Link Shopify, BigCommerce, Magento, and more to sync products, orders, and customers. ## Security Invite, manage, and deactivate team members within this workspace. Create role-based permission sets to control who can view, edit, or administer each feature. As you configure these settings, your workspace will be tailored to match your team’s workflows, security requirements, and international audiences—all backed by Experro’s powerful AI and integration capabilities. # Roles Source: https://help.experro.com/configurations/workspace_settings/roles The **Roles** page enables workspace administrators to define and manage permission sets that control what actions users can perform within the current Experro workspace. You can review existing roles, see how many users are assigned to each, and create new roles tailored to your team’s needs. ## What You Can Do on This Page 1. **Browse Existing Roles** – View every role configured for this workspace, along with its description and user count. 2. **Edit Role Details** – Update a role’s name or description, or adjust its permission set. 3. **Delete Unused Roles** – Remove roles that are no longer needed (only possible if no users are assigned). 4. **Create New Roles** – Define a new role by naming it, describing its purpose, and assigning granular permissions via the permissions matrix. ## Field-by-Field Breakdown | Field | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | The unique identifier for the role (e.g., “Workspace Admin”, “Report Viewer”). | | **Description** | A brief summary of the role’s purpose and authority (e.g., “Can manage workspace settings and integrations”). | | **Users** | The count of active users currently assigned this role. | | **Action** | - **Edit**: Modify the role’s name, description, or permissions.
- **Delete**: Permanently remove the role (only if no users are assigned). | ## Creating a New Role 1. Click **Add Role**. 2. In the **Add Role** form: * **Role Name**: Enter a clear, concise name. * **Description**: Summarize what this role allows. 3. **Permissions Matrix**: * Toggle each permission using the check-box in the matrix to grant or restrict access. 4. Click **Save** to create the role. Once saved, the new role appears in the list and can be assigned to users on the **Users** page. # SMTP Settings Source: https://help.experro.com/configurations/workspace_settings/smtp_settings The **SMTP Settings** page lets you configure the mail server(s) Experro will use to send transactional and notification emails for your storefront. You can review existing SMTP setups, add new ones, and manage the exsiting SMTP servers. ## What You Can Do on This Page 1. **Review Existing Configurations** – See all SMTP entries you’ve created, including metadata like creation and modification details. 2. **Add New SMTP Servers** – Click **Add SMTP** to supply the host, credentials, and security settings for a new mail server. 3. **Edit or Delete** – Use the **Action** column to modify an existing configuration or remove one that’s no longer needed. 4. **Support Multiple Servers** – Maintain several SMTP profiles (e.g., one for marketing emails, another for system alerts) and choose among them as needed. You can create multiple SMTP configurations and route different types of emails through distinct servers to optimize deliverability and separation of concerns. #### Adding a New SMTP Configuration 1. Click **Add SMTP**. 2. Fill in **SMTP Name**, **From Name**, and **From Email**. 3. Enter **SMTP Host** and **SMTP Port**. 4. Select **Encryption** (None, SSL, or TLS). 5. Toggle **Authentication** **On** if required, then supply **SMTP Username** and **SMTP Password**. 6. Click **Save** to persist the new configuration. Your new SMTP profile will appear in the list, ready to be selected for sending emails from Experro. # Store Integration Source: https://help.experro.com/configurations/workspace_settings/store_integration The **Store Integration** page provides pre-built connectors and instructions for linking Experro to your eCommerce platform. Once connected, Experro can automatically import products, orders, customer data, and other storefront information to power analytics, AI recommendations, and automation. ## What You Can Do on This Page 1. **See Available Integrations** – View all supported platforms—Shopify, BigCommerce, and Magento—and their connection status. 2. **Follow Step-by-Step Instructions** – Use the in-UI guide to complete the integration, including any required extensions or API credentials. 3. **Manage Connected Stores** – Review which storefronts are linked, disconnect if needed, or reauthorize when credentials change. ## Supported Platforms | Platform | | --------------- | | **Shopify** | | **BigCommerce** | | **Magento** | Click on the desired platform to begin. Once authorized, Experro will automatically ingest your store data, keeping everything up to date without manual exports. Let me know if you’d like to adjust any of the placeholders or add more detail! ## Shopify & BigCommerce For Shopify and BigCommerce, Experro offers seamless, plug-and-play connectors. Follow the linked documentation to connect to the store, grant the necessary scopes, and start syncing your catalog and orders within minutes. * [Shopify Plug & Play Integration](/plug_and_play/shopify_integration) * [Big Commerce Plug & Play Integration](/plug_and_play/bigcommerce_integration) ## Magento For Magento, follow the steps below to complete the integration. This guide is divided into two major segments: 1. **Adding the Experro Extension to Magento** 2. **Configuring the Magento–Experro Integration** ### 1. Adding the Experro Extension to Magento In this section, you will add the Experro extension to your Magento installation. Follow these steps carefully to ensure that the module is correctly installed and visible in the Magento Admin panel. #### Prerequisites * You have already downloaded the **Experro Connector** ZIP file to your server. * If you do not have the file, contact the Experro Support Team. #### Installation Steps 1. **Extract the Experro Connector Module Files** 1. Upload or move the ZIP file to your Magento root directory. 2. Extract the ZIP into: ``` MagentoRoot/app/code ``` 2. **Verify the Folder Structure** Ensure the extracted module appears as: ``` MagentoRoot/app/code/Experro/Connect ``` 3. **Run Magento Compilation Commands** From the Magento root directory, run: ```bash theme={null} php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento indexer:reindex # Only if required php bin/magento cache:clean php bin/magento cache:flushchmod 777 -R var pub generated ``` 4. **Module Confirmation** 1. Log in to your Magento Admin panel. 2. You should see the **Experro** module logo in the left sidebar. 3. To verify connectivity, navigate to: ``` Admin > Experro > System Status ``` ### 2. Configuring the Magento–Experro Integration #### Prerequisites * You have uploaded and extracted the Experro Connector ZIP file as described above. #### Integration Steps 1. Magento Admin Access 1. Log in to the Magento Admin panel. 2. Navigate to **Experro Connect**. 2. Experro Admin Configuration 1. Log in to the Experro Admin panel. 2. Go to **Platform** > **Install Magento Integration**. 3. Click **Add Store** and fill in the required details: * Environment * Store Name * Magento Store URL * Channel * Language 4. Click **Next**. 3. Copy Experro Token 1. After clicking **Next**, you will see your **Experro Token** displayed. 2. Copy the token (you will need it in Magento). 4. Connect to Experro from Magento 1. Return to the Magento Admin panel. 2. Click **Connect to Experro**. 3. You’ll be redirected to a connection form. 4. Paste the Experro token and fill in any other required fields. 5. Click **Next**. 5. Store Details Page Once connected, you will see the **Store Details** page in Magento, confirming the integration. 6. Verification Navigate to Experro, and click the Verify button. 7. OAuth Details Configuration 1. After clicking Verify, you will be redirected to the OAuth Details page. 2. Copy the store details information from the Magento Admin panel into the respective fields. 3. Click on the Next button. 8. Final Storeview Configuration 1. Complete the final details on the Storeview Details page. 2. Click on the Connect button. 3. A confirmation message "Store added successfully" should appear. 4. The system will then redirect you to the store listing page, where your newly added store will be displayed. This guide should help you smoothly integrate Magento with Experro. # Users Source: https://help.experro.com/configurations/workspace_settings/users The **Users** page lets workspace administrators view, manage, and invite team members to access and work within the current Experro workspace. You can review existing users’ details, adjust their roles and status, and add new users by assigning them predefined roles. ## What You Can Do on This Page 1. **Browse Existing Users** – See all users associated with this workspace, along with key metadata. 2. **Edit User Details** – Change a user’s assigned roles or update their status. 3. **Delete a user** – Remove a user’s access entirely. 4. **Reset Password** – Trigger a password reset email for any user who needs to regain access. 5. **Invite New Users** – Add new team members (must already exist in the global Admin panel) and assign them workspace-specific roles. ## Field-by-Field Breakdown | Field | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Name** | The user’s full name as registered in the global account settings. | | **Email** | The email address they use to log in. | | **Roles** | The workspace-specific role(s) assigned (e.g., Admin, Editor, Viewer). Roles control the scope of actions the user can perform. | | **Status** | Indicates whether the user is **Active** or **Inactive** (disabled). Inactive users cannot log in. | | **Action** | - **Edit**: Update roles or toggle status.
- **Delete**: Permanently remove the user from this workspace.
- **Reset Password**: Send a reset link. | ## Adding a New User 1. Click **Add User**. 2. In the **Add User** form: * **Select User**: Choose from existing global users in your organization. * **Assign Role**: Pick one or more workspace roles to define their permissions. 3. Click **Save** to invite the user to this workspace. Only users already created at the global Admin level can be added here. To create a new global user, please visit the Admin panel outside of this workspace. # Webhooks Source: https://help.experro.com/configurations/workspace_settings/webhooks The **Webhooks** page lets you configure outbound HTTP callbacks so that external systems can react in real time to events in your Experro workspace. You can view, enable/disable, and manage existing webhooks, as well as create new ones with custom payloads, headers, and notification rules. ### What You Can Do on This Page 1. **Browse Configured Webhooks** – See all webhooks you’ve defined, including their endpoint URL, status, last modified details, and quick actions. 2. **Enable or Disable** – Toggle the **Active** switch in the list view to turn individual webhooks on or off without deleting them. 3. **Create New Webhooks** – Click **Add Webhook** to define a new callback, choose triggering events, and set up custom headers or authentication. 4. **Inspect Activity Logs** – After creation, use the **Activity Log** tab on a webhook’s detail page to review delivery attempts, payloads sent, and response statuses. 5. **Configure Failure Notifications** – On the **Email Notification** tab, specify recipients who should be alerted if a webhook repeatedly fails. ### Webhook List View | Column | Description | | --------------- | ------------------------------------------------------------------------------------------------- | | **Toggle** | Quickly turn on/off the webhook from the list. | | **Name** | The descriptive label for your webhook (e.g., “Order Created Hook”). | | **URL** | The HTTP endpoint that will receive the POST payload when the webhook fires. | | **Status** | Shows **Active** or **Inactive**. Use the toggle to instantly enable or disable without deletion. | | **Modified At** | Timestamp of the last configuration change. | | **Modified By** | User who last edited the webhook settings. | | **Action** | - **Edit**: Open the webhook detail page.
- **Delete**: Permanently remove this webhook. | ### Adding or Editing a Webhook When you click **Add Webhook** (or **Edit** on an existing one), you’ll see three tabs: #### 1. Configure Webhook | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | A clear label for identification (e.g., “Inventory Update Notifier”). | | **URL** | The target endpoint where Experro will POST event payloads. | | **Active** | Toggle **On** to enable deliveries immediately; **Off** to pause without deleting. | | **Environment** | Choose which environment(s) (Development, Staging, Production) should trigger this webhook. | | **Custom Header** | Add arbitrary HTTP headers (e.g., `X-Signature: abc123`) to accompany each request. | | **Secret Header** | Define a header (e.g., `X-Webhook-Secret`) containing a shared secret for verifying payload authenticity. | | **HTTP Basic Auth** | Supply a key, value pair if your endpoint requires Basic Authentication. | | **Triggering Events** | Select one or more event types by specifying the **Object** (e.g., `Order`), **Model** (e.g., `Order Created`), and **Action** (e.g., `create`, `update`, `delete`). Only these actions will invoke the webhook. | | **Save** | Persist your settings. Once saved, the webhook becomes active if toggled on. | #### 2. Activity Log * Displays a chronological record of the webhook’s delivery attempts * Helpful for debugging failures or verifying that downstream systems received data correctly. #### 3. Email Notification * **Notification Emails**: Comma-separated list of email addresses to alert when the webhook is automatically deactivated after repeated failures. # Workspace Details Source: https://help.experro.com/configurations/workspace_settings/workspace_details The **Workspace Details** page is where administrators configure and manage the core identity and settings of your Experro workspace. From this page you can: * Upload or change the workspace logo/image * Set the workspace’s display name and description * Choose the timezone and currency your workspace will use * Copy the unique workspace link for sharing or embedding * Save any updates or, if necessary, delete the entire workspace ## Workspace Settings | Field | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Workspace Image** | A square or circular logo representing your workspace. Click **Change Image** to upload a new file (JPG or PNG). Recommended size: 4 MB. | | **Workspace Name** | The primary identifier for your workspace. Keep it concise and unique (e.g., “Acme Corp Ops”). | | **Description** | A short text explanation regarding the workspace’s purpose (e.g., “Central analytics hub for global sales data”). | | **Workspace Timezone** | Select your local region’s timezone from the dropdown. All timestamps (events, logs, report schedules) will render in this zone. | | **Currency** | Choose the default currency (USD, EUR, INR, etc.) for any billing-related metrics or financial reports. Changing this will affect how numeric values are formatted across the UI. | | **Workspace Link** | A read-only URL that uniquely identifies your workspace. Click the copy icon to copy it to your clipboard for sharing or embedding. | | **Save** | Click to persist any changes made on this page. Unsaved changes will be lost if you navigate away. | | **Delete Workspace** | Permanently removes this workspace and all its data. **Use with caution**—this action cannot be undone. | # Cache Source: https://help.experro.com/content/caching/cache_webpages Browsers cache page resources—HTML, CSS, JavaScript, images—to speed up repeat visits. Experro’s built-in **Cache** interface lets you manage this cache, ensuring your users see fresh content when you need and blazing-fast load times otherwise. * **Faster Load Times**: Cached assets serve from the user’s device or the edge network, reducing round-trip time. * **Reduced Bandwidth**: Only changed content needs to download, lowering data transfer and hosting costs. * **Improved Scalability**: Offloading repeat requests to cache minimizes origin-server load during traffic spikes. ## Managing Cache in Experro ### Accessing the Cache Screen 1. Navigate to **Content** → **Cache** in the left sidebar. You’ll see a list of all content library entries here. ### Purging Individual Pages Remove a single page from cache forcing a fresh fetch on next request: 1. Locate the page in the list. 2. Click **Purge** next to its entry. ### Purging All Pages When you’ve rolled out a global change (layout, stylesheet, site-wide script) and you want to clear every page at once: 1. In the Cache screen header, click **Purge All Cache**. 2. Confirm the action in the prompt. With full control over caching, you can strike the optimal balance between performance and freshness ensuring your site feels both fast and up-to-date. # Create a New Entry Source: https://help.experro.com/content/content_library/create_a_new_entry From the navigation panel on the left side, navigate to **Content -> Content Library**. From the left panel, choose the Model you wish to populate (e.g., “Blog Post,” “Product,” “Homepage”). The Models you have created will be listed here. * **Single‑Entry** Record: The existing entry opens directly for editing. * **Multi‑Entry** Record: Click **Add Record** at the top-right of the page. * **Record Name**: Provide the title of the entry. * **Slug** : The Slug will be auto-generated based on the record name. The center panel displays your schema fields and Component blocks. Enter text, upload media, select options, or launch the **Visual Builder** if available. The visual builder is available only for the multi-entry content types and if you have added the Page Editor field to the content model. On the right, switch locales, view draft vs. published versions, or access version history. ## What's Next Once you have created the entry and provided the necessary details and configurations, you can [preview, publish, and schedule](/content/content_library/preview_publish_entry) it to make it live. # Creating a New Variant Source: https://help.experro.com/content/content_library/creating_a_new_variant A variant is an alternate version of a record. You build it in the record itself, then map it to an experiment variant when you set up an A/B test or personalization experiment. Variants work the same way for pages and for components. The steps below apply to both. ## Prerequisites * Permission to edit records in the content library. * A plan that includes A/B testing. Without it, the option to save a variant does not appear. ## Create a Variant In **Content Library**, open the page or component you want to create a variant of. Edit the fields you want the variant to differ on — a different headline, a different image, a different call to action. Everything you do not change carries over from the variant you started from. Click the arrow beside **Save**, then select **Save as a New Variant**. The new variant appears in the variant selector at the top of the record. **Save as a New Variant** only appears when your plan includes A/B testing. If you do not see it in the dropdown, the feature is not enabled for your workspace. ## Switch Between Variants The variant selector sits at the top of the record, beside the language selector. Open it to see every variant on the record and switch between them. The variant currently served on your storefront carries an **Active** badge. Switching variants changes what the editor below displays. Your unsaved changes are not carried across, so save before you switch. ## Using Variants in an Experiment Variants are what an experiment maps to. Once a record has more than one, it becomes selectable on the **Experience** step of the experiment flow, where you decide which variant each experiment group sees. A record used by an experiment cannot be deleted from the content library, whatever the experiment's status. Delete the experiment first, or remove the record from it. ## What's Next * [Versioning](/content/content_library/versioning) * [Map Experiences to Variants](/experiments/a_b_testing/experience) # Overview Source: https://help.experro.com/content/content_library/overview The **Content Library** is where you turn your blueprints (Models and Components) into live content by creating, editing, and managing **Entries**—the actual pages, articles, products, or data records that power your site. ## Before You Begin 1. **Review Your Models** : Ensure you’ve defined your schema under **Content Model** (single‑entry or multi‑entry types) and added the necessary fields and Components. 2. **Permissions** : You must have the **Workspace Admin** role or the “publish content” permission to create, publish, or delete entries. # Preview, Publish, and Schedule an Entry Source: https://help.experro.com/content/content_library/preview_publish_entry ## Previewing Your Content If the Model is enabled as a webpage, click **Preview** (top‑right) to open a live preview in a new tab. Use this to verify layouts, images, and text before publishing to production. ## Saving, Publishing & Scheduling ### Save Draft Click **Save** to create a new draft version, invisible to public APIs and sites. ### Publish Now Click **Publish**, choose **Now**, select the **Language** where you want to publish the content, and click on **Publish**. ### Schedule Publication In the **Publish Record** pop-up, choose **Schedule**, pick a start date/time, then confirm. In case you want to schedule a Unpublish date for the content, you can do so by clicking on the **Unpublish** check-box and following the same steps. - The version you select at publish time is what goes live even if you create new drafts afterward.
- The content goes live in the environment in which you are currently working. # Unpublish or Delete Content Source: https://help.experro.com/content/content_library/unpublish ## Unpublishing Content To remove live content without deleting the Entry: 1. Open the published entry in **Content Library**. 2. Click **Unpublish**, select the lanugage, and select **Unpublish**. Unpublishing does **NOT** delete the entry or its versions. ## Deleting Content Use deletion sparingly, as it removes all versions permanently. 1. In **Content Library**, locate the entry. 2. Navigate to the Actions column and click menu icon next to it. 3. Select **Delete**, then confirm. # Versioning Source: https://help.experro.com/content/content_library/versioning Experro automatically snapshots each entry whenever you **Publish**, and also when you **Save**—but only *after* the entry has been published at least once. This means that before an entry is published for the first time, saving it does not create a new version. However, once an entry has been published, every subsequent **Save** or **Publish** action creates a new version, allowing you to maintain a full version history. ## How Versioning Works * **Sequential Numbering** Versions increment automatically: #1 → #2 → #3, and so on. * **Custom Labels** Add meaningful names (e.g., “v3 – Updated CTA Text”) to identify key milestones at a glance. Versioning safeguards your content i.e., if a change introduces an error or you need to revert to an earlier draft, you can restore any prior version instantly. ## Viewing & Comparing Version History 1. In **Content Library**, open the menu next to your Model’s listing and select **Version History**. 2. In the history view, select two versions to compare side by side. 3. Differences are highlighted: * **Red** for content removed or changed in the newer version. * **Green** for content added or restored from the older version. 4. Use the **“Show Differences Only”** toggle to focus exclusively on changed fields. ## Renaming a Version 1. Open the entry in **Content Library**. 2. Click the **Versions** widget on the right-side of the screen. 3. Select the version that you want to rename. 4. Click **Edit**. 5. Change the **Name** and click **Save**. Include context in your version names (e.g., “Add FAQs Section”) so teammates understand the change right away ## Deleting Versions * To remove an individual version (without deleting the entire entry): 1. Hover over the version you want to delete from the Versions widget and select the delete option against the version. * There is no limit to the number of versions you can maintain, but pruning unnecessary drafts can keep your history concise. # Basics of Content Modeling Source: https://help.experro.com/content/content_model/basics_of_content_modeling ## Content Modeling: Structuring for Scale Every second, vast volumes of content such as blogs, videos, social posts, podcasts, even AR experiences and NFTs are generated around the globe. In this ever‑evolving landscape, what “worked yesterday” may not suffice today. To stay agile and ensure consistency across channels, organizations need two things: 1. A **clear strategy** for what content to create and why. 2. A **robust structure** that makes content reusable, discoverable, and future‑proof. **Content modeling** is the practice of defining that structure before you write a single word. With a headless CMS like Experro, you formalize your content types and their relationships, so editors get purpose‑built forms and developers get a predictable API. The upside? Faster time‑to‑market, fewer errors, and a content ecosystem that scales with your business. ## What Is Content Modeling? Content modeling is the process of **cataloging** and **structuring** every piece of content you manage: 1. **Catalog Content Types** Identify the different kinds of content such as blog posts, product pages, event listings, author bios, FAQs, etc. 2. **Define Attributes** For each content type, specify the fields it needs such as title, body, publication date, images, related products, and so on. 3. **Capture Relationships** Use references (relations) to link content types together (e.g., a “Blog Post” ↔ “Author” model), eliminating duplication and enabling rich cross‑content queries. **Why It Matters**

\* **Consistency**: Every blog post follows the same schema—no missing fields or ad‑hoc layouts.

\* **Reusability**: Create once, then assemble content on web, mobile, email, kiosks, and beyond.

\* **Scalability**: As you add new channels or features, your existing models adapt without rework. ## Core Elements of a Content Model In Experro’s headless CMS, **Models** are the foundational building blocks that define **what** content you store and **how** it’s structured. Think of a Model as a blueprint or schema: it specifies the exact fields—text, dates, media, relations, and more—that each piece of content must (or can) include. A content model consists of multiple fields or components to define the structure. A Content Model consists of the following elements: | Element | Definition | | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | **Content Type** | A high‑level category (e.g., “Tech Blog,” “Product Page,” “Landing Page”). | | **Attributes** | Individual fields within a type (text, rich‑text, number, date, media, relation, etc.). | | **Components** | Reusable groups of attributes (e.g., an “Image + Caption” block) that can nest in multiple types. | | **Relationships** | References linking one content type to another (e.g., a blog post’s **author** field pointing to an Author entry). | ![Content Model Diagram](https://files.readme.io/a20c70fc7fb7c17432696a136a99b8d151a1aff9925127db40d054c0a61470a7-image.png) ## Top 5 Benefits of Content Modeling 1. **Streamlined Workflow**: Clear schemas eliminate guesswork for editors and reduce back‑and‑forth with developers. 2. **Maximized Reuse** Components and relations let you assemble the same content in many contexts—web pages, apps, emails, and more. 3. **Cross‑Team Collaboration** A shared model becomes a single source of truth for designers, architects, writers, and engineers. 4. **Strategic Prioritization** When every content type and attribute is documented, you can allocate resources to the highest‑impact areas. 5. **Reduced Costs & Errors** Consistent models mean fewer integration bugs, less manual formatting, and faster onboarding for new team members. ## How to Build Your Content Model Below is a step‑by‑step approach—tailored to a tech‑news website but adaptable to any domain. ### 1. Audit & Categorize Existing Content * **Gather Samples**: Collect current articles, landing pages, FAQs, product specs, etc. * **Group Similar Items**: Create categories (e.g., “Tech Blog,” “Product Review,” “Event Announcement”). * **Sketch Wireframes**: For each category, draft a rough layout showing the key sections and elements. ### 2. Identify Attributes & Components * For each wireframe, list all individual pieces of information (title, authors, publish date, hero image, body, CTA). * Group recurring sets of attributes into **Components** (e.g., an “Author Bio” block with name, photo, and social links). ![Define Structure](https://files.readme.io/fc9f83818088b50cc8c237d57557152f12916f56dd158f574f3f9142c97b39de-image.png) ### 3. Define Content Types in Experro 1. Navigate to **Content → Content Model → Models**. 2. Click **+** followed by **Add Model**, name your type (e.g., “Tech Blog”). 3. Select **Parent Folder**. 4. Select **Multi Entry** (for multiple entries) or **Single Type** (for one‑off pages). 5. Click **Save**, then start adding fields such as the following as an example: | Field Name | Field Type | Description | | ------------ | ---------- | ----------------------------------- | | Title | Text | Headline of the blog post | | Banner Image | Media | Featured image at the top | | Publish Date | Date | Date/time when the post goes live | | Author | Relation | Links to an **Author** model entry | | Body | Rich Text | Main article content (text + media) | ### 4. Establish Relationships * Use **Relation** fields to connect models: e.g., a Blog Post’s **Author** field points to an **Author** model. * This ensures updates to the Author entry propagate across all related posts. ![Define Content Type](https://files.readme.io/aaa6afaab867dadd84b5a8e3bf883e0b5ae80b49642ed48a9c3cc520dd93eb1a-image.png) ### 5. Review & Iterate * Validate each model by creating sample entries in the **Content Library**. * Gather editor feedback: Are any fields missing? Are component labels clear? * Refine your schema before rolling out to production. ## Next Steps You now have a structured, reusable content architecture. Let us next look into the creation of a model in detail in the next section. # Components Source: https://help.experro.com/content/content_model/components Components are **reusable blocks**—groups of related fields defined once and then embedded in multiple Models. Think of them as mini‑schemas for common content patterns like banners, sliders, or testimonial cards. By using Components, you ensure consistency, simplify maintenance, and speed up page assembly. ## Why Use Components? * **Reusability**: Define a set of fields once and reuse it across many Models (e.g., “Author Bio,” “FAQ Item”). * **Consistency**: All instances of a component share the same schema and validations, so you never end up with “close but different” field sets. * **Modularity**: Break complex pages into manageable building blocks that editors can add, reorder, and configure independently. ## When to Use Components * **Banners & Slideshows**: Define a “Banner” component with title, image, and link fields to power hero carousels. * **Feature Blocks**: Create a “Feature Card” component with icon, headline, and description fields. * **Repeated Layouts**: Any section that appears multiple times or across pages (e.g., FAQs, testimonials). ## How to Create & Use Components ### 1. Navigating to the Components Area 1. In the left‑hand sidebar, click **Content Model** to expand its submenu. 2. Select **Components** to view the list of all existing components on the navigation panel from your workspace. ### 2. Creating a New Component 1. Click **+** followed by **Add Component** from the Components list on the navigation panel. 2. In the dialog, fill out: * **Compnent Name**: e.g., `Banner` or `Hero Slide` * **Internal Name**: Auto‑generated snake\_case identifier (editable) * **Description**: *(Optional)* Brief summary of its purpose * **Parent Folder**: Organize into a folder 3. Click **Save** to create the component and open its editor. ### 3. Defining Component Fields Once your component is created, you’ll land on its **Fields** tab: 1. Click **+ Add Field**. 2. Choose a field type (Text, Rich Text, Media, Boolean, Relation, etc.). 3. Configure the fields as per [Adding Fields to Your Model](/content/content_model/fields/add_fields). 4. Click **Save Field** and repeat for each attribute. ### 4. Embedding a Component in a Model To make a component available in a content type: 1. Go to **Content Model → Models** and open your target Model. 2. On the **Fields** tab, click **+ Add Field** → **Component**. 3. Select the target component. 4. Choose **Repeatable** (allows multiple instances) or **Single** (one instance). 5. Click **Save**. ### 5. Populating Component Entries Once a component is embedded in a Model: 1. Navigate to **Content Library**, and open an entry of that Model. 2. Locate the component field (e.g., **Banner**). 3. Click **Add new** to insert an instance—fill out the component’s fields (Title, Link, Image). 4. For repeatable components, click **Add new** multiple times to add several instances (e.g., carousel slides). 5. Save or publish your entry. ### 6. Use Case: Hero Carousel Slides As an example, build a **Hero Carousel** component: 1. **Define the Component** with fields: * Slide Title (Text) * Slide Subtitle (Text) * Button Text (Text) * Button Link (Text) * Slide Image (Media) 2. **Embed** it as a repeatable component in your Landing Page Model. 3. **Create Slides** in **Content Library** by adding 3–5 instances under the carousel field. Your front‑end can then iterate over the `hero_carousel` array to render a dynamic slideshow. ### 7. Editing & Deleting Components * **Edit**: Navigate to the target component, click the pencil icon at the top right of the screen to update fields or settings. * **Delete**: Click the trash‑can icon to remove a component definition. Deleting a component removes it from all Models and entries that use it. ## Best Practices 1. **Keep Components Focused**: Design each component for a single purpose. 2. **Limit Nesting**: Avoid deeply nested components to maintain clarity. 3. **Name Clearly**: Use descriptive names and identifiers so both editors and developers know each block’s role. 4. **Communicate Changes**: Modifying a component schema affects every page using it—coordinate updates with your team. With Components in place, you can assemble rich, modular page sections quickly and maintain them easily. # Create a Content Model Source: https://help.experro.com/content/content_model/create_a_content_model In order to start creating a content model, you must have a clear understanding of the content structure and how you should define your content schema. A content model consists of multiple fields to define the structure. Follow the steps below to create a content model: 1. Log in to your Experro workspace. 2. In the left‑hand sidebar, click **Content Model** under **Content** to expand its submenu. 3. Under **Models** you should see the list of existing models (if any). Before you begin, ensure you have the **Workspace Admin** role (or equivalent permission) to create and manage content schemas. 1. Click **+** followed by **Add Model** from the left-hand navigation panel. In the popup dialog, complete the following fields: | Field | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Model Name** | A human‑readable name for your content type (e.g., “Blog Post,” “Product Page”). | | **Internal Name (API Identifier)** | Auto‑populated from the Model Name in snake case (e.g., `blog_post`); you can edit it if needed. | | **Description** | (Optional) A brief summary of this content type’s purpose or usage guidelines. | | **Parent Folder** | The organizational folder where this model is stored; defaults to “Uncategorized” if you haven’t created folders. | | **Model Type** | Select **Multi entry** (multiple entries) or **Single entry** (one-off page, e.g., “Homepage”). | | **Act as Webpage** | *(Only for Multi Entry Types)* Check this to enable built‑in page slug creation and page rendering for this model. | Use clear, descriptive Model Names and Internal Names, especially if you’ll consume these via APIs. Click **Save** to finalize. You’ll be taken directly to the new Model’s **Fields** tab, where you can start defining its schema. **Next Up:** Add fields—Text, Rich Text, Number, Date, Media, Relation, and more—to shape your content structure. Check next section **Adding Fields to Your Model** for detailed instructions. ## Related Tasks * **Content Library:** Once your model is defined, switch to the **Content Library** to edit the pages you want to publish. The entries will already be populated in Content Library based on the Content Model you have created. # Adding Fields to Your Model Source: https://help.experro.com/content/content_model/fields/add_fields Once a content model is created, the next step is to define its **Fields**, the individual data points that each entry will capture. In Experro, you can mix and match a variety of field types (from simple text to rich layout blocks) to shape exactly the schema you need. ## How to Add a Field Once you have created a content model, you’ll be taken directly to the new Model’s **Fields** section, where you can start defining its schema by adding fields to it. In case you want to add fields to an existing content model, please follow the below steps: 1. Navigate to **Content → Content Model → Models**, and open your newly created Model. 2. On the model screen, click **Add Field**. 3. Choose the field type from the picker, configure its settings, and click **Save**. 4. Repeat until your schema is complete. Plan your fields upfront—think about which data you’ll query most often, which should be mandatory, and which can be grouped as reusable Components. ## Field Categories To organize your exploration, the field types are grouped into these categories: 1. **Textual Fields** * Text * Rich Text * Email * Password * JSON 2. **Media & Assets** * Media * Color Picker 3. **Choice & Relations** * Boolean * Select * Multi‑Select * Relation * Link Records 4. **Number & Date** * Number * Date & Time * Location 5. **Advanced & Layout** * Script * Style * Page Editor * Component * Flexible Content ## What’s Next In the following pages, we’ll dive into each of these field types—explaining their purpose, configuration options, and best‑practice tips. When you’re ready, pick any field from the list above, and we’ll explore it in detail. # Choice & Relation Fields Source: https://help.experro.com/content/content_model/fields/choice_relation_fields Choice & Relations fields enable structured selections, boolean flags, and inter‑model links within your content schemas. This section covers: * **Boolean** * **Select** * **Multi‑Select** * **Relation** * **Link Records** ## 1. Boolean A **Boolean** field captures a true/false value via a simple checkbox ideal for flags like “Featured?”, “Published?”, or “Accept Terms.” ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Enable Search for this field* : Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * **Validation Tab** * *Default Value* : Select the default value for the field. * *Required* : Ensure the checkbox is explicitly set. * *Read Only* : Prevent editors from modifying the field value. 3. **More** * *Help Text* : Provide guidance on what the checkbox signifies. ## 2. Select A **Select** field presents a single‑choice dropdown, letting editors choose one option from a predefined list (e.g., product sizes, regions, status codes). ### Key Configuration Options 1. **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Enable Search for this field* : Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * *Values* : Enter the list of options (one per line). 2. **Validation Tab** * *Default Value*: Pre-select an option from the values entered in the Default Tab * *Required Field*: Ensure the field is explicitly selected. * *Read Only* : Prevent editors from modifying the field value. 3. **More Tab** * *Help Text*: Describe each option’s purpose. * *Placeholder*: Show placeholder text when no option is chosen. ## 3. Multi‑Select The **Multi‑Select** field offers a dropdown allowing one or more selections from a fixed list (e.g., tags, categories, available features). ### Key Configuration Options 1. **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Enable Search for this field* : Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * *Values* : Enter the list of options (one per line). 2. **Validation Tab** * *Default Value*: Pre-select an option from the values entered in the Default Tab * *Required Field*: Ensure the field is explicitly selected. * *Read Only* : Prevent editors from modifying the field value. 3. **More Tab** * *Help Text*: Explain the selection criteria (e.g., “Choose up to 3 tags”). * *Placeholder*: Show placeholder text when no option is chosen. ## 4. Relation A **Relation** field links entries from one **Collection Type** to another, defining how content models interconnect (e.g., Author → Blog Post, Product → Category). ### Adding a Relation 1. In your Model’s **Fields** tab, click **+ Add Field** → **Relation**. 2. Enter the following details: * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. 3. Choose the **Relation Type**: * **One-to-One** (A ↔ B) * **One-to-Many** (A → many B) * **Many-to-One** (many A → B) * **Many-to-Many** (many A ↔ many B) 4. Select the **Target Model** you’re relating to. 5. Click **Save**. ### Relation Types * **One-to-One**: Single entry on each side (e.g., Product ↔ Model). * **One-to-Many**: One entry relates to multiple entries on the other side (e.g., Customer → Orders). * **Many-to-One**: Multiple entries relate back to a single entry (e.g., Products → Brand). * **Many-to-Many**: Bi‑directional multiple relations (e.g., Orders ↔ Products). ## 5. Link Records The **Link Records** field creates in‑entry references to any published entry (that has “Act as Webpage” enabled), useful for “Related Articles,” “Featured Products,” or custom cross‑links. ### Key Configuration Options 1. **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Select Model* : Select one or more **Target Models** whose entries can be linked. 2. **Validation Tab** * **Required**: Enforce at least one link. * **Read Only**: Prevent editors from modifying the field value. * **Multiple Records**: Allow linking multiple entries (vs. just one). 3. **More Tab** * **Help Text**: Clarify what should be linked (e.g., “Add up to 5 related posts”). **When to Choose Which**

Use **Relation** when your business logic requires joining data—think “Which Author wrote this Post?” or “Which Orders belong to this Customer?”

Use **Link Records** when you want editors to hand‑pick pages for menus, sidebars, “You May Also Like” sections, or any case where page interlinking matters more than data modeling. ## What’s Next Head over to **Number & Date Fields** to configure numeric inputs, date pickers, and geolocation data. # Advanced & Layout Fields Source: https://help.experro.com/content/content_model/fields/layout_fields Advanced & Layout fields empower developers and content teams to embed custom code, apply styles, and build complex page layouts directly within Experro’s CMS. This section covers: * **Script** * **Style** * **Page Editor** * **Component** * **Flexible Content** ## 1. Script The **Script** field lets you include custom JavaScript snippets or code blocks that execute on the front‑end. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * **More Tab** * **Min/Max Height**: Control the visible height of the code editor, improving readability for longer scripts. ## 2. Style The **Style** field provides a CSS editor for custom styling rules. Use it to inject scoped CSS for specific pages or components without touching your global stylesheet. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * **More Tab** * **Min/Max Height**: Adjust the editor’s height to comfortably view your CSS rules. ## 3. Page Editor The **Page Editor** is a visual, drag‑and‑drop builder that lets editors assemble pages using pre‑configured elements such as text blocks, images, carousels, banners while seeing a live preview of the final layout. Only content types with **“Act as Webpage”** enabled can host a Page Editor field. A user must have permissions to add or modify fields in the schema. **Adding Page Editor to a Content Type**: 1. In your workspace, open **Content Model** from the sidebar. 2. Select the Model you wish to enhance. 3. Click **Add Field** → **Page Editor**. 4. Provide a **Field Name** and **Internal Name**, then **Save**. 5. Switch to **Content Library**, open an entry of that Model, and click **Launch Page Editor**. 6. Drag elements from the toolbar onto the canvas, arrange sections, and customize styles, all with an on‑the‑fly preview. ## 4. Component Components are reusable field groups (e.g., “Image Card,” “Testimonial Block”) that you define under **Content Model → Components**. Once created, a **Component** field embeds these blocks into your Models: You can add a component to a content model after you have defined a component from **Content Model → Components**. In order to add a component to a content model, navigate to the Content Model that you wish to enhance. Click **Add Field**. Select the component that you wish to add to the content model. Check the section on [Components](/content/content_model/components) for full details on creating and using Components. ## 5. Flexible Content The **Flexible Content** field provides a free‑form layout builder for editorial teams who need custom page structures beyond predefined Components or the Page Editor. It lets you: * Mix and match **Sections** (e.g., Hero, Gallery, FAQ) in arbitrary order. * Define per‑section **Settings** (background color, padding, custom CSS). ### Key Configuration Optiions * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. Use Flexible Content when your site requires many unique page templates. For more structured layouts, prefer the Page Editor or Components. ## What’s Next Having configured your advanced and layout fields, you’re ready to learn about **Components** (defining reusable content blocks). # Media fields Source: https://help.experro.com/content/content_model/fields/media_fields Media & Asset fields let you manage and style visual elements within your content entries. This section covers the two core field types: * **Media** * **Color Picker** ## 1. Media The **Media** field enables editors to upload and attach one or more files images, documents, or video to a content entry. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. * *Single Media*: Restricts the field to exactly one file. * *Multiple Media*: Allows attaching multiple files per entry. * **Validation Tab** * *Allowed File Types*: Specify which file types are acceptable (e.g., Image, Files, Videos, or All). * *Required Field*: Ensure at least one file is uploaded before saving. * *Read Only*: Prevent editors from modifying the file. * **More Tab** * *Help Text*: Provide guidance on file dimensions, size limits, or usage recommendations using tooltips. ## 2. Color Picker The **Color Picker** field offers a visual swatch and HEX‑code selector, perfect for theme or brand color inputs. This field can be used to capture color values in the following scenarios among many others: * Defining brand colors for page sections or components. * Allowing editors to customize background or text colors without CSS. * Capturing design tokens directly in content entries. **Key Configuration Options**: * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. ## What’s Next After mastering media and color inputs, move on to **Choice & Relations Fields**, where you’ll learn to capture selections (booleans, dropdowns) and link entries across models. # Number & Date Fields Source: https://help.experro.com/content/content_model/fields/number_date_fields Number & Date fields capture numeric, temporal, and geospatial data within your content models. This section covers: 1. **Number** 2. **Date & Time** 3. **Location** ## 1. Number Use the **Number** field to capture any numeric input—integers or decimals—such as prices, quantities, zip codes, or rankings. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Field Type* : Choose between **Integer**, **Float**, **Double**, or **Long** to match your precision needs. * **Validation Tab** * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * *Min/Max Length* : Define the minimum and maximum value that can be entered in the field. * **More Tab** * *Default Value* : Pre‑populate the field (e.g., `0`). * *Help Text* : Guide editors on expected input (e.g., “Enter product weight in kg”). * *Placeholder* : Show example numbers (e.g., `42`). ## 2. Date & Time The **Date & Time** field provides a calendar/time picker to capture dates, times, or both making them ideal for publish dates, event schedules, or timestamps. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * *Field Type* : Select **Date**, **Time**, or **Date Time** mode. 2. **Validations** * **Required**: Ensure a timestamp is set. * **Read Only**: Prevent manual edits by selecting this option. 3. **More** * *Help Text*: Provide context (e.g., “Select the event start date and time”). Use **Date Time** for precise scheduling; choose separate **Date** or **Time** modes when only one dimension matters. ## 3. Location The **Location** field captures geographic coordinates, latitude and longitude making them perfect for mapping, store locators, or geo‑targeted content. ### Key Configuration Options * **Default Tab** * *Field Name* : Enter the display name for the field. * *Internal Field Name* : This field is auto-populated based on the Field Name. * **Validation Tab** * *Required*: Force selection of a location. * *Read Only*: Prevent manual edits by selecting this option. * **More Tab** * *Help Text*: Clarify usage (e.g., “Enter the Coordinates of your store’s address”). ## What’s Next After setting up numeric, date, and location inputs, continue to **Advanced & Layout Fields** to learn how to implement scripting, style overrides, drag‑and‑drop page builders, and flexible content components. # Textual fields Source: https://help.experro.com/content/content_model/fields/textual_fields Textual fields capture string-based data in your content models from simple one-line titles to richly formatted articles. Use these field types to collect and validate any text-centric content. ## 1. Text A **Text** field stores plain or multi-line text—ideal for titles, short descriptions, comments, or any unformatted strings. ### Key Configuration Options * **Default Tab**: * *Field Name* : Enter the display name for the field. * *Short* : Select this button if the field is used for a single-line input. * *Long* : Select this button if the field is used for a multi-line text area. * *Internal Field Name*: This field is auto-populated based on the Field Name. * *Enable Search for this field*: Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * **Validation Tab**: * *RegExp Pattern* : Enter a regular expression if you want the field to validate the input based on a specific pattern. * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * *Min/Max Length* : Define character limits. * **More Tab**: * *Default Value* : Pre-populate entries. * *Help Text* : Show contextual guidance via a tooltip. * *Placeholder* : Display example text in the empty field. ## 2. Rich Text A **Rich Text** field provides either a classic editor style or a WYSIWYG editor with formatting controls perfect for blog bodies, long articles, or any content needing styled text. ### Formatting Toolbar In the WYSIWYG editor, Editors can apply: * **Text Styles**: Bold, Italic, Underline, Strikethrough * **Headings**: H1–H4, Paragraph, Code * **Lists**: Ordered (with multiple list styles) & Unordered * **Inline Styles**: Text color, background highlight, inline classes/styles * **Blocks**: Blockquotes, horizontal rules, tables, code view * **Embeds**: URLs, media, tables * **Undo/Redo**, **Select All**, and **Alignment** tools ### Key Configuration Options * **Default Tab**: * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. * *Default Editor/Inline Editor*: Select the editor that should be used for this field. * *Enable Search for this field*: Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * **Validation Tab**: * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * **More Tab**: * *Default Value* : Pre-populate entries. * *Help Text* : Show contextual guidance via a tooltip. * *Min/Max Height*: Define height limits for the editor. ## 3. Email The **Email** field ensures editors enter a valid email address. It extends the basic Text field with email-specific validation. ### Key Configuration Options * **Default Tab**: * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. * *Enable Search for this field*: Enable this option to allow search on the data stored in this field, i.e., if you tick this option, then the field data will appear in the search. * **Validation Tab**: * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * *Min/Max Length* : Define character limits. * **More Tab**: * *Default Value* : Pre-populate entries. * *Help Text* : Show contextual guidance via a tooltip. * *Placeholder* : Display example text in the empty field. ## 4. Password A **Password** field masks input for sensitive data. Editors can toggle visibility via the “eye” icon. ### Key Configuration Options * **Default Tab**: * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. * **Validation Tab**: * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * *Min/Max Length* : Define character limits. * **More Tab**: * *Default Value* : Pre-populate entries. * *Help Text* : Show contextual guidance via a tooltip. * *Placeholder* : Display example text in the empty field. ## 5. JSON The **JSON** field allows editors to store raw JSON objects or arrays via a code editor interface. ### Key Configuration Options * **Default Tab**: * *Field Name* : Enter the display name for the field. * *Internal Field Name*: This field is auto-populated based on the Field Name. * **Validation Tab**: * *Required Field* : Enforce that editors must enter a value. * *Read Only* : Prevent editors from modifying the field value. * **More Tab**: * *Help Text* : Show contextual guidance via a tooltip. * *Min/Max Height*: Define height limits for the editor. ## What’s Next After defining your textual fields, proceed to **Media & Assets Fields** to learn how to manage images, videos, and color pickers. Then you can explore **Choice & Relations**, **Number & Date**, and **Advanced & Layout** field types to complete your model schema. # Single vs. Multi Entry Models Source: https://help.experro.com/content/content_model/single_entry_vs_multi_entry_models In Experro’s headless CMS, every Model you create must be designated as either a **Single Entry Type** or a **Multi Entry Type**. Choosing the correct type ensures your content schema aligns with how you intend to manage and deliver data. ## Single Entry Type Model A **Single Entry Type** Model is designed to hold exactly one record. Use it for site‑wide or one‑off configurations i.e., content that exists only once and shouldn’t be duplicated. **Common Use Cases** * **Site Header**: Logo, navigation links, contact info—there’s only one header across the site. * **Site Footer**: Copyright text, footer menus, social links—managed as a single entity. * **Home Page Settings**: Hero banner text, featured sections, SEO metadata for the homepage. ## Multi Entry Type Model A **Multi Entry Type** Model supports multiple records, all following the same schema. Use it for content collections where you’ll create many entries of the same type. **Common Use Cases** * **Blog Posts**: Each post is a separate entry—title, body, author, publish date. * **Products**: Every product in your catalog shares the same fields but has unique values. * **Events**: A listing of upcoming events, each with date, venue, description. The **Enable Act as Webpage** toggle appears only for **Multi Entry Type** Models. Turning it on exposes each entry under a public URL and allows use of the Page Editor for visual layout. ## When to Choose Which * **Select Single Entry Type** for configuration or global content that exists only once (header, footer, homepage). * **Select Multi Entry Type** for collections of similar items where each item is unique (blog posts, product listings). ## What's Next With the right entry type selected, you ensure your content API endpoints and editorial workflow behave exactly as you expect. Next, learn how to configure fields in your chosen Model type in [Adding Fields to Your Model](/content/content_model/fields/add_fields). # Forms Source: https://help.experro.com/content/forms/forms Experro’s Forms feature lets you capture user input—contact requests, surveys, sign-ups—either via a visual **Form Builder** or a programmatic **Free Style Form**. Built-in integrations for notifications and webhooks ensure you can act on submissions in real time. ## Form Types 1. **Form Builder** A drag-and-drop interface for assembling common form fields (text, dropdowns, numbers, media uploads, etc.) without code. Ideal for quickly adding simple to moderately complex forms to your pages. 2. **Free Style Form** A headless, API-first form you define entirely via JSON schema. Use this when you need custom validation, dynamic field logic, or integration with external form libraries. ## Creating a New Form 1. **Navigate to** **Content → Forms** in the left sidebar. 2. Click **Create Form** (top-right). 3. In the modal, enter: * **Form Name** (e.g., “Contact Us”) * **Description** (optional guidance) * **Form Type**: **Form Builder** or **Free Style** 4. Click **Create** to proceed to the form editor. ## Free Style Forms After creation, the Free Style Form screen displays: * **Form ID**: A unique identifier you’ll include in API requests. * **Google reCAPTCHA** toggle: Enable to protect against spam. Use the **REST API** from [here](/api-reference/forms) to fetch your form schema and submit responses ## Form Builder Forms In the Form Builder interface, you’ll see a palette of field types such as Single-Line Text, Paragraph Text, Number, and many more. ### Adding & Configuring Fields 1. **Drag** a field from the palette into your form canvas. 2. **Hover** the field and click the **Edit** icon to adjust: 3. **Configure** the field’s label, placeholder, help text, required status, default value, and validation message and any other properties based on the field that you have selected. 4. **Save** to apply your changes. ### Embedding Your Form * **Form Builder Forms** 1. Open a page in the **Visual Builder** from the **Content Library**. 2. Drag the **Form** element onto your layout. 3. From the dropdown, select your newly created Form Builder form. * **Free Style Forms** Integrate via the **Forms API** using the Form ID ### Notifications & Webhooks After your form is created, configure automated actions on submission: * **Notifications** Set email alerts for admins or team members. * **Webhooks** Specify a **Payload URL** whereExperro will send a JSON payload on each submission, enabling integrations with CRMs, marketing tools, or serverless functions. **Next Steps** * Test each form in **Preview** mode before going live. * Use real-time analytics in **Insights → Dashboard** to track submission volume and performance. * If you need custom styling or advanced client-side logic, combine Free Style Forms with your preferred front-end framework. # Introduction Source: https://help.experro.com/content/getting_started/introduction ## What Is the Experro Headless CMS? The Experro Headless CMS is a content‐management back end that decouples content creation and storage from presentation. Unlike a traditional “monolithic” CMS where content and front-end templates live together—Experro’s headless approach exposes all content via REST APIs. This separation enables developers to build any kind of front end (websites, mobile apps, IoT devices) while letting content editors work in a single, unified interface. * **API-First Architecture**: All content operations (CRUD) happen through well-documented API endpoints. * **Flexible Front-End Freedom**: Developers choose their framework or technology stack (React, Vue, Next.js, Nuxt.js, Angular, etc.) without being tied to a templating system. * **Omnichannel Delivery**: One body of content can feed multiple channels such as web and mobile while maintaining consistency across them. ## Key Features & Benefits Experro’s headless CMS has been designed to scale from small blogs to enterprise-level digital experiences. Below are the core capabilities that make it stand out: 1. **Content Modeling & Components** * **Custom Models**: Define structured data types (“Models”) to represent blog posts, products, authors, events, etc. * **Reusable Components**: Build nested, repeatable “Components” (rich text, image galleries, feature blocks) so that editors can assemble complex pages without developer intervention. 2. **Media Management** * **Centralized Asset Library**: Store and organize images, videos, documents, and other digital files in one place. * **Folder/Tag Organization**: Quickly find or filter assets by folder, tag, or search keywords. * **Automatic Transforms**: On-the-fly resizing and format conversion (e.g., WebP, JPEG) available via URL parameters. 3. **eCommerce Support (Optional Add-On)** * **Product, Brand, Category Models**: Pre-built templates for core eCommerce entities that can be customized or extended. * **Storefront Integration**: Use API endpoints to power product listings, carts, checkout flows, and order management on any front-end framework. 4. **Publish Workflow & Scheduling** * **Publish Queue**: Draft, schedule, and queue content for future publication without manual, last-minute intervention. * **Version Control**: Every content entry maintains a revision history. Roll back to previous versions with a single click. 5. **Forms & Lead Capture** * **Drag-and-Drop Form Builder**: Create custom forms (contact, newsletter signup, surveys) without writing code. * **Webhooks & Notifications**: Automatically push form submissions to Slack, send email notifications, or fire off API calls to CRMs. 6. **Navigation & Site Structure** * **Menu Management**: Build and reorder multi-level navigation menus. Link to Collections, Models, external URLs, or anchor links. * **Role-Based Visibility**: Control which menus or pages appear to which user roles or user groups. 7. **Cache Control & Performance** * **Built-In CDN Integration**: Content is automatically cached at the edge for lightning-fast delivery. * **Manual & Automatic Invalidation**: Purge cache for individual entries or entire Collections whenever content changes. 8. **Security & Access Control** * **Granular Permissions**: Define who can create, edit, publish, or delete content by assigning roles. * **API Tokens & Scopes**: Generate scoped API keys that restrict read/write access to specific Models or Collections. ## How This Guide Is Organized This user guide mirrors the **Content** menu structure in the Experro dashboard, providing step-by-step instructions, annotated screenshots, and best practices: 1. **Introduction** Overview of the headless architecture and core benefits. 2. **Getting Started** Logging in, navigating the UI, and understanding your workspace. 3. **Insights** Interpreting Engagement Metrics—Home and Dashboard (CMS, Orders, Products, Customers). 4. **Content Library** Managing Entries: browsing, creating, editing, versioning, and publishing. 5. **Content Model** Defining Models, Components, eCommerce templates, and Collections. 6. **Media Manager** Uploading, organizing, optimizing, and inserting assets. 7. **Publish Queue** Scheduling and monitoring content deployments. 8. **Forms** Building, embedding, and handling form submissions with notifications. 9. **Navigation** Building and managing menus and custom links. 10. **Cache** Controlling edge and browser caching, plus invalidation strategies. Each chapter builds on the last, guiding you from initial setup to delivering a fully dynamic, multi-channel digital experience with Experro. # Key concepts Source: https://help.experro.com/content/getting_started/key_concepts Before diving into the UI, it helps to understand the core phases of content creation and delivery in Experro’s headless CMS. These core concepts help you to understand the platform and the content creation workflow better and customize the content exactly as per your needs. ## 1. Modeling Your Content * **Content Models** Define the blueprint for each type of content you’ll manage such as blog posts, product pages, landing pages, event listings, and more. * Specify **Fields** such as Text, Rich Text, Number, Date, Boolean, or Relation. * Configure model settings (Single entry vs. Multi entry type, display names etc.). * **Components** Group related fields into reusable blocks (for example, an “Image + Caption” component or a “Feature Card” component). * Build once, then embed components inside multiple Models. * Components ensure consistency and speed up page assembly. **Why Models & Components Matter**

Proper modeling keeps your data structured, enforces consistency, and makes it easy to evolve your schema over time without breaking existing content. ## 2. Creating Entries in the Content Library * **Entries** Each Model automatically generates an entry in the **Content Library**. Editors use this entry in content library to create individual records i.e., your actual web pages, product entries, or data objects. * **Managing Entries** * Search, filter, and sort entries by title, status, date, or custom fields. * Preview entries before publishing to see how they’ll render on your front end. * Publish entries to make them live on your website. ## 3. Laying Out Pages with the Visual Builder * **Canvas Interface** Open any content entry in the **Visual Builder** to drag and drop fields and Components into your desired layout. * **Live Preview** See exactly how each entry will render on your front end without writing a single line of code. * **Custom Layouts** Apply grid or section layouts, resize components, and adjust styling properties right in the builder. ## 4. Publishing & Scheduling * **Publish Queue** * **Immediate Publishing:** Push your entry live as soon as it’s ready. * **Scheduled Publishing:** Set a future date and time to automatically go live. * **Version Control** Every publish action creates a new revision. Roll back to any previous version if needed. * **API / CDN Delivery** Once published, content is deployed to Experro’s CDN and exposed via API endpoints for fast, global retrieval. Stagger large content releases by scheduling key entries in advance, and monitor the Publish Queue to ensure no items are missed. ## 5. Structuring Your Site with Navigation * **Menus & Links** Use the **Navigation** section to build hierarchical menus for header, footer, sidebar, or custom navigation components. * **Link Targets** Link menu items to any published entry, external URL, or anchor within a page. **Why Navigation Matters**

A well‑structured menu not only guides users through your site but also helps search engines discover and index your content effectively. With these five phases in mind, Model → Library → Builder → Publish → Navigation, you’ll have a clear mental map of Experro’s content lifecycle. The following chapters will guide you step‑by‑step through each of these areas in the UI. # Getting Started Source: https://help.experro.com/content/getting_started/login Welcome to the Experro Headless CMS! This chapter walks you through the very first steps: accessing your account, finding the “Content” area, and familiarizing yourself with the core UI elements you’ll use every day. ## Accessing Experro and Logging In 1. **Navigate to the Experro Portal** Open your browser and go to your organization’s Experro URL (for example, `https://app.experro.com`). 2. **Enter Your Credentials** * **Email**: Your corporate or registered email address. * **Password**: Your secure account password. 3. **Two-Factor Authentication (if enabled)** * You’ll receive a time-based one-time password (TOTP) via your authenticator app (e.g., Google Authenticator, Authy). * Enter the 6-digit code to complete login. 4. **Landing Page** After successful authentication, you’ll land on the **Insights > Home** dashboard, which gives you an overview of your site’s engagement metrics. Bookmark your Experro login page and enable “Remember me” to speed up future logins provided you’re on a secure device. ## Navigating the “Content” Screen All your content-creation and management tasks live under the **Content** section in the left-hand navigation panel. 1. **Access the Left Navigation Panel** Access the navigation panel from the panel on the left side of the screen. The **Content** section is selected by default. 2. **Navigate the expanded 'Content' section** In the main nav, under **Content**, you’ll find the following sub-sections: * Home * Dashboard * Content Library * Content Model * Media Manager * Publish Queue * Forms * Navigation * Cache 3. **Drill Into a Sub-Section** Click any item—such as **Content Library**—to load that screen in the main workspace. If you are unable to access the "Content" section, verify your role’s permissions to ensure you have the required access. ## Overview of the Main UI Elements Once inside any Content sub-section, you’ll interact with a consistent set of UI components: | UI Element | Purpose | | --------------------- | ------------------------------------------------------------------------------------------------------- | | **Top Action Bar** | Contains the page title, a “+ Add Record” button for creating entries/models/forms, and a search field. | | **Sidebar (Sub-Nav)** | Contextual navigation for the current section (e.g., Models, Components etc. under Content Library). | | **Main Workspace** | The primary canvas where lists, forms, tables, and previews appear. | | **Search** | The magnifying-glass icon in the header for allowing search of a particular record. | | **User Menu** | Your avatar in the top-right to access security settings, Profile, and Log Out. | ### The Top Action Bar * **+ Add Record** * In **Content Library**, this opens a popup to create a new entry in any Model or Collection. * In **Content Model**, it lets you create a new Model or a Component. * **Search Field** * Type keywords to filter the current list (e.g., entry titles, media filenames). * Supports partial matches and live filtering. ### The Sidebar (Sub-Navigation) * **Expanding Sections** Click a parent item to expand/collapse its children. * **Active State** The current section is highlighted helping you always know where you are. ## What’s Next? With login, navigation, and UI basics covered, you’re ready to dive into **Insights**, where we’ll explore how to interpret the Home and Dashboard widgets to monitor your site’s performance. # CMS Source: https://help.experro.com/content/insights/dashboards/cms The **CMS** tab under **Insights → Dashboard** surfaces key content‑management metrics, helping you track creation, publication, and asset usage over time. Like the Home screen, start by adjusting the **Time Selector** to focus on a specific date range; all widgets will update accordingly.
CMS Widgets
### Summary Metrics * **Total Records** Shows the total number of content entries (across all Models and Collections) that were created during the selected period. * **Published Records** Counts how many of those entries were moved into the “Published” state within the chosen timeframe. * **Total Assets** Displays the number of media assets (images, videos, documents) uploaded during the selected dates. * **Total Assets Size** Sums the combined file size of all assets added in that interval, giving insight into storage growth. ### Recent Activity * **Recently Added Records**: Lists the most recent content entries that were created. Click any item to jump directly to its edit screen in the Content Library. * **Recently Modified Records**: Shows entries that were updated during the period. * **Recently Published Records**: Highlights entries that transitioned from draft to published status most recently. * **Recently Scheduled Records**: Displays entries for which a future publish date was set. This widget is useful for keeping an eye on upcoming content. Use the “Recently Scheduled Records” list to verify that time‑sensitive campaigns are queued correctly, and adjust or cancel scheduling as needed directly from the Publish Queue. Multiple widgets are interactive. You can hover over counts or timestamps to see exact dates, and click through to access the underlying list or record directly. # Customers Source: https://help.experro.com/content/insights/dashboards/customers The **Customers** tab under **Insights → Dashboard** offers a deep dive into your audience composition and purchasing behaviors. Begin by selecting a date range with the **Time Selector**; all widgets on this page will reflect metrics from that interval. ## Customer Counts & Rates * **Customers**: Total number of customer accounts during the selected period. * **New Customers**: Number of new customers within the timeframe. * **New Customer Rate**: Percentage of total customers represented by new customers (New Customers ÷ Customers × 100). * **Returning Customer Rate**: Percentage of total customers who had purchased previously and returned to buy again (Returning Customers ÷ Customers × 100). ## Revenue-Based Segmentation * **Top Customers by Revenue**: Breakdown of customers who generated the highest total revenue during the period, starting from highest to lowest. * **Top New Customers by Revenue**: Identifies the first-time buyers whose initial purchases contributed the most revenue. * **All Customer Summary by Revenue**: A comprehensive table or chart summarizing every customer’s total revenue, useful for identifying your best‑valued accounts. ## Geographic Insights * **Customers by Region**: Breaks down customer count by geographic region, helping you tailor regional marketing and support efforts. # Orders Source: https://help.experro.com/content/insights/dashboards/orders The **Orders** tab under **Insights → Dashboard** provides a comprehensive view of your eCommerce performance. Start by selecting the desired date range with the **Time Selector**, and every widget on this screen will reflect metrics for that interval. ## Revenue Metrics * **Revenue**: Displays the total sales revenue generated during the selected timeframe. * **New Buyers Revenue Share**: Shows the percentage of total revenue attributed to first‑time buyers. * **Avg. Order Value**: Calculates the average order value for the selected period. ## Buyer Segmentation * **Orders**: Counts the total number of orders placed in the selected duration. * **New Buyers**: Indicates how many distinct customers made their first purchase during the timeframe. * **Repeated Buyers**: Reflects the number of returning customers who placed at least one repeat order in that period. ## Behavioral Insights * **Purchase by Category**: Breaks down orders by product category (e.g., Apparel, Electronics), helping you identify your top‑performing segments. * **Purchase by Device**: Shows which device types (Desktop, Mobile, Tablet) were used to place orders, guiding UX and checkout optimizations. * **From Session Start to Purchase**: Tracks the average number of sessions for various user events starting from 'Page Viewed' to 'Checkout Completed', highlighting purchase funnels and potential friction points. ## Geographic Trends * **Orders by Location**: Maps or tabulates order volume by country or region, so you can tailor marketing, shipping, and localization strategies to your highest‑value markets. Multiple widgets are interactive. You can hover to reveal exact figures for deeper analysis. # Products Source: https://help.experro.com/content/insights/dashboards/products The **Products** tab under **Insights → Dashboard** surfaces detailed analytics about how your catalog items are performing. Begin by setting the **Time Selector** to your desired date range; all metrics will adjust accordingly to reflect that interval.
Product Widgets
## Core Sales Metrics * **Product Sold**: Displays the total number of product units sold during the selected period. * **Units Sold by Device**: Shows how many units were sold via each device category (Desktop, Mobile, Tablet), helping you optimize the purchase flow for your top form factors. ## Opportunity & Growth Analysis * **High Potential**: Identifies products that received relatively low traffic but achieved strong sales signaling items with untapped audience reach. * **Trending Up**: Highlights products with the largest percentage increase in units sold compared to the previous period, spotlighting emerging bestsellers. * **Top Selling**: Lists the products with the highest absolute unit sales in the selected timeframe. ## Optimization Signals * **To Improve**: Shows products that garnered high traffic but low sales conversion, indicating potential issues in pricing, descriptions, or images. * **Frequently Abandoned**: Identifies items often added to shopping carts but not purchased, helping you pinpoint friction in the final checkout steps. * **Not Selling**: Lists products that were viewed by users but did not sell at all during the selected period making them candidates for promotions or content updates. Click any product name to navigate directly to the product preview screen to review the pricing adjustments, or inventory review. Also, Use the “Units Sold by Device” breakdown to prioritize performance improvements on the devices your customers use most. Multiple widgets are interactive. You can hover to see further details and analysis. # Home widgets Source: https://help.experro.com/content/insights/home_widgets The **Home** screen under **Insights** provides a bird’s‑eye view of your website’s engagement and traffic patterns. At the top, use the **Time Selector** to adjust the date range for all widgets on the page. Each widget then surfaces a specific metric or breakdown, enabling you to quickly assess how users are interacting with your content.
Home Widgets
## Core Metrics * **Visitors**: Total number of users who visited your website during the selected time frame. * **New Visitors**: Number of users who accessed your site for the first time. * **Returning Visitors**: Number of users who had visited before and came back within the selected period. * **Website Traffic**: This displays all the traffic on your website in selected duration. ## Audience Segmentation * **Top Browsers**: Breakdown of your traffic by browser (e.g., Chrome, Firefox, Safari). Helps you prioritize browser‑specific testing or feature support. * **Top Devices**: Distribution of sessions across device types (e.g., Desktop, Smartphone ). Offers insight into which device to optimize for. * **Top Countries**: Geographic distribution of your visitors, showing the top countries by session volume. Useful for localization and geo‑targeted content. * **Top Operating Systems**: Shows which OS platforms (Windows, macOS, Android, iOS, etc.) your audience uses most. ## Traffic Sources & Entry Points * **Sessions by Traffic Source**: A grid view of where your visitors came from. Identify where the most visitors came from based on the source. Use this to gauge the effectiveness of acquisition channels. * **Top Landing Pages**: Lists the URLs or content entries that received the highest number of first‑touch visits. Identifies your most compelling entry‑point content. Multiple widgets are interactive. You can hover or click on chart segments and table rows to drill into the underlying data. Together, these widgets give you a holistic snapshot of who your visitors are, where they come from, and how they enter and interact with your site. # Bulk Operations Source: https://help.experro.com/content/media_manager/bulk_operations To speed up common tasks such as deleting an asset or moving an asset to another folder, you can select and manage multiple assets at once: 1. **Select Assets** * Hover over an asset and select the check-box to add it to your selection and repeat the process to select multiple assets, and * if needed, click **Select All** at the top of the screen that appears once you have selected an asset to select every item in the current folder. 2. **Apply Action** * With your files selected, click **Delete** or **Move** option that appears at the top of the screen after you have selected multiple assets to apply it to all chosen assets simultaneously. Bulk deletion is permanent. Before proceeding, verify that none of the selected assets are in use on live pages or entries. ## Next Steps You’ve now mastered the Media Manager: * Uploaded and validated assets * Organized files into folders and subfolders * Edited metadata for accessibility and SEO * Performed bulk actions for efficiency Next, head back to the **Content Library** to: * **Insert Media** into your entries * **Assemble Pages** using the Page Editor or Components * **Publish** your enriched content to deliver engaging digital experiences across your site. # Managing Assets Source: https://help.experro.com/content/media_manager/managing_assets ## Editing Asset Details 1. In **Media Manager**, click an asset’s name or thumbnail. 2. On the detail page, update: * **File Name** * **Alt Text** * **Title/Caption** 3. Click **Save**. Changes are propagated to every entry using that asset (URL remains unchanged). ## Deleting Assets 1. You can delete an asset from either the asset list in **All Media** or detail view of a particular asset. 2. From the asset list, click on the three dots next to the asset and select the **Delete** option. 3. From the detail view of an asset, click on the **Delete** button. 4. Confirm the delete action, and the asset will be deleted permanently. Deletion is permanent and may break content entries that reference the asset. # Organizing with Folders Source: https://help.experro.com/content/media_manager/organizing_with_folders Folders help you keep your Media Manager tidy and make it easy to locate specific assets. You can create nested structures to reflect your project’s taxonomy. ## Creating a Folder In the left sidebar, select **Media Manager**. Click **Create Folder** in the top‑right corner. Enter a unique folder name (max 30 characters; avoid `\ * : < > ? / |`). Click **Create** to add the folder to your current path. Use clear, descriptive names (e.g., “Blog Hero Images,” “Product Presentations”) to streamline asset discovery. ## Nested Folders You can organize folders up to **5 levels deep**—ideal for large projects needing multiple subcategories (e.g., Year → Quarter → Campaign). ## Renaming a Folder In the sidebar, hover over the folder you wish to rename. Click the **…** menu next to the folder name and select **Rename**. Update the folder name (observe the same character restrictions) and click **Save**. ## Deleting a Folder Hover over the target folder in the sidebar. Click the menu → **Delete**. In the confirmation dialog, click **Delete**. Deleting a non-empty folder is blocked to prevent accidental loss of assets. Remove or relocate files first before deletion. With your folder structure in place, you can quickly navigate to the right location for uploads, bulk operations, or file retrieval keeping your Media Manager organized and efficient. # Overview Source: https://help.experro.com/content/media_manager/overview The **Media Manager** is your centralized asset repository within Experro’s headless CMS. It streamlines the entire asset lifecycle i.e., uploading, organizing, and managing images, documents, videos, and more—so you and your team can quickly find, reuse, and update media without leaving the CMS. ## Asset Fundamentals ### What Is an Asset? An asset is any file you upload—be it an image, document, or video clip that you can then reference in your content entries. Treat it as a building block for your site’s pages, blogs, products, or forms. ### Supported Formats Experro’s Media Manager accepts a wide range of file types, ensuring you can store virtually any asset your project requires: * **Images**: `.jpeg`, `.jpg`, `.png`, `.webp`, `.svg`, `.gif`, `.tiff`, `.psd`, `.ai`, `.bmp`, `.raw` * **Documents & Spreadsheets**: `.doc`, `.docx`, `.odt`, `.txt`, `.rtf`, `.csv`, `.xls`, `.xlsx` * **Presentations**: `.ppt`, `.pptx` * **Video**: `.mpeg`, `.mp4`, `.mov`, `.wmv`, `.avi`, `.flv` If you attempt to upload an unsupported or corrupted file, you’ll receive a clear error message with the option to retry or choose a different file. ### Roles & Permissions Asset management is governed by your workspace permissions. Only users with the **Workspace Admin** role (or explicit asset‑management rights) can: * **Upload** new files or folders * **Edit** asset metadata (file name, alt text, captions) * **Delete** files or entire folders * **Create**, **rename**, and **remove** organizational folders This ensures that only authorized team members can modify your site’s media library and safeguard against accidental changes. With these fundamentals in place, you’re ready to start adding and organizing your assets. In the next section, you’ll learn how to upload files—either by clicking to browse your local computer or by using drag‑and‑drop for quick batch uploads. # Uploading Assets Source: https://help.experro.com/content/media_manager/upload_assets The Media Manager offers two intuitive methods for adding files from single images to multiple images directly into your asset library. ## Click‑to‑Upload From the left sidebar, select **Media Manager**. Navigate to the desired folder (by default you land in **All Media**). Click the **Upload** button in the top‑right corner of the folder view. In the system file picker, select one or more files and click **Open**. Each file displays an upload progress bar; wait until you receive the message for sucessfull upload. ## Drag‑and‑Drop Open **Media Manager** and browse to the target folder. From your desktop or file explorer, drag one or more files onto the designated drop zone. Drop the files to start the upload. Monitor the progress bars as each file uploads. ## Post‑Upload Validation & Error Handling * **Unlimited Size & Quantity** : Upload as many files of any size as you need as there are no hard limits on file count or total data volume. * **Retry on Failure** : If an upload fails, you’ll see an “Upload failed. Retry” message. Simply click **Retry** to attempt that file again. * **Unsupported Formats** : When you try to add a file with an unsupported extension, the system displays “File not supported.” Check the file type and try again with a compatible format. With your assets successfully uploaded, you can now edit metadata, organize files into subfolders, or insert them directly into content entries using the Content Library. # Add Pages to Your Menu Source: https://help.experro.com/content/navigation/add_pages_to_your_menu With your new menu created, the next step is to populate it with links to your published pages. ## Open Your Menu 1. In the left sidebar, click **Content**, then under **Appearance** select **Navigation**. 2. In the list of menus, locate the menu you created. 3. Click the menu name to open the menu editor. ## Pick Pages to Add 1. In the left panel, select a **Content Model** to view its published entries. 2. Tick the checkbox next to each entry you want to include in your menu. 3. Click **Add to Menu**. ## Reorder Menu Items 1. In the right panel, your selected entries appear as menu items. 2. **Drag and drop** each item to reorder them in the desired sequence. 3. The topmost item becomes the first link in your menu. ## Save Your Changes Once your pages are in place and ordered correctly: 1. Click **Save** (top-right) to commit your changes. 2. Your updated menu is now live for your front-end theme to consume. To add items from another Model or include newly published pages, simply return to this screen, select additional entries, and click **Add to Menu** again. # Create a Navigation Menu Source: https://help.experro.com/content/navigation/create_navigation_menu ## Prerequisites Before you begin, make sure you have: * At least one **Multi-Entry** Model with **“Act as Webpage”** enabled. * **Workspace Admin** role (or equivalent) to manage navigation. ## Steps to Set Up a New Menu In the left sidebar, click **Content**, then under **Appearance** select **Navigation**. Click **Add Navigation** in the top-right corner of the screen. In the **Navigation Name** field, enter a descriptive label (e.g., “Main Menu,” “Footer Links,” “Sidebar”). Click **Save** to create your new, empty menu. ## What’s Next? * Your menu now appears in the Navigation list. * Proceed to **Adding Pages to Your Menu** to populate it with links. * Later, you can revisit this screen to **Edit**, **Delete**, or **Rename** your menu at any time. # Editing & Deleting Entire Menus Source: https://help.experro.com/content/navigation/edit_delete_menu Once you’ve created a navigation menu, you can update its name or remove it entirely when it’s no longer needed. ## Renaming or Updating a Menu 1. In the left sidebar, click **Content**, then under **Appearance** select **Navigation**.. 2. Hover over the menu you wish to change and click the on the menu option under **Actions** column menu. 3. Select **Edit**/**Rename** based on the action you want to perform. Make the required changes. 4. Click **Save** to apply your changes. ## Deleting a Menu Deleting a menu removes it permanently. Ensure it isn’t actively used by your live theme. 1. In the left sidebar, click **Content**, then under **Appearance** select **Navigation**.. 2. Hover over the menu you wish to change and click the on the menu option under **Actions** column menu. 3. Select **Delete**. 4. Confirm the deletion in the prompt. With your menus created, populated, and organized or removed when obsolete, you have full control over your site’s navigation structure. Next, learn how to manage individual menu items in the next section **Managing Individual Menu Items**. # External & Custom Links Source: https://help.experro.com/content/navigation/manage_external_links In addition to linking to your published pages, you can include arbitrary URLs such as external websites, campaign landing pages, or documents by leveraging a **Custom Links** Content Model. ## “Custom Links” Content Model 1. **Create the Model** * A content model for Custom Links is alredy created in the system by default. 2. **Fields in the model** The content model has the following fields added inside it: * **Title** (Text): The display name for your link. * **Link** (Text or Email): The full URL (optionally validate with regex). * **Description** (Rich Text, optional): Additional context or instructions. ## Creating Custom Link Entries 1. Navigate to **Content Library → Custom Links**. 2. Click **Add Record**. 3. Fill in: * **Title**: e.g., “Support Portal” * **Link**: e.g., `https://support.example.com` * **Description** (optional) 4. Click **Save** (or **Publish** if you want it available immediately). ### 3. Adding Custom Links to Menus 1. Move to the navigation section and select your menu. 2. In the left panel, choose the **Custom Links** model. 3. Tick the checkbox next to the entries you want in your menu. 4. Click **Add to Menu**; the items appear in the right pane. 5. **Drag and drop** to position them alongside page links. 6. Click **Save** to update the menu. With Custom Links integrated into your navigation, you can easily blend internal pages and external resources giving users a unified menu experience across all your site’s destinations. # Manage Individual Menu Items Source: https://help.experro.com/content/navigation/manage_individual_menuitems Beyond creating and ordering, you can customize or remove specific items within a navigation menu to fine-tune your site’s user experience. ## Deleting a Menu Item 1. Navigate to the menu you wish to edit and select your menu. 2. In the right panel, locate the menu item you wish to remove. 3. Click the **pencil** (Edit) icon on that item. 4. In the pop-over, click **Delete**. 5. Click **Save** (top-right) to persist your changes. Deleting a menu item does not delete the underlying page—it simply removes the link from your navigation. ## Customizing a Menu Item Click the **pencil** icon beside any item to open its settings: * **Display Label**: Override the default text (e.g., “About Our Company” → “About Us”). * **Title Attribute**: Text shown on hover. Use for accessibility or extra context. * **Class Name**: Add custom CSS classes for unique styling. * **Link Target**: Choose opening behavior: “Same Tab” or “New Tab.” After making edits, click **Update** in the pop-over, then **Save** your menu. ## Best Practices * **Clear Labels**: Keep menu labels concise and user-focused. * **Consistent Behavior**: Limit “New Tab” links to external destinations or documents. * **Styling Hooks**: Use **Class Name** sparingly to apply unique styles only when necessary. With the ability to remove or tailor individual menu items, you can maintain a navigation structure that adapts to your evolving site content and design. Up next: **External & Custom Links**. # Multi-Level Menus Source: https://help.experro.com/content/navigation/multi_level_menu Dropdown or nested menus let you organize related links under a single parent, creating a clear hierarchy that improves user navigation on complex sites. ## Add Your Top-Level Items Ensure you’ve already added all the pages that you want in your hierarchy to your menu following [Add Pages to Your Menu](/content/navigation/add_pages_to_your_menu). ## Nest a Child Item 1. In the right panel of the menu editor, locate the item you want to make a **child**. 2. **Drag** that item directly **below** its intended **parent**. 3. While dragging, shift the item slightly **to the right**—you’ll see a nested indentation indicator. 4. **Drop** to create the parent → child relationship. ## Add Deeper Levels Repeat the drag-and-drop nesting for additional layers: * **Sub-Child**: Drag an item under a child and indent further. * **Unlimited Depth**: You can nest as many levels as your design requires (though 2–3 levels is typical for usability). ## Save Your Menu Once your hierarchy is set: 1. Click **Save** (top-right). 2. Confirm your front-end theme reflects the nested menu (check your site header, footer, or sidebar). ## Best Practices * **Keep it shallow**: No more than 2–3 levels deep to avoid burying content. * **Group logically**: Children should naturally fall under their parent’s category (e.g., “Team” under “About”). * **Use clear labels**: Ensure menu labels communicate hierarchy and context clearly to users. # Overview Source: https://help.experro.com/content/navigation/overview A clear, intuitive menu is vital for guiding your visitors through your site whether it lives in the header, footer, or a sidebar. Experro’s **Navigation** feature gives you a visual, drag-and-drop interface to build and manage your menus, linking directly to any published page, collection, or external URL. ## Why Use Experro’s Navigation? * **Centralized Menu Management** Build, edit, and organize all your site menus in one place—no code required. * **Visual Drag-and-Drop** Quickly reorder items or nest submenus by dragging items on the canvas. * **Dynamic Content Links** Link directly to any **Act as Webpage** entry in your content library, ensuring your menus always reflect live content. * **Custom URLs & External Links** Include links to marketing campaigns, partner sites, or resources outside your Experro instance using a dedicated “Custom Links” model. ## Prerequisites * **Content Models & Entries**: You must have at least one **Multi-Entry** Model with **“Act as Webpage”** enabled, and you’ve created entries (pages) under it. ## Roles & Permissions To access and modify navigation menus, you need: * **Workspace Admin** role * **Manage** permissions on both the **Content Model** and **Content Library** ### When to Use Navigation * **Header Menus**: Primary site navigation—link to key sections (Home, About, Blog, Contact). * **Footer Menus**: Secondary or utility links—privacy policy, terms, social channels. * **Sidebar or Mega-Menus**: Deep hierarchies—product categories, documentation, resource libraries. * **Custom Contextual Menus**: Landing-page specific navigation or campaign-driven link sets. With this overview, you’re ready to start building your first menu. In the next page, **Creating a New Menu**, we’ll walk through the prerequisites and steps to set up your navigation. # Publish Queue Source: https://help.experro.com/content/publish_queue/pub_queue The **Publish Queue** centralizes all pending, scheduled, and completed publish and unpublish actions for your content entries. Instead of triggering each operation immediately, the system queues them and processes one at a time ensuring reliable, ordered deployments across your environments. ## Access & Permissions * **View Rights** : You need the **Workspace Admin** role or **view** permission on the relevant Content Models to see the Publish Queue. * **Navigation** : From the left sidebar, navigate to **Content** and then click **Publish Queue**. ## Queue Overview Each row in the Publish Queue gives you a snapshot of an action: | Column | Description | | --------------- | ------------------------------------------------------- | | **Title** | The entry’s title (e.g., “Blog: How to Model Content”). | | **Model** | Content Model name (e.g., Blog Post, Product). | | **Environment** | Target environment (Development, Production, etc.). | | **Language** | Language of the content entry. | | **Date & Time** | When the action was enqueued (UTC). | | **Version** | Entry version number associated with this action. | | **Status** | Current state: 'Published', 'Scheduled', 'Unpublished'. | | **Created By** | Who initiated the publish or unpublish. | | **ID** | Unique identifier of the entry or record in the queue. | ## Filtering & Searching ### Applying Filters Use the filter panel above the list to narrow down results by: * **Model** : Show only entries from selected Content Models. * **User** : Display actions performed by specific team members. * **Language** : Filter by the language of the content entry. * **Status** : Filter by Pending, In Progress, Completed, or Failed. When you select any filter, the queue refreshes automatically. ### Searching * Enter keywords (entry title, ID, or user name) in the search bar to locate specific queue items instantly. ## Reviewing Queue History To inspect actions within a specific timeframe: 1. Click the **Duration** selector above the queue. 2. Choose a preset (Last 7 Days, Last 30 Days) or pick custom start/end dates. 3. The list updates to show only queue items enqueued in that period. ## Next Steps * **Troubleshooting**: If an entry’s status is **Failed**, click the row to view error details and retry as needed. * **Unpublishing**: Scheduled unpublish actions also appear here—manage them just like publishes. * **Monitoring**: Use the Publish Queue dashboard regularly to ensure your content pipeline runs smoothly and to catch any processing errors early. With the Publish Queue, you gain full visibility into your content deployment workflow keeping your sites up to date and your team informed every step of the way. # What is Experro Merchandising? Source: https://help.experro.com/discovery_suite/ai_merchandising/what_is_merchandising ## Overview Experro Merchandising is a comprehensive tool that enables you to control how products are displayed in your digital storefront. It provides a framework for creating, managing, and automating rules that determine product placement based on specific criteria. This capability helps ensure that the right products are shown to the right customers at the right time, ultimately improving search relevance and increasing conversion rates. By leveraging Experro’s [Rule-based merchandising](/experro_discovery/merchandising/rules) , you can effectively transform casual browsers into engaged buyers. The system is designed to be flexible, allowing you to configure rules that target product promotions, optimize placement, and deliver personalized shopping experiences. Experro’s AI Merchandising combines generative AI intelligence with intuitive rule-based controls—empowering merchants, eCommerce managers, and merchandisers to optimize every product placement for maximum impact. With just a few clicks, you can layer your expertise on top of automated AI insights to spotlight high-value SKUs, drive cross-sells, and execute targeted campaigns—no developers or guesswork required. ### Key Capabilities | Capability | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Visual Merchandiser** | A drag-and-drop interface that lets you build and preview merchandising campaigns—perfect for both new users and seasoned pros. | | **Site-Wide Rule Engine** | Deploy boosts, buries, pins, slots, and exclusions globally or scoped by category, search query, or collections. | | **Product Intelligence** | Surface real-time insights on product visibility, engagement, and revenue performance to guide data-driven merchandising decisions. | | **Targeted Campaigns** | Tailor promotions to customer segments, geographies, or local events—apply rules based on brand, theme, inventory, or any attribute you choose. | | **Scheduled Rules** | Predefine and schedule time-decay boosts or demotions for key events (e.g., Black Friday, seasonal launches), then let Experro handle the timing. | | **AI-Enhanced Controls** | Eywa, our Generative AI engine, refines merchandising rules using live behavior signals—optimizing for your business KPIs automatically. | | **Experimentation Tools** | Run A/B tests on different rule sets, preview changes interactively, and view rule-level performance metrics to continuously improve ROI. | ### How AI Merchandising Drives Results * **Spotlight New Arrivals Instantly** Automatically boost fresh products into the top 20 search results on day one—building momentum from launch. * **Maximize Cross-Sell & Upsell** Promote complementary items (e.g., “Summer Caps” alongside “Florida Tees”) to create ready-made bundles and increase cart totals. * **Optimize Inventory Flow** Prioritize sale or surplus stock to accelerate turnover, and demote out-of-stock or discontinued items to avoid frustration. * **Enhance Themed Experiences** Feature curated, branded pages—like holiday gift guides or limited-edition capsule collections—to tell a cohesive shopping story. * **Unlock Sponsored Placements** Create new revenue streams by allocating prime “sponsored” slots to partners or high-margin products without disrupting the customer journey. With Experro AI Merchandising, you gain a self-optimizing toolkit that marries your strategic vision with real-time AI insights—delivering personalized, high-impact storefront experiences that delight customers and drive measurable business growth. # Autocomplete in Action Source: https://help.experro.com/discovery_suite/autocomplete/autocomplete_in_action When a shopper begins typing “dress” into the Experro search bar, Autocomplete springs into action—instantly offering relevant suggestions across all scopes: search keywords, product categories, and content pages. Below, we’ll walk through how Experro generates those suggestions and highlight common “dress” completions like “polyester dress,” “women's dress,” and “spandex dress,” as well as matching category and content page links.

### How Autocomplete Works Across Scopes 1. **Real-Time Prefix Matching**\ As each character is entered, Experro matches the growing prefix against its indexed terms (keywords, category names, and content titles) with typo tolerance. For example, typing “dress” surfaces “polyester dress,” “women's dress,” and “spandex dress” products, plus category suggestions like “Dresses” and content pages such as “Enchanting Elegance: A Guide to Evening Gowns & Party Dresses.” 2. **AI-Driven Intent Recognition**\ Beyond literal prefixes, Experro’s Gen-AI models predict the most likely next words by understanding shopper context. Since “dress” is high-traffic, the engine knows users often follow it with qualifiers (“polyester” “spandex” “women’s”), and will surface matching category pages or how-to articles (e.g., “Enchanting Elegance: A Guide to Evening Gowns & Party Dresses.”). 3. **Popularity & Performance Boosting**\ Suggestions are ranked by a blend of global popularity (how often each term or page is used) and performance signals (click-through and conversion rates). If the “Plus Size” category drives high engagement, it will rise above less-popular variants, whether product or content. 4. **Personalization Layer**\ For returning or logged-in users, Experro hones suggestions based on past behavior—surfacing “women's dress” products for dress enthusiasts, “popular dresses” category for frequent buyers, or a recently read blog post for content-focused shoppers. 5. **Configurable Rules**\ Merchants can manually boost, bury, or suppress specific terms, categories, or pages. If a new “Traditional Dress” collection is launching, adding it as a Boost Term will pin it at the top of all “dress” suggestions—across products, categories, and content pages. By blending real-time prefix matching, advanced intent understanding, performance signals, and flexible rule controls, Experro Autocomplete turns each keystroke into a rich, multi-scope discovery moment—so every shopper finds the exact product, category, or content they need. # Get the most out of Autocomplete Source: https://help.experro.com/discovery_suite/autocomplete/get_most_out_of_autocomplete ## Configuration & Best Practices * **Suggestion Types:** Choose to surface queries, categories, products, or a mix. For high-traffic stores, prioritizing product-level suggestions can drive direct clicks to top-selling SKUs. * **Max Suggestions & Grouping:** Control how many items appear and whether they’re grouped by type (e.g., top three products, then top two queries). Grouped suggestions help shoppers refine intent rapidly. * **Performance Thresholds:** Set minimum impression or click-through thresholds to keep the dropdown relevant—filtering out rarely used or obsolete terms. * **Personalization Tuning:** Adjust the balance between global popularity and individual affinities to either reinforce trending items or spotlight personal tastes. ## Tips for Leveraging Autocomplete * **Monitor Dropdown Analytics:** Track which suggestions drive clicks and which fall flat. Use this data to refine weighting rules or add new synonyms. * **Surface Promotions & Collections:** Temporarily inject campaign keywords or collection names into suggestions (e.g., “Spring Sale Dresses”) during promotions for higher visibility. * **Optimize for Mobile:** Keep suggestion text concise and limit images to ensure fast load times and easy tapping on smaller screens. * **A/B Test Layout Variations:** Experiment with different numbers of suggestions, image thumbnails vs. text-only, or suggestion grouping to find the highest-converting configuration. # Overview Source: https://help.experro.com/discovery_suite/autocomplete/overview Experro Autocomplete accelerates the path from intent to result by predicting and suggesting full queries, products, or categories as shoppers type—guiding them toward high-value searches and reducing keystrokes. Built on the same multimodal, AI-driven infrastructure as Experro Search, Autocomplete delivers instant, context-aware completions that reflect both overall trends and individual behavior. ## How Autocomplete Works * **AI-Driven Intent Recognition:** Beyond exact prefixes, Experro’s language models understand partial phrases—so typing “boho win” can surface “bohemian winter coat” without manual dictionaries. * **Behavioral Boosting:** Suggestions are ordered by a blend of global popularity (overall search volume and performance) and personalized signals (recent session clicks and known-user affinities), surfacing the most relevant completions first. * **Multimodal Suggestions:** Autocomplete can display product thumbnails alongside text entries, offering a glimpse of matching items and encouraging exploration. **Example UX:** As a shopper types “leather,” the dropdown immediately suggests “leather jacket,” “leather tote bag,” and “leather boots,” each accompanied by a small product image and search volume indicators. # Get the most out of Banners Source: https://help.experro.com/discovery_suite/banners/get_most_out_of_banners ## Why & How Banners Drive Growth ### Strategic Benefits * **High-Intent Visibility**\ Banners appear directly within search results and category pages, where users already have strong purchase intent. This ensures your campaigns are seen at the most critical decision-making moments. * **Guided Discovery**\ Banners help direct users toward specific products, categories, or collections, reducing friction and improving navigation within large catalogs. * **Campaign Amplification**\ Instead of relying only on homepage banners or ads, you can reinforce campaigns across all discovery touchpoints, increasing visibility and recall. * **Faster Execution**\ Banners can be created and deployed instantly without engineering support, enabling quick response to business needs or market trends. * **Contextual Relevance**\ By aligning banners with user queries or browsing context, you ensure messaging feels personalized and timely. ### Operational Levers * **Flexible Placement Control**\ You can define exactly where a banner appears within the product grid, such as after the 4th or 8th product, ensuring optimal visibility without disrupting the browsing experience. * **Rule-Based Targeting**\ Banners can be triggered based on search queries, categories, or merchandising conditions, ensuring precise delivery. * **Seamless Integration**\ Banners work alongside merchandising rules, collections, and search ranking logic, creating a cohesive discovery experience. * **No-Code Management**\ Merchandisers can create, edit, and manage banners directly from the dashboard, enabling faster experimentation and reduced dependency on developers. * **Performance Tracking**\ Track key metrics such as impressions, clicks, and conversions to measure the effectiveness of each banner. ## Common Use Cases * **Promote Seasonal Campaigns** Run time-bound campaigns aligned with events or seasons to drive urgency and conversions. **Example:** “Diwali Sale – Up to 50% Off” banner across home decor and gifting categories. * **Boost Product Launches** Highlight new arrivals or exclusive launches to ensure immediate visibility among relevant audiences. **Example:** A banner for “New iPhone Launch – Explore Now” shown on mobile and electronics pages. * **Drive Category-Level Promotions** Target specific categories with tailored offers to improve relevance and engagement. **Example:** “Flat 40% Off on Winter Jackets” banner within the outerwear category. * **Support Search-Based Targeting** Display dynamic banners based on user queries to align with intent. **Example:** Searching “sofa sets” triggers a banner for “Modern Living Room Collections – Shop Now.” * **Cross-Sell and Upsell** Encourage users to explore complementary products or bundles within their browsing journey. **Example:** A banner within a “Handbags” listing promotes “Complete Your Look – Wallets & Accessories.” * **Clear Inventory or Overstocks** Push slow-moving or excess inventory using targeted messaging within relevant listings. **Example:** “Last Chance Deals – Up to 70% Off” banner for clearance categories. ## Best Practices * **Keep Messaging Contextual and Clear**\ Ensure banner messaging aligns with the user’s intent and page context. Avoid generic copy and focus on relevance. **Example:** Instead of “Big Sale,” use “Up to 30% Off on Running Shoes” for a running shoes search page. * **Optimize Placement for Visibility Without Disruption**\ Place banners where they are easily noticeable but do not interrupt the browsing flow. Avoid overloading pages with too many banners. **Example:** Insert a banner after the first or second product row rather than at the very top or between every few items. * **Design for Mobile First**\ Ensure banners are responsive, lightweight, and visually clear across all devices. Prioritize readability and fast loading. **Example:** Use shorter text and high-contrast visuals for smaller screens. * **Use Strong Visual Hierarchy**\ Highlight key elements such as discounts, CTAs, and product imagery to capture attention quickly. **Example:** Emphasize “50% OFF” visually, supported by a clear “Shop Now” CTA. * **Leverage Scheduling for Campaigns**\ Pre-schedule banners for upcoming campaigns and ensure they expire automatically when no longer relevant. **Example:** Schedule a “Weekend Sale” banner to go live Friday evening and expire Sunday night. * **Continuously Measure and Iterate**\ Track performance metrics like CTR, engagement, and conversion rate to refine your strategy. **Example:** Replace low-performing creatives with new variations based on performance insights. * **Test Variations Regularly**\ Experiment with different creatives, messaging, placements, and formats to identify what drives the best results. **Example:** Compare “Flat 20% Off” vs “Save ₹500” messaging to see which performs better. By using Banners strategically, you transform your discovery experience into an active merchandising layer that not only informs users but also influences decisions, drives engagement, and delivers measurable business impact. # Overview Source: https://help.experro.com/discovery_suite/banners/overview Experro **Banners** empowers merchandisers to place promotional content (image, video or HTML) directly within **Search Results**, **Category Pages**, and **Collection Pages** — controlling what shoppers see and where they see it, at the exact moment when they are browsing and searching. Whether you’re promoting seasonal sales, highlighting new collections, or driving traffic to high-value pages, Banners ensure your marketing appears exactly when shoppers are actively browsing or searching. By blending placement flexibility with real-time preview and device-level control, Banners lets your team: * **Promote campaigns in context** — surface a "Summer Sale" banner on search results for "swimwear" and "dresses", not sitewide. * **Drive traffic to high-value pages** — redirect shoppers from a browse page directly to a new collection, brand landing page, or campaign PLP. * **Reinforce brand partnerships** — display co-branded content on category pages during joint campaigns, without modifying the product catalog. * **Capture high-intent moments** — meet shoppers with relevant offers when they are actively searching, not after they have already left. * **React to seasonal trends** — launch and retire promotional banners on a schedule, with no manual cleanup required. ## What Are Banners? Banners are promotional content units that appear within product discovery pages, configured and managed entirely from **Discovery → Banners**. Each banner works on a **two-step model**: 1. [**Create and configure the banner**](/experro_discovery/banners) (content, layout, device behavior) 2. [**Attach it to a Merchandising Rule**](/experro_discovery/merchandising/rule_types/banner_rule) that controls where and when it appears **Two-Step Model**\ Creating a banner does not make it live. A banner only appears on your storefront when it is attached to an active Merchandising Rule. See [**Using Discovery Dashboard: Banners**](/experro_discovery/merchandising/rule_types/banner_rule) for step-by-step setup instructions. Unlike traditional merchandising methods, Banners do not interfere with product ranking or relevance. They enhance discovery by adding contextual promotions without altering how products are displayed. ### Banner Content Types Banners support multiple content formats based on your campaign needs: | **Type** | **Best For** | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Image** | Standard format for seasonal promotions, campaign creative, and brand placements. Supports PNG, JPG, AVIF, WEBP or GIF up to 2 MB. | | **Video** | High-production campaigns where motion adds meaningful context. Supports video URLs from platforms like YouTube, Vimeo, Dailymotion, etc. | | **HTML** | Advanced scenarios: countdown timers, dynamic copy, embedded interactive elements, personalized messaging. | For optimal alignment, the banner dimensions should match the size of a single product tile in the PLP grid. ### Placement and Layout Control Banners integrate directly into the product grid. Seven layout options control where the banner appears relative to products: | **Layout** | **Where It Appears** | | --------------- | --------------------------------------------------------------------------------- | | **1x1** | Inline within the product grid, occupying the same space as a single product tile | | **1x2** | Spans two product columns in a single row | | **1x3** | Spans three product columns in a single row | | **Full Width** | Stretches across the entire width of the product grid | | **Top** | Above all products, before the grid begins | | **Bottom** | Below all products, after the grid ends | | **Below Facet** | Between the filter panel and the product grid | Each layout can be configured independently for Desktop, Tablet, and Mobile, ensuring your banners adapt to different screen sizes without breaking the browsing experience. **Example: "Summer Jewelry Sale" Banner** A jewelry retailer is launching a 30% off summer sale. The goal is to promote it on search results pages — not sitewide — because shoppers searching for jewelry are the highest-intent audience. 1. **Banner Creative:** Full-width campaign image featuring the hero piece, with a "Shop Now" CTA linking to the sale collection page. 2. **Layout:** Full Width, positioned above the product grid to anchor the page without competing with product tiles. 3. **Device Configuration:** Landscape crop for Desktop and Tablet; a separate portrait crop for Mobile to preserve the focal point. 4. **Merchandising Rule:** A Search Rule targeting queries like "gold necklace," "diamond earrings," and "summer jewelry" — the banner appears only when shopper intent matches. 5. **Schedule:** Live June 15 to July 31. The rule can be scheduled to publish and run during a specific interval of date and time. The rule deactivates automatically — no manual cleanup required. 6. **Event Tracking:** The onload event tracks impressions, clicks, and other interactions, and sends this data to third-party marketing platforms. An Onclick event records CTR and passes click data to the retargeting platform. | **Why It Works** | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Intent-matched placement:** Shoppers searching for jewelry see a jewelry sale — not a generic homepage banner they have already scrolled past. | | **No ranking disruption:** The banner sits within the grid but does not alter which products appear or in what order. Discovery stays merit-based; promotion stays controlled. | | **Measurable from day one:** Impression and click events are tracked the moment the rule goes live, giving the team real performance data before the campaign closes. | Ready to build your first banner? See [**Using Discovery Dashboard → Banners**](/experro_discovery/banners) for step-by-step setup instructions. # KPI Optimization Source: https://help.experro.com/discovery_suite/business_value_kpi_optimization Experro Discovery transforms your storefront into a high-performance sales engine by turning every search, click, and recommendation into measurable impact. By weaving together AI-driven relevance, live behavior signals, personalized experiences, and flexible merchandising controls, Experro helps you optimize the metrics that matter most to eCommerce success: * **Improve Conversion Efficiency** Continuous learning from shopper behavior—clicks, add-to-cart events, and purchases—ensures your top products consistently surface first. Customers find what they want more quickly, reducing friction and boosting overall conversion rates. * **Elevate Average Order Value** Intelligent cross-sell and up-sell recommendations surface complementary and premium items exactly when shoppers are most receptive. By suggesting related products and bundles in context, you guide customers toward richer carts and higher transaction revenue. * **Boost Cross-Sell Revenue** Contextual “Frequently Bought Together” and “Complete the Look” widgets turn single-item visits into multi-product purchases. This targeted pairing of accessories, upgrades, and add-ons helps maximize cart totals and overall sales. * **Eliminate Zero-Result Searches** Deep semantic and multimodal search interprets intent—even for long-tail, conversational, or image-based queries—so shoppers never hit a “no results found” dead end. Engagement stays high and potential revenue isn’t lost to dead-end searches. * **Accelerate Time-to-Market** A fully managed, headless pipeline ingests new products, price changes, and inventory updates in real time. Merchants can launch flash sales, seasonal collections, or limited-time promotions instantly—capturing revenue peaks without delay. * **Maximize Merchandising ROI** Open-box merchandising controls let you boost, bury, pin, or slot products with ease. Transparent rules and built-in experimentation ensure your strategic campaigns drive measurable uplift in revenue and campaign ROI. * **Strengthen Customer Loyalty** One-to-one personalization—from first click onward—creates tailor-made experiences that resonate with each shopper. By continuously adapting recommendations and search results, Experro fosters repeat visits, higher lifetime value, and sustainable growth. By closing the loop between every shopper action and your discovery engine, Experro Discovery becomes a self-optimizing system: every customer interaction teaches the platform how to drive more revenue, more often. # Get the most out of Collections Source: https://help.experro.com/discovery_suite/collections/get_most_out_of_collections ## Why & How Collections Drive Growth ### Strategic Benefits * **Thematic Storytelling**\ Curate lifestyle-driven assortments (e.g., “Cozy Fall Finds”) that guide customers through cohesive experiences, boosting engagement and dwell time. * **Higher AOV & Conversions**\ Surface complementary products together (e.g., handbag + wallet + scarf bundles) to encourage cross-sell and up-sell, lifting average order values. * **Real-Time Adaptation**\ AI-generated Collections update within minutes of inventory or catalog changes, ensuring your storefront always reflects current stock and seasonal priorities. * **Rapid Time-to-Market**\ Launch promotional landing pages or flash-sale Collections in under two minutes—no developer needed—so you never miss a campaign window. * **SEO & Organic Reach**\ Use AI prompts to spin up niche Collections (e.g., “Eco-Friendly Home Decor”), capturing long-tail search traffic without manual keyword research. ### Operational Levers * **Seamless Integration**\ Collections live alongside Experro’s search and recommendations, blending human curation with AI ranking for a unified discovery experience. * **Transparent Control**\ Preview and tweak Collections logic via our open-box model—fine-tune automated generation with manual overrides to match your brand voice. * **Scalable Personalization**\ Target Collections by category, search term, or user segment to deliver one-to-one thematic experiences at scale. * **Data-Driven Optimization**\ Track key metrics—click-through rate, add-to-cart rate, revenue—in Experro Analytics. Use those insights to refine your curation strategy and maximize ROI. ## Best Practices * **Optimize for Mobile & Accessibility**: Verify that your Collection renders smoothly across devices. Use responsive carousels or grid layouts that adapt to viewport width, and ensure alt-text descriptions are present for images to support both SEO and accessibility. * **Leverage Rich, Descriptive Titles & Meta Data**: Align your Collection title and URL slug with top-performing keywords (e.g., “summer festival sandals”). Consistent keyword usage in titles, headings, and meta descriptions not only aids SEO but also sets clear shopper expectations. * **Time-Box Your Promotions with Scheduling & Time-Decay**: Pre-schedule Collections around key events (e.g., holidays, seasonal launches) and apply **scheduling** so they automatically retire when relevance wanes. This ensures content freshness without manual cleanup. * **Monitor Performance & Iterate Rapidly**: Track **click-through rate (CTR), add-to-cart rate, and revenue** for each Collection in your Experro Analytics dashboard. Use these insights to refine item selection, ordering logic, and timing—turning raw data into continuous optimization. * **Use Thematic Storytelling & Visual Cohesion**: Group products around clear themes (e.g., “Eco-Friendly Home Decor,” “Weekend Getaway Essentials”). Ensure imagery, copy, and UI style consistently reflect that theme, reinforcing the narrative and guiding shopper expectations. By following these practices, you’ll ensure your Experro Collections are not only visually compelling but also optimized for discovery, performance, and conversion—turning every curated grouping into a strategic growth lever. # Overview Source: https://help.experro.com/discovery_suite/collections/overview Experro **Collections** empowers merchants to curate and showcase hand-picked groups of products—whether seasonal bundles, thematic assortments, or promotional sets—directly within search results, category pages, and recommendation slots. By blending AI-driven discovery with human curation, Collections transforms your storefront into a dynamic, story-driven journey that boosts engagement and average order value—all without writing a single line of code. By combining three modes of collection creation, you can leverage collections to: * **Tell compelling stories** (e.g. a “Cozy Cabin Getaway” bundle of flannel shirts, wool socks, and camp mugs) * **Drive cross-sell and upsell** (e.g. “Home Office Essentials” grouping desk lamps, ergonomic chairs, and monitor stands) * **React in real time** to inventory changes, promotions, or seasonal trends. ## What Are Collections? Collections are flexible assortments of products you surface anywhere in the customer journey—on search pages, category pages, home pages, or dedicated landing experiences. They come in three flavors: ### AI-Generated Collections Let Experro’s generative AI do the heavy lifting. Provide a prompt—“boho festival accessories,” or “sleek leather winter jackets,” —and Experro instantly assembles a matching set of SKUs. * *Example:* Ahead of Coachella week, fire off “festival sandals + fringe bags” and automatically surface that capsule collection site-wide. * *Benefit:* Zero manual SKU tagging and instant time-to-market.
### Product Query Define dynamic rules that pull products in and out as your catalog evolves. Use simple boolean logic—`tag:summer AND price:<100`—to power endlessly updating assortments. * *Example:* “Back-to-School Essentials” pulls in all items tagged `school` under \$50; as you add new backpacks or pens next semester, they automatically appear. * *Benefit:* Hands-off upkeep for large, rule-based assortments. ### Static CSV Uploads For full control, upload a CSV of up to 10,000 SKUs to lock in a precise list. Ideal for one-off promotions or editorial features. * *Example:* “Executive Gift Guide” for corporate clients—hand-picked leather portfolios, premium pens, and monogrammed notebooks. * *Benefit:* Exact lineup you choose, with no pops or drops until you upload a new file. ## Example: “Festival Season” Collection Imagine you’re a footwear retailer gearing up for summer music festivals. With Experro Collections, you can spotlight your festival-ready styles right when shoppers are searching for them. 1. **Collection Name:**\ `Festival Season Footwear` 2. **Scope:**\ Automatically include any sneaker or sandal tagged with `festival` in your catalog (e.g., bright gladiator sandals, embroidered canvas kicks) 3. **Display Placement:**\ Inject a dynamic carousel immediately for any query containing “sandals,” “boots,” or “festival shoes.” 4. **Activation Schedule:**\ Go live on **June 1** (just before peak festival season) and automatically retire on **August 31** to keep your storefront fresh. 5. **Merchandising Boost:**\ Within this carousel, pin your hero SKU—say, a limited-edition leather sandal—at position one, then boost related boho-style options by +20% so they surface ahead of the rest. > **Why It Works:** > > * **Contextual Relevance:** Shoppers typing “festival sandals” see curated festival picks, not generic summer shoes > * **Timely Promotions:** The time-bound activation ensures you capture festival traffic without manual clean-up. > * **Strategic Merchandising:** Pinning and boosting your key styles guarantees they get prime real estate in the carousel. With this setup, when a shopper searches for “boho festival boots” or “gladiator sandals,” they immediately encounter your hand-picked festival line—dramatically increasing the chances they’ll click through, add to cart, and join in the festival fun. # Introduction Source: https://help.experro.com/discovery_suite/discovery_introduction Welcome to the Experro Discovery documentation! Discover how Experro powers best-in-class search, merchandising, and analytics for your storefront. Browse each section below to get started. New to Experro? Start with What is Experro Discovery? to see the big picture. ## Search & Merchandising Power your storefront with Experro’s Generative AI Search—built on advanced semantic understanding, real-time behavior signals, and vector embeddings. Deliver highly relevant, intent-aware results with features like autocomplete, synonyms, and contextual query interpretation. Take full control of search and recommendation experiences with transparent, rule-based merchandising. Use boost, bury, pin, slot, and sort operations to curate results globally or for specific queries—while blending manual overrides with AI-powered rankings for maximum impact. Discover Experro’s AI-powered recommendation engine that delivers personalized product suggestions based on user behavior, preferences, and real-time interactions. Blend storytelling with algorithmic precision using Collections. Automatically generate or manually curate product groups based on themes, filters, or CSV uploads. Perfect for seasonal campaigns, SEO landing pages, and editorial curation. Guide users with smart, adaptive filters that change dynamically based on query context, catalog data, and inventory. Configure display logic, field types, and sorting to deliver lightning-fast navigation and relevant drill-downs. Unlock the full potential of your discovery strategy with real-time analytics. Track top searches, CTR, conversions, and zero-result queries. Use these insights to fine-tune your merchandising, synonym logic, and ranking models. ## Plug & Play Get your store connected in minutes. Supports Shopify & BigCommerce with a streamlined installation and configuration flow. Customize look & feel: themes, layouts, search results, autocomplete widgets, custom CSS/JS, and localized labels. Install the Experro app, configure API scopes, and connect to your Shopify store in minutes. Create API credentials and seamlessly link your BigCommerce catalog to Experro Discovery. # Facets Source: https://help.experro.com/discovery_suite/facets Facets are the filters shoppers use to refine results on a **search page, category page,** or **collection.** They appear in the left side menu on desktop, or inside a nested menu on mobile. Common examples include Brand, Color, Size, Price, and Rating. Which facets appear on a given page depends on the products in the result set. Price is likely to show on almost every page because most products have a price. Waterproof will only show when waterproof products are present. ## How Facets Work in Experro Facets begin as product attributes in your catalog. Once an attribute is indexed in Experro, you decide which attributes become shopper-facing facets by creating a Facet Rule. A Facet Rule is a group of one or more facets tied to a specific scope on your storefront. The rule controls which facets appear, how each one looks, how values are sorted and labeled, and which values are visible to shoppers. You no longer configure facets one by one as standalone settings. Every facet now sits inside a Facet Rule. To build one, see Create and Manage Facet Rules. ## Facet Scope Every Facet Rule has a Scope that determines where it applies. There are four scope types: * **Global —** Applies to the entire site. Use this for the default facet configuration that runs everywhere a more specific rule does not. * **Searches —** Applies to all search queries or to specific search terms. * **Categories —** Applies to all categories or to specific categories. * **Collections —** Applies to all collections or to specific collections. **Precedence:** A more specific rule overrides a broader one. If two rules at the same scope conflict, Experro applies the most recently active facet rule. ## Where to Start Open the Discovery section in the sidebar and click Facets to see the listing screen. For the full setup walkthrough, see Create and Manage Facet Rules. For appearance and display settings, see Configure Facet Appearance. For value-level controls (rename, merge, show/hide), see Manage Facet Values. # Merchant Intelligence Source: https://help.experro.com/discovery_suite/merchant_intelligence Managing an eCommerce storefront means juggling data collection, performance analysis, A/B testing, and optimization—all while keeping campaigns and promotions on track. **Merchant Intelligence** in Experro Discovery streamlines this process by delivering real-time, AI-powered insights and suggestions through our Eywa engine. It proactively monitors shopper experiences, identifies opportunities and issues, and even offers automated optimizations—so merchandisers and managers can focus on strategy, not spreadsheets. ## Key Capabilities | Capability | Description | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Optimization Opportunities** | Eywa continuously scans site interactions to surface underperforming queries, low-converting categories, and high-impact tests—so you never miss a chance to improve. | | **Search Trends** | Track top-searched terms over time, uncover emerging demand, and feed that intelligence back into merchandising, promotions, and inventory planning. | | **Zero & Low-Result Insights** | Identify queries that return few or no results, then refine synonyms, dictionaries, or suggestions to close those gaps and prevent lost sales. | | **Category Performance** | Monitor how each category or collection page converts and engages visitors—then adjust placement, filters, or product mix based on data-driven recommendations. | | **First-Party Behavior Tracking** | Capture detailed, cookie-less shopping signals (clicks, filters, dwell time) for more accurate performance metrics than third-party analytics platforms. | | **360° Customer Intelligence** | Combine session signals, purchase history, and site-wide behavior to build comprehensive profiles—fueling more relevant search, recommendations, and merchandising decisions. | | **Revenue & ROI Intelligence** | Tie every optimization back to revenue impact and ROI, making it easy to prioritize high-value opportunities and justify investment in discovery initiatives. | ## Why Merchant Intelligence Matters * **Proactive Issue Resolution:** Instantly detect and address performance dips before they impact sales. * **Data-Driven Strategy:** Replace guesswork with clear, actionable insights on what to boost, bury, or test next. * **Efficiency Gains:** Automate repetitive analysis and rule adjustments, freeing your team to focus on high-level merchandising strategy. * **Continuous Optimization:** With Eywa’s AI suggestions and auto-implement options, your storefront evolves in real time to meet changing customer needs. By integrating Merchant Intelligence into your Discovery Suite, you gain a trusted AI “wingman” that watches, learns, and optimizes—ensuring your storefront stays ahead of trends, maximizes revenue, and delivers exceptional shopper experiences. # Our Engine Source: https://help.experro.com/discovery_suite/our_platform Experro’s unified platform brings together four powerful pillars—Relevance, Performance, Personalization, and Merchandising—into a single engine that adapts in real time to your customers’ needs and your business goals. Here, you’ll see how each pillar works in concert: from deep semantic search that understands intent, to data-driven ranking models that reward top performers, to one-to-one experiences tailored by every click, and hands-on merchandising controls that let you steer your storefront with precision. Together, these capabilities transform product discovery from a basic utility into your most strategic growth lever. ## Relevance Experro’s semantic engine truly understands intent—handling slang, synonyms, and contextual phrases so shoppers find what they’re after even without exact keyword matches. By mapping text and images into the same high-dimensional space, Experro surfaces products based on deep similarity rather than just literal terms. Whether someone types “vintage leather satchel” or uploads a photo of a tan bag, the most relevant items rise to the top. search_pillars.png ## Performance Experro maintains a live performance score for each SKU by continuously analyzing impressions, clicks, add-to-cart events, purchases, and revenue. These metrics are tracked within the context of each query—so products that perform best for “red running shoes” may differ from those for “trail sneakers.” As customer behavior evolves, top-performing items organically climb higher in the results without any manual intervention. ## Personalization No two shoppers are alike. Experro delivers true one-to-one experiences by blending long-term affinities with real-time session signals: * **Known-user affinities:** Leverage historical orders and clicks tied to a customer’s login or email. * **Anonymous session signals:** Capture real-time actions—every click, scroll, or filter applied creates a live “session profile” that steers immediate results. By blending these signals, Experro delivers 1:1 tailored search and recommendation experiences—even on a user’s very first visit. ## Merchandising Experro’s open-box framework gives merchants granular control over product placement, layering manual rules on top of AI-driven rankings: * **Boost & Bury:** Promote new arrivals or demote clearance stock. * **Pin & Slot:** Lock products into a specific rank or range (e.g., always pin your hero SKU in position 1). * **Include/Exclude:** Force items into—or out of—the result set. With these four pillars working in concert, Experro Discovery transforms product discovery into a strategic asset—delivering personalized, high-impact experiences that delight customers and drive measurable business growth. This blend of machine-learned scoring and hands-on controls ensures your business objectives and customer intent stay perfectly aligned. # Discovery Suite Source: https://help.experro.com/discovery_suite/overview Experro Discovery is a next-generation, AI-driven product discovery platform built for the Generative AI era. Today’s shoppers demand speed, relevance, and personalization at every touchpoint—and Experro delivers on all fronts by turning search, recommendations, and merchandising into strategic growth engines. By democratizing the sophisticated tools once reserved for retail giants, Experro enables any brand to captivate customers, boost conversions, and accelerate time-to-market, all with minimal developer effort and maximum ROI. In a landscape where popular eCommerce giants pour billions into shopper engagement, Experro levels the playing field. Our platform combines customer behavior data, large-language models (LLMs), high-dimensional vector embeddings, and proprietary Generative AI (Eywa) to deliver contextually relevant, AI-powered discovery experiences. Whether a customer types a query, uploads an image, or navigates via faceted filters, Experro instantly interprets intent and surfaces the right products with zero manual tuning. ## The Generative AI Suite At the heart of Experro lies Eywa, our purpose-built Generative AI engine for eCommerce. From the very first click, Eywa learns each shopper’s preferences and intent in real time—transforming static catalogs into dynamic, personalized storefronts that drive engagement, loyalty, and sales. * **Real-Time Intent Capture:** Eywa ingests clickstream, search terms, and session behavior to continuously refine product suggestions. * **Adaptive Learning:** Generative prompts powered by LLMs craft thematic Collections and personalized Recommendations on the fly. * **Zero-Manual Maintenance:** New SKUs, promotions, and trends automatically integrate into search and discovery workflows without developer intervention. ## Powering Business Outcomes Beyond delighting shoppers, Experro Discovery accelerates merchant KPIs and frees up teams to focus on strategy rather than repetitive tasks. * **Automated Workflows:** Leverage AI-driven insights to identify underperforming queries, optimize merchandising rules, and schedule seasonal campaigns in minutes. * **Actionable Intelligence:** Built-in dashboards surface performance gaps and growth opportunities—empowering merchandisers and marketers to make data-backed decisions. * **Developer-Light Integration:** A headless, composable architecture plugs seamlessly into Shopify, BigCommerce, or Magento-live in minutes, not months. ## Technologies & Capabilities Experro Discovery’s power comes from the seamless fusion of foundational technologies and a rich feature set—delivering modern product discovery that’s fast, flexible, and flawlessly personalized. ### Data Foundations * **Customer Behavior Signals** First-party clickstream events (impressions, clicks, add-to-cart, purchases) feed live performance scores, ensuring the system learns what resonates in real time. * **Continuous Catalog Indexing** Product metadata, variant images, and rich content (blogs, guides) are ingested continuously, so every attribute remains searchable and up to date. ### AI & Semantic Intelligence * **Large Language Models (LLMs)** Deep NLP understands conversational and long-tail queries—handling slang, modifiers, and multi-part questions like a human expert. * **Vector Embeddings** Text and image data map into the same high-dimensional space, enabling true multimodal search where keywords, photos, and behavioral context converge. * **Generative AI Engine (Eywa)** Eywa crafts thematic Collections, personalized Recommendations, fallback logic for zero-result queries, and even automatic synonym generation. ### Human-Centered Controls * **Open-Box Merchandising** Intuitive rules let you boost, bury, pin, slot, or exclude products globally or scoped to categories, queries, or pages—layered seamlessly atop AI-driven scores. * **Smart Facets & Filters** AI-powered facet ranking surfaces the most relevant filters first, while dynamic grouping and hide/show rules keep the UI clean and context-aware. ### Discovery Features * **Multi-Modal Search** Combine vector, text, and image queries for rapid, high-precision results—even when catalog data is sparse. * **Autocomplete & Zero-Result Elimination** Real-time suggestions, typo correction, and search redirects keep shoppers on track and prevent dead-ends. * **AI-Driven Recommendations** A suite of pre-built algorithms (RFY, FBT, SP, PP, HNR, BS, and more) delivers personalized cross-sells, up-sells, and trending displays. * **Dynamic Collections** Create thematic assortments via CSV, smart rules, or AI prompts—then schedule and sunset them automatically to align with your campaign calendar. * **Insights & A/B Testing** End-to-end analytics and built-in experiment tools let you measure impact, validate new strategies, and continuously optimize across search, recommendations, and merchandising. ### Enterprise-Grade Architecture * **Headless & Composable** Plug Experro into Shopify, BigCommerce, Magento or any custom backend in minutes—no front-end rewrites required. * **Global & Multi-Store Support** Serve multilingual, multi-region catalogs from a single platform, with localized search and discovery experiences. ## Key Features at a Glance ### Gen AI Search Leverages customer behavior data, large language models (LLMs), vector embeddings, and proprietary AI models, to understand shopper intent and deliver precise results for every query—whether it’s a short keyword, a long-tail request, or a conceptual phrase. Shoppers enjoy instant, relevant matches even when product descriptions lack exact terms. ### Autocomplete Predicts full queries and surfaces popular suggestions as customers type, reducing keystrokes and guiding shoppers toward high-value terms. Powered by both prefix matching and AI-driven intent recognition, the dropdown can show products, categories, or trending searches in real time. ### Recommendations Product recommendations enable merchants to create a dynamic and engaging shopping experience, personalized to each shopper throughout their journey—from landing on the homepage to browsing categories, exploring products, and reaching the cart page. Our Eywa engine leverages real-time customer behavior, interests, and intent—collected from browsing, search, facets, affinities, purchase history and more—to deliver highly personalized product suggestions ### Merchandising Offers open-box controls—boost, bury, pin, slot, sort, include/exclude, —so merchants can blend manual strategies with AI-driven rankings for precise, context-aware product placement. Our strategic merchandising tools allow them to apply their expertise, insights, and business priorities on top of automated AI, all with just a few clicks. Here is a pin rule that is configured on the Experro Admin Panel. Here is the corresponding search result for the configured rule on the storefront.
### Smart Facets Facets are a fundamental component of eCommerce experiences, enabling shoppers to filter products within search results or category pages and find the items that best match their interests. Experro Discovery empowers brands to create more powerful, customized, and engaging filtering experiences, surpassing the limited features available on typical eCommerce platforms. These intuitive filters—by price, color, size, or any merchant-defined attribute allow to quickly narrow large result sets. ### Insights & Analytics Built-in dashboards track query performance (impressions, zero-result rates), top searches, filter usage, and conversion metrics—empowering merchants to see what’s working, spot gaps, and fine-tune search and merchandising strategies for maximum ROI. ### Collections Curate dynamic, theme-driven product assortments—seasonal bundles, editorial picks, or promo sets—and seamlessly insert them into search results or category pages. With simple rules or CSV uploads, you can tell cohesive shopping stories, boost cross-sells, and spin up or retire collections in minutes—no developer needed. Here, you can see a curated collection of formal shirts. This overview gives a snapshot of Experro Discovery’s capabilities, each feature working together to create a seamless, personalized, and high-impact shopping experience. By elevating discoverability, conversion, satisfaction, continuous optimization, and flexibility in one unified platform, Experro Discovery turns product discovery into your most powerful growth lever. For more detailed information on each component of Experro Discovery, please refer to the following sections: * [**Merchandising**](/experro_discovery/merchandising) * [**Search**](/experro_discovery/search) * [**Facets**](/experro_discovery/facets) * [**Insights & Analytics**](/experro_discovery/insights_and_analytics) # Putting it all together Source: https://help.experro.com/discovery_suite/putting_it_all_together/overview Experro Discovery transforms every touchpoint—Autocomplete, Search, Collections, Recommendations, Merchandising, and Analytics—into a single, seamless journey that guides shoppers from first click to final purchase. Rather than siloed modules, each feature feeds into the others, creating a continuously learning ecosystem where every action refines relevance, personalization, and profitability. ## The Unified Discovery Flow A shopper starts typing or drops in a photo; Autocomplete suggests complete queries, product names, and categories in real time, reducing friction and driving engagement. The visitor submits a query—whether “patio chairs,” “boho lamp,” or an uploaded image—and Experro Search harnesses deep semantic understanding plus live performance and personalization signals to deliver a ranked, relevance-first lineup. Immediately within those results, hand-picked Collections and targeted merchandising rules spotlight seasonal launches, promotional bundles, or hero SKUs—blending human insight with AI accuracy. Behind the scenes, known-user profiles and in-session behaviors continuously adjust rankings, so repeat customers see favorites while newcomers enjoy fresh, tailored assortments. On product detail pages, dynamic recommendation carousels (“You May Also Like,” “Complete the Look”) pull from the same signals, ensuring that discovery remains consistent whether through search or browsing. Every click, zero-result, and conversion funnels into Experro’s analytics dashboard—illuminating which queries underperform, which Collections resonate, and which merchandising tweaks deliver the biggest lift. ## A Day in the Life of Your Storefront Imagine a customer lands on your site hunting for “summer sandals.” They see Autocomplete prompt “women’s sandals,” “kids sandals,” and “leather sandals.” They select “leather sandals,” triggering Search to return top-selling, high-margin pairs first—alongside a curated “Festival Season Footwear” carousel and a personalized boost for eco-friendly brands. Clicking on a favorite sandal brings up a recommendation strip suggesting matching bags and accessories. Behind the scenes, Experro tracks every interaction—updating performance scores, refining session affinities, and feeding fresh data back into the ranking engine so that tomorrow’s shopper enjoys an even smarter experience. ## Continuous Optimization Loop * **Daily Calibration:** Regular syncs refresh product catalogs and regenerate embeddings, keeping search and Collections up to date with your latest inventory and pricing. * **Weekly Audits:** Merchandisers review zero-result searches and adjust synonyms or dictionary entries, ensuring no query falls through the cracks. * **Ongoing Experiments:** By spinning up alternative ranking strategies or A/B testing new Autocomplete boosts and merchandising rules, teams discover the highest-impact configurations before rolling them out more broadly. * **Seasonal Readiness:** Time-decay settings automatically elevate holiday, back-to-school, or summer promotions for defined windows—then gracefully retire them without manual intervention. Together, these orchestrated components make Experro Discovery more than a set of features—they become a self-optimizing engine that continually learns from your customers, aligns with your brand strategy, and drives measurable growth at every stage of the shopper journey. # Get the most out of Recommendations Source: https://help.experro.com/discovery_suite/recommendations/get_most_out_of_recos 1. **Align Algorithms to Context:** Choose “Frequently Bought Together” on product pages and “Popular Products” on homepages to match shopper mindset. 2. **Use Merchandising Overrides Sparingly:** Apply “boost” or “pin” rules for strategic SKUs (new launches or clearance) but let AI handle the bulk of ranking for agility. 3. **Monitor & Iterate:** Track click-through and add-to-cart rates per widget. Swap algorithms or adjust rule weights based on performance insights. 4. **Combine Static and Dynamic:** Pair AI-generated lists with hand-picked hero SKUs in a single carousel to blend data-driven relevance with editorial curation. 5. **Schedule for Seasonal Campaigns:** Use scheduled widgets to automatically surface holiday gift guides or limited-time collections without manual intervention. # Overview Source: https://help.experro.com/discovery_suite/recommendations/overview Experro’s Recommendations system empowers merchants to deliver deeply personalized, AI-powered product suggestions across the shopper journey—starting from the homepage and extending all the way to the cart page. With intuitive configurability, real-time intelligence, and robust algorithmic diversity, Recommendations in Experro is engineered to drive engagement, improve product discovery, increase AOV, and ultimately convert more shoppers. At the heart of Experro Recommendations lies **Eywa**, our proprietary AI engine. Eywa blends **Generative AI models**, **contextual understanding**, and **real-time behavior analytics** to predict and surface the most relevant products for each shopper. It doesn't just match keywords—it interprets **shopping intent**, detects micro-patterns in behavior, and uses **semantic understanding** to serve highly accurate and meaningful suggestions. ## Why Use Recommendations? Modern shoppers—especially Millennials and Gen Z—expect shopping experiences to feel like personalized feeds. Whether they’re exploring the homepage or returning to complete a purchase, they want suggestions that resonate. Experro helps you deliver that: * **Re-engage visitors** with reminders of previously viewed but unpurchased products on the homepage. * **Reduce PDP bounce rates** with similar products that keep shoppers exploring. * **Maximize cart value** by suggesting cross-sell items like accessories or warranties at checkout. * **Create sticky, high-converting experiences** with AI-powered discovery moments embedded across your storefront. ## Key Capabilities ### GenAI-Powered Recommendations Experro’s recommendations are powered by **Generative AI** and advanced machine learning models, providing highly relevant product suggestions tuned to customer preferences, trends, and behavioral signals. ### Real-Time Personalization Recommendations adapt instantly based on real-time user signals—including browsing history, searches, filter usage, and cart behavior—ensuring **context-aware discovery** across every digital touchpoint. ### Advanced Intelligence & Insights Leverage **in-depth analytics and recommendation intelligence** to refine strategies, track impact, and uncover shopper trends. Optimize performance with precision using the built-in Recommendations Dashboard. ### Plug & Play Widgets Get up and running in minutes—**no coding required**. Experro’s prebuilt, customizable widgets allow you to plug intelligent recommendations into any page—homepage, PDPs, category listings, or checkout. ### Omnichannel Ready Take recommendations beyond the storefront—**email campaigns and in-store kiosks** can also be powered by the same AI-backed engine for a consistent and tailored experience. ## Available Algorithms Experro offers one of the **widest arrays of recommendation algorithms** in the market. Each is purpose-built to support key stages of the shopper journey—discovery, exploration, decision-making, and retention. | Algorithm Name | Use Case | | ---------------------------- | ------------------------------------------- | | Recommended For You | Personalized suggestions based on browsing | | Frequently Bought Together | Smart cross-sell based on purchase behavior | | Frequently Viewed Together | Behavioral co-viewed products | | Similar Products | Alternatives to the current product | | Popular Products | High-performing, trending items | | Hot New Releases | Fresh arrivals, new collections | | Best Sellers | Most purchased products | | Recently Viewed | Continue exploring recent interests | | Recently Purchased | Easy reordering for returning users | | Pick-up Where You Left Off | Resume journey from last interaction | | Inspired by Browsing History | Pattern-matched recommendations | | Custom / Query-Based | Business-defined or custom algorithm output | Each of these algorithms is fully configurable and can be **plugged into recommendation widgets** anywhere across your storefront. With Experro Recommendations, you don’t just suggest products—you guide, inspire, and convert shoppers with precision and relevance, powered by cutting-edge AI. # Recommendation Examples Source: https://help.experro.com/discovery_suite/recommendations/reco_examples Below are two in-depth examples illustrating how Experro Recommendations elevate key touchpoints—turning routine interactions into revenue-driving moments. ## Cross-Sell at Checkout **Scenario:** A shopper adds a digital camera to their cart but hasn’t yet picked up essential accessories. 1. **Contextual Trigger:** As soon as the “Add to Cart” button is clicked, Experro’s “Frequently Bought Together” algorithm kicks in. It analyzes both your store’s historical purchase data and the customer’s own browsing session to identify the most complementary items. 2. **Dynamic Widget Display:** A compact carousel appears in the cart sidebar showing three to five high-impact accessories—lenses, tripods, memory cards, or camera bags—each with a thumbnail, title, price, and quick “Add” button. 3. **Personalization Layer:** If the shopper previously viewed or added certain accessories (e.g., a specific tripod model), those items receive a slight boost in the carousel ordering. New, high-margin products you want to promote can also be pinned to the front. 4. **Seamless Experience:** No page reloads are required. As the customer toggles between cart and product pages, the carousel stays in sync with their chosen camera model, ensuring suggested items always match the exact SKU variant. 5. **Business Impact:** * **Average Order Value Uplift:** Customers frequently add at least one accessory, increasing cart totals by 15–30%. * **Reduced Purchase Friction:** By presenting the right items in context, you eliminate the need for customers to hunt across menus or search again—shortening the path to a larger, more complete purchase. ## Homepage “Trending Now” **Scenario:** A visitor lands on your homepage looking to browse what's popular right now. 1. **Real-Time Popularity Data:** Experro tracks product impressions, clicks, add-to-cart events, and revenue in real time. Every hour, your “Popular Products” list refreshes to reflect the latest shopper behavior—so if a new sneaker launches this morning and sells out three times over lunchtime, it will surge to the top by afternoon. 2. **Behavioral Context:** For known shoppers, Experro blends overall popularity with category affinities. A visitor who normally browses women’s activewear will see trending leggings and sports bras, while a general visitor sees a broader mix of best-sellers across all categories. 3. **Widget Presentation:** On the homepage hero or a mid-page carousel, the “Trending Now” section displays 8–12 items in a scrolling strip. Each tile includes a “Hot” badge for new best-sellers, a thumbnail, dynamic pricing (e.g., “20% off today”), and a quick-view option. 4. **Strategic Merchandising Overlay:** Merchants can temporarily pin a strategic push—say, a limited-edition collaboration shoe—so that even if it hasn’t yet amassed high sales, it still appears among trending items for a set period. Time-decay rules ensure this pin automatically releases after the promotion ends. 5. **Business Impact:** * **Increased Engagement:** Visitors are 25% more likely to click into a product when they see it marked as “Trending,” driving deeper browsing. * **Social Proof & Urgency:** Badges like “Top Seller” or “New Arrival” combine with live data to create urgency, boosting conversion rates by up to 12% on featured items. These detailed examples show how Experro Recommendations not only deliver relevance through AI but also layer in personalization and strategic control—turning routine moments into powerful drivers of revenue and customer loyalty. # Natural Language Processing Source: https://help.experro.com/discovery_suite/search/core_concepts/nlp Experro transcends basic keyword matching by using advanced NLP to understand conversational intent and context. Whether a shopper types “best waterproof boots for winter hiking” or “what dresses work for a summer wedding,” Experro’s LLM-powered engine interprets the full meaning of the request—not just isolated keywords—and returns precisely ranked results that align with the shopper’s real need. **Key differentiators include:** * **Contextual Understanding:** Experro’s NLP doesn’t merely parse terms; it deciphers the context behind them, handling slang, modifiers, and multi-part questions much like a human expert would. * **Multimodal Relevance:** Text and image embeddings coexist in the same vector space, so visual cues (like fabric texture or pattern) combine seamlessly with textual intent to boost relevance on every query. * **Accuracy & Speed at Scale:** Optimized vector indexes and real-time signal processing ensure that even the most complex, long-tail or conversational searches return instant, hyper-relevant results—no matter how large your catalog grows. By marrying deep semantic parsing with lightning-fast retrieval, Experro makes every conversational or long-tail query a high-precision discovery moment—driving engagement, reducing zero-result rates, and ultimately boosting conversion. **What makes Experro’s NLP special?**\ • It understands multi-part questions, slang, and modifiers.\ • It blends text and image signals in a unified vector space.\ • It processes complex queries in milliseconds, regardless of catalog size. # Semantic vs Keyword Search Source: https://help.experro.com/discovery_suite/search/core_concepts/semantic_vs_keyword Experro offers two distinct search modes tailored to different use cases: | Feature | AI Search (Keyword Search) | Gen-AI Search (Semantic Search) | | ----------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Core Approach** | Direct term matching against titles, descriptions, and tags | Vector-based intent matching that understands meaning and context | | **Control & Precision** | Exact control over which terms match; ideal for precise, governed setups | Automatic handling of synonyms, slang, and higher-level concepts without manual rules | | **Query Handling** | Fuzzy matching (typo tolerance), prefix/suffix options, custom synonyms, stop-words, and phrase rules | Holistic interpretation of long-tail and conversational queries (“cozy winter boots”), as well as pure-image inputs | | **Multimodal Capabilities** | Text-only search | Unified vector space for text + images—mix keywords, questions, or uploads seamlessly | | **Maintenance & Tuning** | Requires ongoing manual tuning of synonyms, dictionaries, and phrase lists | Self-learning model that adapts to new products, trends, and visual styles with zero manual effort | | **Performance & Scalability** | Lightweight footprint; predictable latency; suited for smaller catalogs or lower-traffic sites | Optimized for large, dynamic catalogs; minimal performance impact thanks to precomputed embeddings | | **Best-Fit Scenarios** | Controlled environments requiring exact matches or strict governance | Ambitious brands needing richer relevance, zero-maintenance synonym management, and cutting-edge multimodal discovery | **When to Use Which Mode** * Start with **Keyword Search** for controlled, exact matches and minimal overhead. It’s a solid choice for smaller catalogs or when you need tight governance over term handling. * Upgrade to **Semantic Search** to unlock powerful Gen AI-driven discovery: richer relevance, true multimodal queries, and zero-maintenance synonym management—ideal for ambitious brands seeking a competitive edge. # Get the most out of Search Source: https://help.experro.com/discovery_suite/search/get_most_out_of_search Welcome to your quick-start guide for supercharging Experro Search. Each of these proven best practices turns your search into a high-conversion engine. ### Audit & Resolve Zero-Result Queries Regularly review queries that return no results and prioritize them by search volume. Zero-result searches often indicate missing synonyms, phrase gaps, or unmapped attributes. By adding targeted synonyms, dictionary entries, or related content, you can capture stranded intent and reduce bounce rates from “no results” pages. ### Enable Visual Discovery Equip your search bar with an ability to allow shoppers to upload images. Pure-image search provides instant, visually similar product matches—ideal for fashion, home décor, or gift inspiration. ### Balance Semantic & Keyword Modes Deploy semantic (Gen-AI) search on high-traffic, long-tail queries—where deep intent understanding boosts relevance—and fallback to lightweight keyword (AI) search for simple, low-volume lookups. This hybrid approach preserves performance while capturing nuance. ### Optimize Field Weights Identify your most influential attributes—such as brand, category, or material—and amplify their importance in the index. Adjusting field weights ensures that results favor these high-value dimensions, aligning search outcomes with customer priorities. ### Apply Seasonal & Time-Decay Rules Use time-decay boosts and demotions to highlight seasonal collections, flash sales, or holiday promotions. These overrides automatically expire after a set period, keeping search results fresh without manual cleanup. ### Optimize Autocomplete Performance Ensure your autocomplete dropdown appears instantly to guide shoppers toward popular and high-value terms as they type. Quick, relevant suggestions reduce friction and increase usage of your search bar. ### Conduct Ranking Experiments Create multiple ranking strategies and run A/B tests on specific categories or visitor segments. Measure lifts in conversion rate, add-to-cart actions, and average order value to identify your most effective ranking mix before rolling changes site-wide. ### Design a Prominent Search Interface Position a large, clearly labeled search box at the top of every page. A highly visible search bar invites use, reduces frustration, and encourages shoppers to express their intent directly. ### Leverage Analytics & Feedback Loops Use built-in dashboards to monitor zero-result rates, click-through patterns, and filter usage. Feed these insights back into your search configuration—updating synonyms, adjusting boosts, and refining field weights to continuously sharpen relevance. ### Keep Your Search Engine Current Automate regular syncs of your product catalog—new SKUs, price changes, and inventory updates—and regenerate embeddings on a regular cadence. A fresh index ensures shoppers always see up-to-date availability and pricing. By applying these best practices, you’ll transform Experro Search into a self-optimizing, insight-driven discovery engine that consistently delivers the right products at the right moment—boosting engagement, conversions, and customer satisfaction. # How Experro Search Works Source: https://help.experro.com/discovery_suite/search/how_experro_search_works At its core, Experro Search transforms raw product data and customer interactions into an ever-smarter discovery engine. Here’s an end-to-end look at what happens behind the scenes: Experro connects directly to your backend (Shopify, BigCommerce, custom API) and ingests every product record—titles, descriptions, metadata, and image variants—in real time. New SKUs, price changes, or inventory updates appear in search results almost instantly. * **Text Embeddings:** Every word in your product titles, descriptions, and tags is converted into a high-dimensional vector that captures meaning, context, and relationships. * **Image Embeddings:** Variant images (colors, patterns, textures) are passed through specialized vision models to produce vectors that align with the text embeddings—so visual cues carry equal weight in your search. * **Industry-Specific Training:** Embedding models are fine-tuned on fashion, home decor, electronics, or other verticals to maximize relevance for your catalo Both text and image vectors live side-by-side in the same index. A single query—whether typed, spoken, or uploaded as a photo—hits this combined space, enabling true cross-modal matches. Every shopper action (impression, click, add-to-cart, purchase) is streamed back into Experro. These live signals continuously retrain our ranking algorithms, so the products that perform best—both overall and within each query context—naturally rise to the top. For each query, Experro computes: * **Relevance Score:** Semantic proximity between query and product embeddings * **Performance Score:** Real-time engagement metrics for that query * **Personalization Score:** Known-user affinities + anonymous session signals * **Merchandising Overrides:** Any merchant-defined boosts, pins, or exclusions\\ These factors blend via a configurable algorithm to produce one definitive, optimized result list—delivered in milliseconds. You can tune the weight of each component in “Ranking” under "Algorithm" via your Experro Admin Panel if you want to prioritize, say, performance signals over pure semantic relevance. Even if you don’t have rich clickstream data yet, Experro will gracefully fall back to its semantic vector search and keyword-matching layers—so your search is always fast and accurate. # Overview Source: https://help.experro.com/discovery_suite/search/overview Experro Search is the gateway to your catalog—part of our unified Discovery Suite—delivering instant, hyper-relevant results that power revenue and delight shoppers. By blending multimodal retrieval (text + image), deep semantic relevance, real-time performance signals, and personalization affinities, Experro Search handles everything from quick keyword lookups to nuanced, conversational queries and pure-image searches. ### Key Capabilities * **Instant, Contextual Relevance** Leveraging our semantic engine, Experro returns curated matches in milliseconds—so whether a customer types “running shoes,” “trail hiking boots,” or uploads a photo of their favorite sneaker, they see the most relevant items first. * **Effortless Synonyms & Concept Matching** Embedded NLP automatically equates terms like “tee,” “t-shirt,” and “graphic tee,” and recognizes high-level concepts such as “bohemian dress” or “mid-century chair,” requiring zero manual synonym or dictionary setup. * **True Multimodal Search** Text and images share the same high-dimensional vector space, enabling mixed queries—“blue floral dress” plus a pattern photo—to deliver precise results even when your product metadata is incomplete. * **Long-Tail & Conversational Queries** Deep language understanding parses complex requests—“what coats work for damp spring mornings?” or “best laptop bags under \$100”—returning relevance-ranked results that capture shopper intent, not just keywords. With Experro Search at the heart of our Discovery Suite—backed by performance-driven ranking, one-to-one personalization, and flexible merchandising controls—every visit becomes an opportunity: customers find and engage with your best products faster, and your storefront continually optimizes itself for growth. # Results Ranking Source: https://help.experro.com/discovery_suite/search/results_ranking Experro’s ranking engine blends four distinct score components into a single, optimized ordering—ensuring shoppers see the most relevant, high-performing, personalized, and strategically placed products first. This holistic approach balances customer intent with business goals in real time. ### Relevance Scoring Instead of simple keyword matches, Experro measures deep semantic similarity between the user’s query and each product’s embeddings (Image +Text). This ensures that results align with meaning, style, and visual cues—so “leather biker jacket” returns genuine matches, even if your catalog uses “motor coat.” ### Performance-Based Ranking Live engagement metrics—impressions, clicks, add-to-carts, purchases, and revenue—are continuously scored within each query context. Products that resonate most with shoppers for a given search organically climb higher over time, turning customer behavior into an ever-improving ranking signal. ### Merchandising Controls Merchandising rules layer on top of AI-generated scores to reflect strategic priorities: * **Boost & Bury:** Amplify new arrivals or suppress low-margin/clearance items. * **Pin & Slot:** Fix products in a specific position or within a defined range. * **Include/Exclude:** Force items into or out of the result set. ### Personalization Scoring Experro personalizes ordering by blending two affinity signals: * **Known-User Profiles:** Leverage historical behavior (past purchases, wishlists) tied to logged-in customers. * **Anonymous Session Signals:** Capture live interactions (clicks, filters, dwell time) to form a real-time session profile.\ By combining long-term and in-session data, Experro delivers one-to-one relevance—ensuring first-time visitors and loyal customers alike see products tailored to their preferences. ## Why It Matters This dynamic, multivariate ranking ensures that shoppers never have to dig through irrelevant items. They see the right products first—driving higher engagement, faster conversions, and stronger alignment between your merchandising strategy and real customer intent. # Create an A/B Test Source: https://help.experro.com/experiments/a_b_testing/create_an_ab_test An A/B test splits a fixed share of your traffic across a control group and up to three variants, then measures which one performs best. This guide walks the full flow, from the create button to a live experiment. ## Prerequisites * Permission to manage experiments in the workspace. * At least one channel and language configured. * The pages, components, algorithms, or merchandising rules you want to test, each with variants already defined. ## Create the Experiment On the Experiments list, click **Create Experiment**, then choose **A/B Test** in the Select Experiment Type dialog. Give the experiment a name, then select a **Channel** and a **Language**. Observation and hypothesis are optional but worth writing — they record why you ran the test. Click **Create & Continue**. This saves the experiment as a draft. Add one primary metric. This is the KPI that decides the winner. Add secondary metrics to watch for side effects. Decide who enters the experiment and what share of them take part. Pick a start date. Optionally add an end date, an event count limit, and email recipients to notify when the test finishes. Add your variants and set the split. The total must equal 100%. Add the pages, components, algorithms, or rules you are testing, then map each one to a variant. Click **Start Experiment**, then confirm the prompt to publish the associated records. **Start Experiment** stays disabled until you complete the Details step. Its tooltip reads "To start the experiment, first add the experiment details and create it." ## If Validation Fails Experro checks every step when you start the experiment. If something is missing, a red icon appears beside the affected step in the **Configurations** rail and the message "Please enter all the required fields" appears at the top of the screen. Use the rail as a checklist. A green check means the step is complete. You can click **Save** at any point, even with required fields empty. Saving keeps the experiment as a draft so you can come back to it. ## Key Considerations * After you save the Details step, **Channel** and **Language** become read-only. * Every experience you add must be mapped to a variant before the experiment can start. ## What's Next * [Details](/experiments/a_b_testing/details) * [Metrics](/experiments/a_b_testing/metrics) * [View Experiment Results](/experiments/analytics/overview) # Details Source: https://help.experro.com/experiments/a_b_testing/details Details is the first step of the A/B test flow and the only one you must complete before the experiment exists. Saving this step creates the draft. ## Configuration Details | Field | Required | Description | | ------------------- | -------- | ----------------------------------------------------------------- | | **Experiment Name** | Yes | A name for the experiment. Names do not have to be unique. | | **Observation** | No | What you noticed that prompted the test. Up to 10,000 characters. | | **Hypothesis** | No | What you expect the change to do. Up to 10,000 characters. | | **Channel** | Yes | The channel the experiment runs on. | | **Language** | Yes | The language the experiment runs in. | ## Why Observation and Hypothesis Matter These two fields are optional, but they turn a test into a record others can learn from. Six months later, the numbers alone rarely explain why anyone ran the test. Write the observation as something you measured: > Many users add products to the cart but do not complete the checkout process. Write the hypothesis as a prediction you can falsify: > Simplifying the checkout steps will reduce friction and increase completed purchases. ## Key Considerations * **Channel** and **Language** decide which pages, components, algorithms, and rules appear later on the **Experience** step. Choose them carefully. * Once you save this step, both fields become read-only. To change them, clone the experiment and start again. * If the workspace has only one channel and one language, both fields are hidden and applied automatically. You cannot move past Details until the name, channel, and language are set. ## What's Next * [Metrics](/experiments/a_b_testing/metrics) # Duration Source: https://help.experro.com/experiments/a_b_testing/duration Set when the experiment starts, how it stops, and who gets notified when it finishes. Duration controls the experiment's running window. Set a start date, and either an end date or nothing at all — an experiment with no end date runs until you end it manually. ## Configuration Details | Field | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------- | | **Start Date** | Yes | When the experiment begins. A future date schedules it. | | **End Date** | No | When the experiment stops. Leave empty to run indefinitely. | | **Email Notification** | No | Addresses to notify when the experiment completes. | ## Email Notification Start typing a name or address and Experro suggests matching users. To notify someone outside the workspace, type the full address and press **Enter**. You can add as many recipients as you need. Badly formatted addresses are rejected with an inline message. ## Key Considerations * **Start Date** and **End Date** are a single linked range. The end date must fall after the start date. * If no end date is set, the experiment runs until you end it manually. Results show `∞ days` in place of a countdown. * A draft whose end date has already passed cannot be started until you move the date forward. Leave a gap of more than three minutes between the start and end dates. The scheduler runs every three minutes, and a shorter window may never publish. ## What's Next * [Variants](/experiments/a_b_testing/variants) # Experience Source: https://help.experro.com/experiments/a_b_testing/experience An experience is a concrete thing a visitor sees — a specific page version, component, search algorithm, or merchandising rule. This step connects your abstract variants to those real objects. Until you map experiences, variants are only percentages. Mapping gives each group something to actually experience. ## Add an Experience Click **Add Experience(s)** and choose a type. Only records that already have variants appear for selection. Variants are authored in the module the record belongs to, not here — so create them before you reach this step. | Type | What you map | Where you create the variants | | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Web Pages** | Page records that act as web pages | [Creating a New Variant](/content/content_library/creating_a_new_variant) | | **Components** | Component records | [Creating a New Variant](/content/content_library/creating_a_new_variant) | | **Algorithms** | Search ranking algorithms | [Algorithm Variants](/experro_discovery/search/algorithm_field_settings_catalog_settings/algorithm#variants) | | **Merchandising** | Merchandising rules | [Creating a New Variant](/experro_discovery/merchandising/creating_a_new_variant) | Each type can be added once. Selected types are removed from the dropdown. ## Map Variants Adding a type opens a selection dialog. Search for the records you want, filter by content model where available, and add one or more. Each added row then gives you two things to set: 1. A **Version** — defaults to the published version, or the latest version if none is published. 2. A variant mapping — which internal variant of that record maps to which experiment variant. The column header for each variant shows its traffic allocation, so you can see the split while you map. ## Key Considerations * Web pages must be enabled to act as web pages. * Visibility of algorithms and merchandising rules depends on your plan. If your plan does not include Discovery, those types will not appear. Every experience must have a version and a variant mapping before the experiment can start. You can save an incomplete mapping, but you cannot launch with one. Starting an experiment prompts you to publish the associated records. The experiment only begins after you confirm. ## What's Next * [View Experiment Results](/experiments/analytics/overview) # Metrics Source: https://help.experro.com/experiments/a_b_testing/metrics Metrics define what success means for the experiment. Experro measures every variant against the metrics you set here and uses the primary metric to decide the winning variant. ## Primary and Secondary Metrics A **primary metric** is the single KPI the experiment is designed to move. It determines the winner, so pick the one that maps most directly to the business outcome you care about. Exactly one is required. **Secondary metrics** are tracked alongside it. They explain how and why the primary moved, and they catch damage elsewhere in the funnel. They never decide the winner. Suppose add to cart is your primary metric. Revenue and checkout rate make good secondary metrics — more carts only help if they convert and order value holds. ## Configuration Details Each metric has two fields. Both are required. | Field | Description | | ---------------- | --------------------------------------------------------- | | **Metric Name** | A label for reports. Free text. | | **Metric Event** | The event this metric measures. Choose from the dropdown. | ## Choosing a Metric Event **Metric Event** opens a two-part list. **Ready to Use** holds prepared business metrics. **All Events** holds the raw storefront events your site sends. Tabs at the top filter between the two. | Group | Options | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ready to Use** | Average Order Value, Bounce Rate, Total Revenue, Units Sold | | **All Events** | Cart Viewed, Category Viewed, Checkout Completed, Checkout Initiated, Collection Viewed, Component Clicked, Component Viewed, Page Leave, Page View, Product Added to Cart, Product Removed from Cart, Product Searched, Product Searched Zero Result, Product Variant Viewed, Product Viewed | Pick the event that reflects what you are changing. A checkout redesign is measured on Checkout Completed. A merchandising change is measured on Units Sold. **Metric Name** is a label only. It does not have to match the event you choose, so name it for the question you are answering. Keep secondary metrics to the few that would genuinely change your decision. A long list makes results harder to read, not richer. ## What's Next * [Target Audience](/experiments/a_b_testing/target_audience) # Target Audience Source: https://help.experro.com/experiments/a_b_testing/target_audience Target Audience controls entry to the experiment. It answers two separate questions: who is eligible, and how many of the eligible actually take part. ## Targeting Choose one of two options. **All Visitors** makes every visitor eligible. This is the default and the right choice for most tests. **Condition Based Target** narrows eligibility using audience segments, UTM parameters, locations, or device types. See [Condition Based Targeting](/experiments/targeting/condition_based_targeting). ## Traffic Allocation Traffic allocation sets the percentage of eligible visitors who enter the experiment, from 1 to 100. It defaults to 100. Lower it when you want to limit exposure — a risky change might start at 10% while you watch for problems. ## How Targeting and Allocation Combine The two settings apply in order. Targeting runs first and produces the eligible pool. Traffic allocation then takes a percentage of that pool. Suppose 1,000 visitors arrive: 1. Targeting restricts the experiment to US visitors, leaving 500 eligible. 2. Traffic allocation is set to 50%, so 250 visitors enter the experiment. 3. Those 250 are then split across the control group and variants on the **Variants** step. The remaining 750 visitors never enter the experiment and see your live experience. Traffic allocation on this step controls entry to the experiment. The split between the control group and each variant is set separately on the **Variants** step. ## Key Considerations * Values of zero or below are corrected to 1. * Narrow targeting reduces the traffic reaching your test, which lengthens the time needed for a reliable result. ## What's Next * [Condition Based Targeting](/experiments/targeting/condition_based_targeting) * [Duration](/experiments/a_b_testing/duration) # Variants Source: https://help.experro.com/experiments/a_b_testing/variants Variants sets the shape of the test — how many versions you are comparing and what share of traffic each one receives. What each variant actually shows is configured later, on the **Experience** step. ## Define Variant Traffic Allocation Every A/B test includes a **Control Group**. The control is your existing experience and the baseline every variant is measured against. It cannot be removed. Add variants with **Add Variant**. The experiment supports four in total, including the control group. | Element | Behavior | | ---------------------- | ----------------------------------------------------- | | **Variant Name** | Control Group, Variant A, Variant B, Variant C. | | **Traffic Allocation** | The share of entering traffic this variant receives. | | **Delete** | Removes a variant. Unavailable for the control group. | | **Add Variant** | Disabled once four variants exist. | ## How the Split Works On first load the experiment starts at 50% control and 50% Variant A. Adding a variant redistributes traffic equally, and you can then set each share by hand. The total must equal 100%. **Total Allocation** turns red when it does not, and the experiment cannot start. ## Worked Example Carrying on from [Target Audience](/experiments/a_b_testing/target_audience), 100 visitors enter the experiment. With four groups at 25% each: * Control Group — 25 visitors * Variant A — 25 visitors * Variant B — 25 visitors * Variant C — 25 visitors ## Key Considerations * At least one variant besides the control group is required. * The allocation you set here applies to every experience type in the experiment. More variants split your traffic thinner, so each one takes longer to reach a trustworthy result. Two or three groups usually answer the question faster than four. Changing allocation after an experiment starts does not move visitors already assigned. New visitors are distributed until the split matches the new configuration. ## What's Next * [Experience](/experiments/a_b_testing/experience) # Experience Analytics Source: https://help.experro.com/experiments/analytics/experience_analytics Alongside **Traffic** and **Metrics**, the results screen shows one tab for each experience type in the experiment. Each tab starts with a selector so you can choose which page, component, algorithm, or rule to examine. ## Web Page Summary tiles cover **Total Visitors**, **New Visitors**, **Returning Visitors**, **Average Time on Page**, **Total Page Views**, **Unique Page Views**, **Exit Rate**, and **Bounce Rate**. Below the tiles: * **Variant Performance Over Time** — a chart for any tile metric, at daily, weekly, or monthly granularity. * **Metrics by Variant** — every tile metric broken out by group. * **Visitor by Device**, **Traffic by Location**, and **Traffic by Browser** — distributions per group. A few definitions worth knowing: | Metric | How it is measured | | ------------------------ | ------------------------------------------ | | **Returning Visitors** | Total visitors minus new visitors | | **Exit Rate** | Share of page views that ended the session | | **Bounce Rate** | Share of page leaves under ten seconds | | **Average Time on Page** | Total time on page divided by page leaves | ## Component Summary tiles cover **Component Impressions**, **Component Clicks**, and **Interaction Rate**, where interaction rate is clicks divided by impressions. The tab also breaks these out by variant, device, location, and browser. ## Search Algorithm Summary tiles cover **Search Views**, **Search Clicks**, **CTR**, **Add to Cart Rate**, **Total Orders**, **Avg. Order Value**, and **Total Search Revenue**. Below them sit a variant performance chart, a metrics-by-variant table, and a traffic-by-device table. ## Merchandising Summary tiles cover **Product Impressions**, **Product Clicks**, **Add to Cart Rate**, **Conversion Rate**, **Merchandising Revenue**, **Avg. Order Value**, and **Rule Hit Count**. Below them sit a variant performance chart and a metrics-by-variant table. ## Key Considerations * Tabs appear only for experience types included in the experiment. * The duration selector at the top applies across every tab. * Personalization experiments use the same layout without control group columns. Experience tabs describe how a specific page or rule performed. Use them to explain a result, not to decide the winner — that decision belongs to the primary metric on the **Metrics** tab. ## What's Next * [View Experiment Results](/experiments/analytics/overview) * [End an Experiment](/experiments/managing_experiments/end_an_experiment) # View Experiment Results Source: https://help.experro.com/experiments/analytics/overview Opening an experiment shows its results screen. A summary bar sits above a set of tabs — **Traffic** and **Metrics** always, plus one tab for each experience type in the experiment. ## The Summary Bar | Element | What it shows | | --------------- | ------------------------------------------------- | | **Channel** | The channel the experiment runs on | | **Language** | The language the experiment runs in | | **Time Period** | Days remaining until the end date | | **Status** | Draft, Scheduled, Published, Paused, or Completed | **Time Period** shows `∞ days` when no end date is set, and is hidden while the experiment is a draft. Ending an experiment early freezes both readings. An experiment ended with two days left permanently shows "2 days left" — a record of how early you stopped it. ## Traffic Tab **Traffic Allocation** compares the split you configured against what actually happened. | Column | Meaning | | ------------------- | ------------------------------ | | **Expected** | The percentage you configured | | **Actual** | The percentage actually served | | **Unique Visitors** | Distinct people | | **Visitors** | Total visits | Small gaps between expected and actual are normal. Large or persistent gaps are worth investigating before you trust the results. Below it, **Assigned Traffic** plots each group's share over time. ## Metrics Tab Metrics are split into **Primary Metrics** and **Secondary Metrics**, each showing one row per group. | Column | Meaning | | ----------------------- | ----------------------------------------- | | **Traffic Split** | The share of traffic this group received | | **Conversion/Visitors** | Conversions against visitors measured | | **Expected Conversion** | The conversion rate for this group | | **Improvement** | Relative change against the control group | The control group is marked with a lock icon and reads `Baseline` in every improvement column. Each variant is measured against it. **Lift** is the relative improvement of a variant over the control, calculated as `((VariantMetric - ControlMetric) / ControlMetric) * 100`. Below the tables, **Metrics Over Time** plots a selected metric for every group. Judge the winner on the primary metric. Secondary metrics tell you whether the win came at a cost elsewhere. Resist reading results in the first days of a test. Early numbers swing widely, and a variant that looks ahead on day two often finishes behind. ## What's Next * [Experience Analytics](/experiments/analytics/experience_analytics) * [End an Experiment](/experiments/managing_experiments/end_an_experiment) # Clone and Delete Experiments Source: https://help.experro.com/experiments/managing_experiments/clone_and_delete_an_experiment Cloning copies a configuration so you can run a follow-up test without rebuilding it. Deleting removes an experiment and everything it collected. ## Clone an Experiment Clone from the row menu on the Experiments list, or from the **Clone** button on the experiment's own screen. The clone opens as a new **Draft** with every setting copied — details, metrics, target audience, duration, variants, and experience mappings. Edit what you need, then save or start it. | Copied | Not copied | | ------------------------------- | ----------------------------- | | All configuration | Collected metrics and results | | Variants and traffic allocation | Start and end dates | | Experience mappings | Status | Experro confirms with "Experiment cloned successfully." Cloning is the fastest way to run a variation on a test you have already built — a second CTA wording, or the same test on another channel. ## Delete an Experiment Delete from the row menu, or from the **Delete** button on the experiment's screen. The confirmation depends on the status. **Published experiments** warn that configurations, variants, and collected metrics will be removed, and offer **Pause Experiment** as an alternative alongside **Cancel** and **Delete**. **Scheduled experiments** name the scheduled start date and warn that deleting cancels the run. **Draft and completed experiments** get a straightforward confirmation. ## Key Considerations * Published and paused experiments cannot be deleted while running. Pause or end them first. * Cloned experiments can share a name with the original. Names are not required to be unique. Deletion is permanent. Configurations, variants, and every metric collected are removed, and there is no undo. ## What's Next * [Pause an Experiment](/experiments/managing_experiments/pause_an_experiment) * [Manage Your Experiments](/experiments/managing_experiments/experiment_list) # End an Experiment Source: https://help.experro.com/experiments/managing_experiments/end_an_experiment An A/B test finishes in one of two ways: you end it yourself, or it reaches the end date you configured. Either way, the last step is the same — choose the winning variant. ## End an Experiment Manually Open the experiment and click **Configure Experiment**. The **End Experiment** button sits in the top-right controls. The Select Winning Variant dialog shows each group with its average value, total, and sessions. The variant with the highest average value is selected by default. Choose a different one if you want, or select **No winning variant** to close the test without declaring one. Click **End Experiment**. The status changes to **Completed**. ## When an Experiment Ends Automatically An experiment ends on its own when the end date arrives. Experro emails the recipients configured on the **Duration** step. The experiment then appears as **Completed** in the list with a caution icon beside its name, showing that it still needs a decision. Open it and you will see a banner: > The experiment has ended. Click Conclude Experiment to choose the winning variant and conclude the experiment. Click **Conclude Experiment** to open the same Select Winning Variant dialog and finish the process. ## After an Experiment Ends * Configuration becomes read-only. * **Pause** and **End Experiment** are removed. **Clone** and **Delete** remain. * Visitors previously enrolled see the control experience and become eligible for other experiments on their next visit. Personalization experiments cannot be ended manually. When they reach their end condition they return to **Draft** instead of completing. Ending an experiment is final. To keep collecting data, pause it instead. ## What's Next * [Clone and Delete Experiments](/experiments/managing_experiments/clone_and_delete_an_experiment) * [View Experiment Results](/experiments/analytics/overview) # Manage Your Experiments Source: https://help.experro.com/experiments/managing_experiments/experiment_list The Experiments list is the home screen for the module. It shows every A/B test and personalization experiment in the workspace, and it is where you start a new one. ## What You Can Do on This Page * **Search** — find an experiment by name. * **Filter** — narrow the list by channel, language, status, or type. * **Edit Columns** — show or hide the audit columns. * **Create Experiment** — start a new A/B test or personalization experiment. * **View Archived** — see experiments that are no longer active. * **Clone** or **Delete** — act on a single experiment from the row menu. ## Columns | Column | Description | | ------------------- | ----------------------------------------------------------------- | | **Experiment Name** | The name you gave the experiment. Names do not have to be unique. | | **Experiment On** | Web Pages, Components, Search Algorithm, or Merchandising. | | **Type** | A/B Test or Personalization. | | **Channel** | The channel the experiment runs on. | | **Language** | The language the experiment runs in. | | **Status** | Draft, Scheduled, Published, Paused, or Completed. | | **Created By** | The initials of the person who created it. | | **Action** | Opens the row menu. | Four more columns are available through **Edit Columns**: Created At, Created By, Modified At, and Modified By. They are hidden by default. ## Filtering and Searching Search matches on the experiment name only. It does not search descriptions or variant names. The four filters are multi-select, so you can combine them — for example, every published A/B test on your French channel. ## Row Actions Open the row menu to clone or delete an experiment. **Clone** opens the create flow with every setting copied across. Metrics and results are not copied, and the clone starts as a draft with its dates cleared. **Delete** asks for confirmation. What the confirmation says depends on the status. Deleting an experiment permanently removes its configuration, variants, and collected metrics. There is no undo. To stop a running experiment without losing its data, pause it instead of deleting it. ## What's Next * [Set Experiment Priority](/experiments/managing_experiments/experiment_priority) * [Clone and Delete Experiments](/experiments/managing_experiments/clone_and_delete_an_experiment) # Set Experiment Priority Source: https://help.experro.com/experiments/managing_experiments/experiment_priority A visitor can only be assigned to one experiment at a time. When several experiments target the same visitor, priority order decides which one applies. ## Reorder Experiments On the Experiments list, click the reorder icon in the top-right corner. Its tooltip reads "Adjust the order of experiments to set their priority." A banner explains the rule: "The order of experiments determines priority. When a user qualifies for multiple experiments, the one listed higher will be applied first." Drag rows by their handle to reposition them. Click **Save**. Experro confirms with "Experiment order saved successfully." **Cancel** discards the change. ## How Priority Is Applied When a visitor arrives, Experro checks whether they are already assigned to an experiment. If not, it works down the list and assigns them to the first experiment whose targeting they match. Priority is evaluated at runtime, so changing the order changes future assignments. ## How Each Type Behaves **A/B tests hold their assignment.** Once a visitor is placed in a variant, they keep seeing it on every subsequent visit, even if their context changes. This consistency is what makes the results statistically meaningful. **Personalization responds to context.** A visitor who arrives from a different campaign or location can move to a different variant, because relevance matters more than consistency. ## Impact on Results Priority affects far more than which page renders. * Experiments lower in the order receive only visitors not claimed by higher ones. * Reduced traffic means a smaller sample, which lengthens the time needed to reach a reliable result. * An experiment starved of traffic collects too little data to produce a readable result. Reordering a running experiment changes its traffic mid-flight. Where possible, set priority before experiments start. When two experiments target the same page, the published version in the content library determines what is served. If you pause the higher-priority experiment, republish the version used by the remaining experiment from the content library. ## What's Next * [Manage Your Experiments](/experiments/managing_experiments/experiment_list) * [Condition Based Targeting](/experiments/targeting/condition_based_targeting) # Pause an Experiment Source: https://help.experro.com/experiments/managing_experiments/pause_an_experiment Pausing stops an experiment from serving variants while keeping everything else intact. Use it when you need to halt a test quickly — a problem on the site, a pricing change, or a campaign that has to take priority. ## When Pause Is Available The **Pause** button appears in the header when the experiment is **Scheduled** or **Published**. It is hidden in every other state. ## Pause the Experiment Click the experiment on the Experiments list to open its results screen, then click **Configure Experiment**. A confirmation dialog explains what pausing does. For an A/B test: "Pausing this test will stop all traffic distribution across variants. Visitors will only see the control group experience until the experiment is resumed." For a personalization experiment: "Pausing this experiment will temporarily stop all personalized experiences. Users will see the default experience until the experiment is resumed." Click **Pause Experiment**. Traffic distribution stops immediately. ## What Happens to Enrolled Visitors Visitors already assigned to the experiment stay assigned. They see the control experience for as long as the pause lasts, then return to their assigned variant when you resume. Their assignment is not lost, so resuming does not restart your sample. ## Resume the Experiment Click **Start Experiment** to resume. * If the end date is still in the future, the experiment returns to **Published** and data collection continues. * If the end date has already passed, the experiment moves to **Completed**. Metrics collected before the pause are preserved. Configuration is preserved exactly as you left it. All fields remain populated when you resume. If you are considering deleting a running experiment, pause it instead. Deleting destroys the collected metrics permanently. ## What's Next * [End an Experiment](/experiments/managing_experiments/end_an_experiment) * [Experiment Statuses](/experiments/overview/experiment_statuses) # Experiment Statuses Source: https://help.experro.com/experiments/overview/experiment_statuses Understand the lifecycle states an experiment moves through, from draft to completed, and what triggers each transition. Every experiment carries a status that tells you whether it is running, waiting to run, or finished. Status also controls what you can do to the experiment — a published experiment cannot be edited or deleted, but it can be paused. ## Status Definitions | Status | What it means | How it gets here | | ------------- | --------------------------------------------------- | ----------------------------------------------------------------------- | | **Draft** | Saved but never started. | You click **Save** without starting, or you pause a running experiment. | | **Scheduled** | Started, but the start date is still in the future. | You click **Start Experiment** with a future start date. | | **Published** | Live and collecting data. | The start date arrives, or you start an experiment dated today. | | **Completed** | Finished collecting data. | The end date arrives, or you end it manually. | | **Paused** | Temporarily stopped. | You click **Pause** on a scheduled or published experiment. | ## How Statuses Change A scheduled experiment becomes published automatically. Experro checks for due experiments every three minutes. Resuming a paused experiment sends it back to **Published** if the end date is still in the future. If the end date has already passed, it moves straight to **Completed**. ## Key Considerations * Published, paused, and completed experiments are read-only. Clone the experiment to make changes. * Published and paused experiments cannot be deleted. Pause first, or end the experiment. * Cloning always produces a draft, with the start and end dates cleared. A draft whose end date has already passed cannot be started. Update the end date to a future date first, or the system rejects the start. Because the scheduler runs every three minutes, an experiment whose start and end dates are less than three minutes apart may never publish. Widen the window and start it again. ## What's Next * [Manage Your Experiments](/experiments/managing_experiments/experiment_list) * [Pause an Experiment](/experiments/managing_experiments/pause_an_experiment) * [End an Experiment](/experiments/managing_experiments/end_an_experiment) # Experiments Overview Source: https://help.experro.com/experiments/overview/overview Run A/B tests to find what performs best, and personalization experiments to serve each audience the experience that suits them. Experiments let you change your storefront on evidence rather than opinion. Instead of debating which headline, layout, or ranking algorithm works better, you serve different versions to real visitors and measure what happens. The module contains two experiment types. They share most of their configuration and reporting, but they answer different questions. ## The Two Experiment Types Split traffic across a control group and up to three variants by fixed percentages, then measure which one performs best. **Answers:** which version wins? Give each variant its own audience, and serve every visitor the version that matches them. **Answers:** which version suits this visitor? Both run through the same step-by-step configuration flow and share their reporting. Where they differ: | | A/B Testing | Personalization | | ------------- | ------------------------------------------------- | -------------------------------------------- | | Control group | Always present | None | | Traffic | Divided across the control group and each variant | One figure for the whole experiment | | Targeting | One audience for the whole test | One target type, with values set per variant | | Details | Includes Observation and Hypothesis | Neither field appears | | Use it to | Decide what to roll out | Tailor what each segment sees | An A/B test is a decision you make once and apply to everyone. Personalization is a decision you make repeatedly, per visitor. ## What You Can Experiment On Both types target the same four experience types, and one experiment can include more than one. | Experience | What you test | | ----------------- | -------------------------------------------------------------- | | **Web Pages** | Versions of a page, such as a new hero layout or CTA color | | **Components** | Versions of a reusable component, such as a promotional banner | | **Algorithms** | Ranking configurations for search results | | **Merchandising** | Product ordering and merchandising rules | ## Use Cases ### A/B Testing **Validate a conversion hypothesis.** Your add to cart rate sits at 1.8% against an industry benchmark of 3.0%, and you suspect the CTA button. Test the current blue button against orange, with add to cart as your primary metric and revenue as a secondary metric to catch any downstream damage. **Compare search ranking strategies.** Send half your search traffic to a relevance-weighted algorithm and half to one weighted toward margin. Measure click-through and conversion before committing. **Test merchandising rules safely.** Try a new product ordering rule on 20% of traffic rather than the whole catalog, and watch conversion before rolling it out. **Evaluate a layout change.** Run a new product detail page against the current one for two weeks, or until 10,000 add to cart events arrive. ### Personalization **Reward returning customers.** Serve a loyalty-focused homepage to a returning customer segment while first-time visitors see acquisition messaging. **Match the landing page to the campaign.** Serve a page that continues the promise of a paid search ad to visitors arriving with those UTM parameters. **Adapt to market.** Show region-appropriate merchandising and promotions based on the visitor's location. **Tune for device.** Give mobile visitors a shorter component layout while desktop visitors see the full version. ## Who Uses Experiments **Marketing analysts** target experiments to specific campaigns and segments, then track primary and secondary metrics to isolate marketing impact. **Ecommerce managers** allocate traffic across merchandising and search variants, then pause or clone experiments as priorities shift. ## Key Capabilities * Run experiments per channel and language. * Target by audience segment, UTM parameter, location, or device. * Track one primary metric and multiple secondary metrics. * Stop on a date, or end a running experiment manually. * Pause, resume, clone, and reorder experiments as priorities change. A visitor is assigned to one experiment at a time. When a visitor qualifies for several experiments, priority order decides which one applies. ## What's Next * [Create an A/B Test](/experiments/a_b_testing/create_an_ab_test) * [Create a Personalization Experiment](/experiments/personalization/create_a_personalization_experiment) * [Experiment Statuses](/experiments/overview/experiment_statuses) # Create a Personalization Experiment Source: https://help.experro.com/experiments/personalization/create_a_personalization_experiment A personalization experiment serves each visitor the version most relevant to them. You define the variants, give each one an audience, and map each to a real experience. This guide walks the full flow, from the create button to a live experiment. ## How It Differs From an A/B Test | | A/B Test | Personalization | | ------------------ | ------------------------- | --------------------------- | | Variant assignment | Fixed traffic percentages | Audience rules | | Control group | Always present | None | | Variants tab | Separate step | Merged into Target Audience | | Completion | Moves to Completed | Returns to Draft | | Winner selection | Yes | Not applicable | An A/B test measures which version wins. Personalization assumes different visitors want different things and delivers accordingly. ## Prerequisites * Permission to manage experiments in the workspace. * At least one channel and language configured. * The audiences you want to target, defined in your workspace. * The pages, components, algorithms, or merchandising rules you want to personalize, each with variants already created. ## How the Configuration Screen Works Configuration is a step-by-step flow. Each step is its own screen with its own address, and **Previous** and **Next** move between them. The **Configurations** rail on the left jumps straight to any step and marks completed steps with a green check. Personalization has five steps: Details, Metrics, Target Audience, Duration, and Experience. An A/B test has six. It adds a separate Variants step, which personalization does not have — variants are defined on Target Audience instead. ## Create the Experiment On the Experiments list, click **Create Experiment**, then choose **Personalization** in the Select Experiment Type dialog. Give the experiment a name, then select a **Channel** and a **Language**. Click **Create & Continue**. This saves the experiment as a draft. Add one primary metric, then any secondary metrics you want to track alongside it. Set **Traffic Allocation** and pick a **Target Type**. Add each variant and give it values for that type. Pick a start date. Optionally add an end date and email recipients. Add the pages, components, algorithms, or rules you are personalizing. Choose which version of each record every variant receives. Click **Start Experiment**, then confirm the prompt to publish the associated records. **Start Experiment** stays disabled until you complete the Details step. Its tooltip reads "To start the experiment, first add the experiment details and create it." ## If Validation Fails Experro checks every step when you start the experiment. If something is missing, a red icon appears beside the affected step in the **Configurations** rail. The message "Please enter all the required fields" appears at the top of the screen. Use the rail as a checklist. A green check means the step is complete. You can click **Save** at any point, even with required fields empty. Saving keeps the experiment as a draft so you can come back to it. ## Key Considerations * After you save the Details step, **Channel** and **Language** become read-only. * **Observation** and **Hypothesis** do not appear on a personalization experiment. They are A/B test fields. * Personalization has no control group and no per-variant traffic split. A visitor reaches a variant by matching its audience values. * Once an experiment is published or paused its configuration is locked. Clone it to make changes. ## What's Next * [Details](/experiments/personalization/details) * [Target Audience](/experiments/personalization/target_audience) * [View Experiment Results](/experiments/analytics/overview) # Details Source: https://help.experro.com/experiments/personalization/details Details is the first step of the personalization flow and the only one you must complete before the experiment exists. Saving this step creates the draft. ## Configuration Details | Field | Required | Description | | ------------------- | -------- | ---------------------------------------------------------- | | **Experiment Name** | Yes | A name for the experiment. Names do not have to be unique. | | **Channel** | Yes | The channel the experiment runs on. | | **Language** | Yes | The language the experiment runs in. | ## Key Considerations * **Channel** and **Language** decide which pages, components, algorithms, and rules appear later on the **Experience** step. Choose them carefully. * Once you save this step, both fields become read-only. To change them, clone the experiment and start again. * If the workspace has only one channel and one language, both fields are hidden and applied automatically. Personalization has no **Observation** or **Hypothesis** field. Both belong to the A/B test [Details](/experiments/a_b_testing/details) step. ## What's Next * [Metrics](/experiments/personalization/metrics) # Duration Source: https://help.experro.com/experiments/personalization/duration Duration controls the experiment's running window. Set a start date, and either an end date or nothing at all — an experiment with no end date runs until you pause it. ## Configuration Details | Field | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------- | | **Start Date** | Yes | When the experiment begins. A future date schedules it. | | **End Date** | No | When the experiment stops. Leave empty to run indefinitely. | | **Email Notification** | No | Addresses to notify when the experiment finishes. | ## Email Notification Start typing a name or address and Experro suggests matching users. To notify someone outside the workspace, type the full address and press **Enter**. You can add as many recipients as you need. Badly formatted addresses are rejected with an inline message. ## Key Considerations * Personalization duration is shorter than the A/B test version. There is no timezone selector and no **Stop Experiment by Event Count** toggle. * If no end date is set, the experiment runs until you pause it. Results show `∞ days` in place of a countdown. * A draft whose end date has already passed cannot be started until you move the date forward. ## When the Experiment Ends A personalization experiment cannot be ended manually. When it reaches its end date it returns to **Draft** rather than completing. Adjust the dates and start it again to resume, or leave it as a draft. Leave a gap of more than three minutes between the start and end dates. The scheduler runs every three minutes, and a shorter window may never publish. ## What's Next * [Experience](/experiments/personalization/experience) # Experience Source: https://help.experro.com/experiments/personalization/experience An experience is a concrete thing a visitor sees — a specific page version, component, algorithm, or merchandising rule. This step connects each audience variant to the experience built for it. Until you map experiences, a variant is only a traffic share and a set of audience values. Mapping gives each audience something to actually receive. ## Add an Experience Click **Add Experience(s)** and choose a type. Only records that already have variants appear for selection. Variants are authored in the module the record belongs to, not here — so create them before you reach this step. | Type | What you map | Where you create the variants | | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Web Pages** | Page records that act as web pages | [Creating a New Variant](/content/content_library/creating_a_new_variant) | | **Components** | Component records | [Creating a New Variant](/content/content_library/creating_a_new_variant) | | **Algorithms** | Search ranking algorithms | [Algorithm Variants](/experro_discovery/search/algorithm_field_settings_catalog_settings/algorithm#variants) | | **Merchandising** | Merchandising rules | [Creating a New Variant](/experro_discovery/merchandising/creating_a_new_variant) | Each type can be added once. Selected types are removed from the dropdown. ## Map Variants Adding a type opens a selection dialog. Search for the records you want, filter by content model where available, and add one or more. Each added row then gives you two things to set: 1. A **Version** — defaults to the published version, or the latest version if none is published. 2. A variant mapping — which internal variant of that record maps to which audience variant. The column header for each variant shows the audience it serves, so you can see who receives what while you map. ## Key Considerations * Web pages must be enabled to act as web pages. * Visibility of algorithms and merchandising rules depends on your plan. If your plan does not include Discovery, those types will not appear. * Every audience variant needs at least one experience mapped to it. Every experience must have a version and a variant mapping before the experiment can start. You can save an incomplete mapping, but you cannot launch with one. ## Publishing on Start Starting an experiment prompts you to publish the associated records. The experiment only begins after you confirm. ## What's Next * [View Experiment Results](/experiments/analytics/overview) # Metrics Source: https://help.experro.com/experiments/personalization/metrics Metrics define what you are measuring. Experro tracks each variant against the metrics you set here, so you can see how every audience responded to the experience built for it. ## Primary and Secondary Metrics A **primary metric** is the single KPI the experiment is designed to move. Exactly one is required. Pick the one that maps most directly to the business outcome you care about. **Secondary metrics** are tracked alongside it. They explain how and why the primary moved, and they catch damage elsewhere in the funnel. Suppose add to cart is your primary metric. Revenue and checkout rate make good secondary metrics — more carts only help if they convert and order value holds. ## Configuration Details Each metric has two fields. Both are required. | Field | Description | | ---------------- | --------------------------------------------------------- | | **Metric Name** | A label for reports. Free text. | | **Metric Event** | The event this metric measures. Choose from the dropdown. | ## Choosing a Metric Event **Metric Event** lists the events your storefront already sends, under business names rather than event identifiers — **Units Sold** and **Conversions**, for example. Pick the event that reflects what you are personalizing. A tailored landing page is measured on conversions; a merchandising rule tuned by region is measured on units sold. Each variant serves a different audience, so a variant with lower numbers is not necessarily the weaker experience. Different audiences behave differently by design. ## What's Next * [Target Audience](/experiments/personalization/target_audience) # Target Audience Source: https://help.experro.com/experiments/personalization/target_audience Target Audience is where a personalization experiment takes shape. It sets how many visitors take part, and it defines the variants along with the audience each one serves. ## Traffic Allocation Traffic allocation sets the percentage of your visitors who become part of the campaign, from 1 to 100. It defaults to 100. Lower it to introduce a personalized experience gradually. If your site gets 100 visitors a day and you want 20 of them in the experiment, set it to 20%. This is one figure for the whole experiment. Personalization has no control group and does not divide traffic between variants. Which variant a visitor receives depends on the audience they match, not on a percentage split. ## Define Target Type and Its Variants **Target Type** is chosen once and governs the whole experiment. Each variant then holds its own values for that one type — you cannot target one variant by location and another by device. | Target Type | Targets | | ------------------ | --------------------------------------------------------------------- | | **Segments** | Predefined user groups, based on demographic or behavioral attributes | | **UTM Parameters** | Users arriving via specific ad campaigns or UTM parameters | | **Locations** | Users by geographic location | | **Devices** | Users by device type, such as mobile or desktop | Below the dropdown, each variant appears as its own block. Use the pencil to rename a variant, **Remove** to delete one, and **Add Variant** to add another. The fields inside a block depend on the type. **Locations** offers Countries, Region/States, and Cities. ## Worked Example A two-variant experiment with **Target Type** set to **Locations**: | Variant | Countries | Region/States | Cities | | --------- | --------- | ----------------------------------- | ----------------------- | | Variant A | India | National Capital Territory of Delhi | Delhi | | Variant B | India | Andhra Pradesh | Anaparthy, Chipurupalle | A visitor browsing from Delhi receives Variant A. A visitor browsing from Anaparthy receives Variant B. ## Key Considerations * Every variant needs values before the experiment can start. * **Target Type** applies to the whole experiment. Changing it changes it for every variant. * Check that each set of values matches meaningful traffic before launching. A variant targeted at a few dozen visitors a week will not produce readable results. ## What's Next * [Condition Based Targeting](/experiments/targeting/condition_based_targeting) * [Duration](/experiments/personalization/duration) # Condition Based Targeting Source: https://help.experro.com/experiments/targeting/condition_based_targeting Condition based targeting restricts an experiment to visitors who match rules you define. Use it when a test only makes sense for part of your audience — a campaign landing page, a single market, or mobile shoppers. Select **Condition Based Target** on the **Target Audience** step to reveal the **Select target type** dropdown. ## Target Types | Type | Filters on | | ------------------ | ------------------------------------------------- | | **Segments** | Existing audiences defined in your workspace | | **UTM Parameters** | Campaign tracking parameters on the visitor's URL | | **Locations** | Country, region or state, and city | | **Devices** | Mobile, tablet, and desktop | ## Segments Choose one or more audiences from the dropdown. Visitors qualify if they belong to **any** selected audience. **Create Segment** opens the Audiences screen in a new browser tab so you can define a new one without losing your configuration. ## UTM Parameters Build a set of conditions, each with three parts: a parameter (`Source`, `Medium`, `Campaign`, `Term`, `Content`, `ID`, `Source Platform`, or `Referral`), an operator, and a value. Available operators are `Equals`, `Not Equal to`, `Contains`, `Does not contain`, `is blank`, `is not blank`, and `Matches regex`. The **Match** dropdown decides how the conditions combine: * **All** — the visitor must satisfy every condition. * **ANY** — the visitor must satisfy at least one. For example, with **ANY** and two conditions — source equals `newsletter`, campaign contains `spring` — a visitor arriving from the newsletter qualifies even if the campaign does not match. ## Locations Set country, region or state, and city. Suggestions filter as you type, and all three fields accept multiple values. Visitors qualify if their location matches **any** entry in **any** of the three fields. ## Devices Select one or more of `mobile`, `tablet`, and `desktop`. Visitors qualify if their device matches any selected value. ## Key Considerations * Targeting is applied before traffic allocation. Narrowing the audience reduces the traffic your experiment receives. * A visitor whose context changes mid-journey may stop matching your conditions. Check that your conditions actually match meaningful traffic before launching. A test targeted at an audience of a few dozen visitors a week will not reach a reliable result. ## What's Next * [Target Audience](/experiments/a_b_testing/target_audience) * [Create a Personalization Experiment](/experiments/personalization/create_a_personalization_experiment) # Analytics Overview Source: https://help.experro.com/experro_analytics/analytics_overview The Experro Discovery Analytics module gives you a complete view of how shoppers interact with your storefront — what they search for, what they click, what they buy, and what they leave behind — across every device, every traffic source, and every product. The Analytics module is organized into a set of focused dashboards, each one answering a specific question about the shopper experience. Use Overview as your daily check-in, Opportunities to spot search terms that need intervention, and the per-surface dashboards (Search, Categories, Collections, Facets, Products, Source) to dig into individual parts of the funnel. Navigate to the Analytics section from the Discovery main menu. The left-hand navigation lists every dashboard available to you: Overview, Opportunities, Search, Autocomplete, Categories, Collections, Facets, Products, and Source. Each dashboard opens with a consistent set of controls in the top right — Site, Device, Date Range, Compare, and Search Preview — that scope every chart and table on the page. ## Dashboards at a Glance A quick reference of every dashboard in the module and what it is best used for: * **Overview** — The composite top-line view. Headline KPIs (visits, searches, orders, revenue, conversion rate) with a performance trend chart. The right starting point for any analytics session. * **Opportunities** — Surfaces actionable insights — zero-result searches, low-result searches, and search terms trending up or down — so you can intervene before they become problems. * **Search** — Search-specific analytics, including the search conversion funnel and the queries that drive (or fail to drive) revenue. * **Autocomplete** — Tracks the autocomplete dropdown — suggestion types, top selected suggestions, and how autocomplete interactions evolve over time. * **Categories** — Category-page performance — views, clicks, add-to-cart rates, orders, revenue, conversion funnel, and device breakdown. * **Collections** — Collection-page performance, separate from Categories because curated collections behave differently from catalog categories. * **Facets** — Facet usage — how often shoppers filter, which facets and facet values are most popular, and how facet usage correlates with conversion. * **Products** — Product-level performance — best and worst performers, with a per-product drilldown showing full performance history. * **Source** — Traffic-source analytics — top referrals, top geographies (with country and region drilldown), and top UTM campaigns with revenue attribution. ## Global Controls Every dashboard shares the same set of controls in the top-right of the page. Setting these once scopes every chart, KPI, and table on the dashboard to the same window. ### Site selector Pick the site or storefront variation you want to analyze — for example, French Site, US Site, UK Site. Switching sites scopes every metric on the page to that site only. ### Device filter Filter analytics by device type. Options are All Devices (default), Desktop, Mobile, and Tablet. Useful for diagnosing device-specific issues — for example, why mobile conversion is lower than desktop, or why facets are used less often on mobile. ### Date range Select the time period for the dashboard. The date range picker offers ten preset durations and a custom range: * Today * Yesterday * Last 7 days * Last 14 days * Last 30 days * Last 60 days * Last 90 days * Last 6 months * Last 12 months * Custom date range (pick any start and end date from the calendar picker). ### Compare Compare gives you a benchmark. Every KPI on the dashboard shows a percentage change against the chosen comparison period, with a green up arrow for positive change and a red down arrow for negative. Switch on Compare and pick one of four modes: * **Previous duration** — The same number of days immediately before the selected range. Last 7 days compared against the 7 days before that. * **Previous period** — The same calendar period in the prior cycle. The current month-to-date compared against the previous full month. * **Same period last year** — The same dates one year ago. Essential for seasonal benchmarks where last week's number tells you nothing about whether you're on track. * **Custom date range** — Any custom start and end date. Useful for comparing against a specific campaign window or a known baseline. ### Search Preview The Search Preview button opens the Search Preview tool with the current site, device, and date range pre-selected, so you can validate live search behavior without losing your analytics context. **Data delay:** Analytics data is processed in near-real-time but is not instantaneous. Expect a delay of up to 15 minutes between an event happening on the storefront and it appearing in the dashboard. For very recent traffic, refresh the dashboard after a few minutes. ## Store Not Connected When you open Analytics for the first time, or when the catalog connection drops, you may see a Store Not Connected state. This is normal during initial setup and after deliberate disconnections. Reconnect the catalog through Catalog Connection to begin populating analytics. Analytics begins collecting from the moment the catalog is connected — there is no historical backfill. The first few hours after connection will show partial data; expect a full first day before headline KPIs are meaningful. ## Suggested Analytics Routines A handful of regular rituals that get the most value out of the analytics module. ### Daily — Overview check-in Open the Overview dashboard with Date Range set to Yesterday and Compare set to Previous duration. Spot-check the headline KPIs — visits, conversion rate, revenue — and the percentage changes. Anything outside the normal band warrants a deeper look in the relevant dashboard. ### Weekly — Opportunities sweep Open Opportunities with Date Range set to Last 7 days. Work through the four tabs in order — Zero Search Results, Low Results, Trending Up, Trending Down — taking action on the highest-volume rows. Aim to clear or de-prioritize the top 20 of each tab before close of business. ### Weekly — Products health Open Products with Date Range set to Last 7 days. Check the Least Performing Products tab — anything in your hero merchandising that has landed here needs investigation. Click into the per-product drilldown to see whether the drop is search-side, category-side, or campaign-side. ### Monthly — Source attribution Open Source with Date Range set to Last 30 days and Compare set to Same period last year. Look at Top Campaigns to validate that paid spend is converting; look at Top Geographics for early-signal market expansion opportunities; look at Top Referrals/Channels to spot inbound shifts. ### Seasonal — Year-over-year Before major seasonal moments (Valentine's, Mother's Day, Back to School, Black Friday), open Overview with Compare set to Same period last year. Use the YoY view to set realistic targets and to identify search terms or categories that surged last year so you can pre-position merchandising rules ahead of this year's peak. # Autocomplete Source: https://help.experro.com/experro_analytics/autocomplete The Autocomplete dashboard tracks the performance of the autocomplete dropdown — the suggestions that appear as a shopper types in the search box. ## How to Use Autocomplete Navigate to the Analytics section and select Autocomplete from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. The dashboard reports on the autocomplete experience because most shoppers click a suggestion rather than complete their typed query — so understanding autocomplete behavior is critical to understanding search behavior overall. ## Breakdown by Suggestion Type Autocomplete returns suggestions from several types — Products, Categories, Recent Searches, Popular Searches, Brands, and others. The Breakdown by Type widget shows what share of selections each type captures. Use it to understand whether shoppers are gravitating toward product suggestions or category navigation, and to spot when a suggestion type that should be performing well is being ignored. ## Performance Over Time A trend chart for autocomplete impressions and selections across the selected date range. Helpful for catching configuration regressions — a sudden drop in selections after a synonym change, for example, often indicates that the change broke autocomplete matching. ## Top Selected Suggestions Lists the autocomplete suggestions most often clicked. Tells you which suggestions are working well and surfaces opportunities to promote underperforming-but-valuable items by featuring them more prominently or adding synonyms. # Categories Source: https://help.experro.com/experro_analytics/categories The Categories dashboard reports on the performance of category pages — the navigation-driven entry points where shoppers browse rather than search. ## How to Use Categories Navigate to the Analytics section and select Categories from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. Categories often account for the majority of catalog discovery, especially on mobile and on returning-visitor sessions. The Categories dashboard answers how well that browse experience is converting. ## Category KPIs The dashboard opens with KPI tiles covering the full category funnel — views, clicks, click-through rate, add-to-cart rate, orders, revenue, and conversion rate. Each tile shows the absolute value for the period and the percentage change when Compare is on. ## Category Conversion Funnel A funnel visualization showing how shoppers move from category view to product click to add-to-cart to order. Same shape as the Search funnel but scoped to category-page entries. Hover any stage to see the absolute count and the stage-over-stage conversion rate. ## Device Breakdown A donut chart showing category-driven sessions and revenue split by device (Desktop, Mobile, Tablet). Helpful when mobile categories underperform — often a layout or facet-discoverability problem. ## Top Categories A ranked table of categories by views, with click-through, add-to-cart, orders, and revenue alongside. Click a category row to drill into a per-category dashboard with the same widgets scoped to that one category — useful for understanding why a specific category is over- or under-performing the rest of the catalog. # Collections Source: https://help.experro.com/experro_analytics/collections The Collections dashboard reports on the performance of collections — curated product groupings that sit alongside the category tree. ## How to Use Collections Navigate to the Analytics section and select Collections from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. Collections are tracked separately from Categories because they typically perform very differently — a well-curated collection often outperforms the equivalent category on both engagement and conversion. The Collections dashboard answers whether your curation is paying off. The dashboard is organized into four tabs across the top: Overview, Performance, Facets Interactions, and Orders & Sessions. Open the tab that matches the question you are answering. ## Overview Tab Headline KPIs and trend charts. Three rows of KPI tiles cover the full collection funnel: * **Engagement** — Total Collection Views, Total Sessions with Collection, Total Visitors with Collection, Total Collection Clicks. * **Conversion** — Click-Through Rate (CTR), Average Page Depth, Total Add to Carts, Add-to-Cart Rate. * **Revenue** — Total Orders, Average Order Value, Conversion Rate, Total Revenue from Collection. Below the KPI tiles you will find a Performance Over Time chart with Total Category Views overlaid against Total Revenue. Three side-by-side widgets — Sessions, Revenue Per Session, Conversion Rate — compare sessions where the shopper engaged with a collection against sessions where they did not. The cleanest demonstration of whether collections are pulling their weight on your storefront. A Collection Conversion Funnel visualization from view to click to add-to-cart to order, and a Collection Views by Device donut chart, round out the tab. ## Performance Tab Per-collection performance breakdown. The main table shows each collection with views, clicks, CTR, add-to-cart rate, orders, and revenue. Sort by any column. Switch between the Top Collection and Top Products sub-tabs to see either the collection-level view or the products within those collections. Below the main table, an Optimizing Opportunities section surfaces collections that need attention. Three sub-tabs cover the three patterns to watch for: * **Lowest Converting Collection** — Collections at the bottom of the conversion ranking. * **Collection with Missing Products** — Collections referencing products that no longer exist in the catalog. * **Top Collection with High Exit Rate** — High-volume collections where shoppers are leaving rather than continuing into a product page. ## Facets Interactions Tab Facet usage scoped to collection pages. Three widgets surface the key signals: * **Popular Facets on Collection Page** — Ranked list of facet groups used on collection pages — for example, Category, Product Type, Colour, Material, Price. * **Collection Facet Interactions** — A donut chart splitting collection sessions into Facet Interactions vs Non-Facet Interactions. Use to gauge whether shoppers on collection pages need filters or browse without them. * **Most Popular Facet Values** — Specific facet values most often selected on collection pages — Dress, Trousers, Black, Silk, Cotton, and so on. ## Orders & Sessions Tab A recent-activity table for shopper-level diagnosis. The Recent Orders sub-tab shows the most recent orders that included a collection-page touch, with Order ID, time since creation, number of items, and order value. The Recent Sessions sub-tab shows the most recent sessions that engaged with a collection, with session-level metrics for diagnosis. # Facets Source: https://help.experro.com/experro_analytics/facets The Facets dashboard reports on how shoppers use filters across the storefront — search results, category pages, and collection pages. ## How to Use Facets Navigate to the Analytics section and select Facets from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. Facet usage is one of the strongest predictors of conversion intent. Shoppers who apply filters are signaling specific intent — understanding facet behavior is therefore a direct lever on revenue. ## Facet KPIs Four KPI tiles open the dashboard: * **# Facet Interactions** — Total number of facet selections across all sessions during the period. * **# Searches with Facets** — Number of search sessions in which the shopper applied at least one facet. * **# Categories with Facets** — Number of category-page sessions with at least one facet applied. * **Facets Engagement Rate** — Percentage of qualifying sessions that included facet usage. A high-level health metric for the filter experience. ## Most Popular Facets A ranked table of facet groups (Category, Product Type, Colour, Material, Price, Size Range, Capacity, Dimensions, Brand, Availability) showing Total Interactions, Search Interactions, Category Interactions, and % of Total Interactions. Tells you which facets matter most overall and how their usage splits between search-results pages and category pages. ## Most Popular Facet Values A ranked table of specific facet values — Dress, Trousers, Black, Silk, Cotton, White, Red, Blue, Shirt, Wooden — with the facet group each belongs to and total interactions. Useful for inventory planning and merchandising prioritization. ## Facets Performance Two sub-tabs that link facet usage back to traffic sources: * **Top Searches with Facet Usage** — Search terms that most often led to facet interactions. Queries where the result set was broad enough that shoppers needed filters to narrow — a useful diagnostic for relevance tuning. * **Top Categories with Facet Usage** — Category pages where shoppers most often applied facets. Tells you which categories need the strongest facet design. Clicking a search term or category name in any table opens a scoped drilldown — for example, "Searches for Gorgeous Wooden Bike" or "Fashion/Men/Shirt" — showing facet performance for that one query or category in isolation. # Opportunities Source: https://help.experro.com/experro_analytics/opportunities The Opportunities section can be used to identify search terms that need your attention — terms that returned no results, returned too few results, or whose volume is shifting noticeably. ## How to Use Opportunities Navigate to the Analytics section, then select the Opportunities tab from the left navigation. Set the site, device, date range, and (optionally) the comparison period from the controls in the upper right of the page. The dashboard has four tabs across the top of the table area, each surfacing a different opportunity stream: **Zero Search Results**, **Low Results**, **Trending Up**, and **Trending Down**. Open the tab of interest to see the search terms in that stream during the selected period. ### Zero Search Results Shows search terms that returned no results during the selected period. Each row shows the search term and the number of times it was searched. These are catalog gaps or synonym gaps — fix them and you instantly unlock previously-lost demand. ### Low Results Shows search terms that returned some results but not enough to give the shopper a useful selection. Often the highest-value tab in the dashboard — these are shoppers who searched, got results, and still bounced because the result set was too narrow. The table shows the search term, the number of searches, the % Change versus the comparison period, and the Exit Rate. ### Trending Up Shows search terms gaining momentum over the selected period. Capitalize on emerging trends — surface these products in banners, on the home page, or in merchandising rules. The table includes the % Change column with a green up arrow for terms that have grown most. ### Trending Down Shows search terms losing momentum. Investigate inventory, freshness, or competing categories that may be drawing demand away. The % Change column shows the decline with a red down arrow. ## Take Action on Each Term For every search term in the table, you can take action without leaving the dashboard. Click the three-dot menu in the **Action** column on any row to open the action menu, then pick the action that matches the gap you are trying to close. * **Try** — Opens Search Preview with the term pre-loaded, so you can see exactly what the shopper saw. The fastest way to diagnose what went wrong. * **Merchandise** — Opens the merchandising rule editor with the term pre-scoped. Create a Boost, Pin, or Slot rule that surfaces specific products for this query. * **Add Synonyms** — Opens the synonyms editor with the term pre-loaded. Add equivalent terms so future searches for variations also match. * **Add Phrases** — Opens the phrases editor with the term pre-loaded. Group related words to ensure the search engine treats the phrase as a single unit. ## Suggested Workflow Start the week on the Zero Search Results tab — these are the clearest gaps and the easiest wins. Then move to Low Results, focusing on terms with high search volume and high exit rate first. Use Trending Up to pre-position merchandising rules and banners around terms with consistent week-over-week growth. Finally, use Trending Down to investigate decay — sometimes the cause is external (a competitor campaign), sometimes catalog-side (out of stock, removed products), and sometimes search-side (broken merchandising rule). Click any search term in any tab to open a query-specific drilldown with full conversion and engagement metrics for that one term. # Products Source: https://help.experro.com/experro_analytics/products The Products dashboard reports on per-product performance — which products are converting, which aren't, and what shoppers are searching for when they encounter (or fail to encounter) each product. ## How to Use Products Navigate to the Analytics section and select Products from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. The dashboard opens with two top-level tabs — Best Performing Products and Least Performing Products — and a unified product-performance table that supports sorting by any column. Use it as the bridge between catalog operations and merchandising decisions. ## Best Performing and Least Performing Tabs Best Performing Products ranks products by performance with views, CTR, add-to-cart count, total orders, and total revenue. Use this tab to identify your hero SKUs and protect their visibility through merchandising rules. Least Performing Products is the inverse. The bottom of the ranking is usually a mix of new launches that haven't accumulated history yet, inventory-constrained SKUs, and genuinely underperforming products that need merchandising attention or removal. ## Searches with No Impressions and High Impressions A second section below the main table bridges search and catalog: * **Searches with No Impressions** — Searches that occurred but did not return any impression for the product in context. These are missed-discovery moments — either a synonym gap, a relevance issue, or a catalog gap. * **Searches with High Impressions** — Searches that produced many impressions for the product but did not convert. Often signals a relevance mismatch (the product is showing up but not for the right intent) or a creative issue (the listing image or title is not persuading clicks). ## Per-Product Drilldown Clicking any product opens a per-product dashboard showing the product's full performance picture. The drilldown header shows the product image and name; below it sits a grid of KPI tiles: * Total Searches that surfaced the product. * Total Views the product received. * Total Carts (add-to-cart events). * Total Orders. * Cart-to-Order Rate. * Click-to-Cart Rate. * Cart Rate. * Search Conversion Rate. * Total Revenue. Below the KPIs, a Product Performance section breaks down the traffic that drove the product. The Popular Search Keywords sub-tab lists search terms that most often surfaced this product, with searches, clicks, CTR, add-to-cart, orders, and revenue per term. The Popular Categories sub-tab does the same for category pages where the product appeared. Recent Visits and Sessions section at the bottom of the page shows recent shopper activity involving the product — useful for spot-checking unusual behavior and for customer-service investigations. # Search Source: https://help.experro.com/experro_analytics/search The Search dashboard reports on search behavior end-to-end — how often shoppers search, what they search for, what results they see, and how those searches convert. ## How to Use Search Navigate to the Analytics section and select Search from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. The dashboard opens with KPI tiles at the top covering the search funnel — total search volume, click-through, add-to-cart, conversion, and revenue. Each tile shows the absolute value for the selected period and, when Compare is on, the percentage change against the comparison period. ## Search Conversion Funnel Below the KPI tiles, a funnel visualization shows how shoppers move from search to click to add-to-cart to order. Hover any stage of the funnel to see the absolute count and the stage-over-stage conversion rate. The drop-off between any two stages is the leak to investigate first. ## Performance Over Time A trend chart plots search volume and conversion across the selected date range. Useful for spotting seasonal patterns, post-launch volatility, or the impact of recent merchandising changes. When Compare is on, the comparison period is overlaid on the same axes for direct visual reference. ## Search Term Tables Below the funnel and trend chart, the dashboard surfaces search terms in several ranked lists: * **Top Searched Terms** — Highest-volume queries during the period. The terms that matter most by sheer traffic. * **Top Converting Searches** — Searches with the highest conversion rate. These are queries to over-invest in — protect their merchandising, ensure inventory, monitor for relevance regressions. * **Top Revenue Generating Searches** — Searches that drove the most revenue. Often overlaps with Top Converting but weighted by basket size. Click any search term to open a query-specific drilldown with full performance history for that one term — including the products it returned, the click-throughs it generated, and the conversion path of the resulting sessions. # Source Source: https://help.experro.com/experro_analytics/source The Source dashboard reports on where your traffic and revenue come from — referral channels, geographies, and marketing campaigns. ## How to Use Source Navigate to the Analytics section and select Source from the left navigation. Set the site, device, date range, and comparison period from the controls in the upper right. Use the dashboard to attribute revenue back to acquisition efforts, to spot geographic expansion opportunities, and to validate that paid spend is converting. The dashboard has three tables, each surfacing a different cut of the traffic-source picture. ## Top Referrals / Channels A ranked list of traffic sources with visits and revenue per source. Tells you which inbound channels are pulling their weight on a revenue basis, not just on a visit basis. ## Top Geographics A geographic breakdown of visits and revenue by country. Rows are expandable — clicking the arrow next to a country drills into the states or regions within that country where applicable. For example, a United States row expands into Maine, Florida, Arizona, Washington, and Illinois, each with its own visit count and revenue contribution. Use the See More link at the bottom of a country's expanded list to load additional regions when more than the first few are populated. When you launch a new locale or shipping market, monitor Top Geographics weekly for the first few months to track adoption. When you see a previously-small region trending up, that's a signal to consider localized merchandising or a dedicated site variation. ## Top Campaigns UTM-based campaign tracking with revenue attribution. Each row in the table represents a unique combination of UTM Source, Campaign, Medium, and Content, with the visits and revenue attributed to that combination during the period: * **UTM Source** — The platform the visitor came from: google, facebook, linkedin, twitter, youtube, pinterest, tiktok, snapchat, quora, reddit, and so on. * **Campaign** — The named campaign the visitor came from: Summer Blast 2025, Style Promo, July Campaign, Flash Deal, and so on. * **Medium** — Marketing medium: CPC, Social Ads, Email, Referral, Video Ads, Search Ads, Podcast Ads. * **Content** — The specific creative or content variation: Ad Group A, Carousel 3, Weekly Blast, Offer Code 20, Post Series 2, Static Image 5, Monthly Highlights, Promo Code 30. * **Visits and Revenue** — Direct revenue attribution per campaign row. # Banners Source: https://help.experro.com/experro_discovery/banners Experro **Banners** lets merchandisers place promotional content within **Search Results**, **Category Pages**, and **Collection Pages** — directly from the Discovery dashboard. Banners are built in two stages: **creating the banner** asset, then [**attaching it to a Merchandising Rule**](/experro_discovery/merchandising/rule_types/banner_rule) that controls placement and schedule. Let us start with **creating a Banner** first. For a feature overview and use-case examples, see the [Banners Overview page](/discovery_suite/banners/overview). # Creating a Banner Select the grid icon at the top left of the application. Select **Discovery** from the dropdown menu. On the **Discovery** screen, navigate to **Banners** from the left panel under **Discovery**. The Banners screen displays all configured banners with the following columns: | **Field** | **Description** | | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Name** | Internal label assigned to the banner. Used to identify it across the dashboard and within Merchandising Rules. | | **Status** | Indicates whether the banner is Active or Inactive. Only active banners are eligible to display once attached to a live rule. | | **Created At** | The date the banner was created. | | **Created By** | The user who created the banner. Useful for team collaboration and audit tracking. | | **Action** | A menu (···) offering Edit, Clone, Activate/Deactivate, and Delete. | **Search and Filter** Use the Search bar to filter banners by name. Use the Status dropdown to filter by Active or Inactive. **Actions Menu** Click ··· on any row to access the following actions: * **Edit** — modify the banner's configuration * * **Clone** — duplicate the banner and all settings as a starting point for a new campaign * * **Activate / Deactivate** — toggle the banner's active status without deleting it * * **Delete** — permanently remove the banner Click **Add Banner** to open the creation modal. Enter the following: * **Name** (required) — an internal identifier for the banner. Use a naming convention that reflects the campaign and placement, for example: "Summer Sale — Dresses — Search." * **Description** (optional) — additional context for your team, such as campaign dates or the intended rule. Click Save. The banner configuration screen will open. # Configuring Banner Banners can be configured independently for Desktop, Tablet, and Mobile. Each device tab has its own layout, content, and visibility settings. To suppress a banner on a specific device, check Hide banner for \[device] view within that device tab. Configure devices separately when: * Your banner creative is not responsive across screen widths * You are using a different image crop or aspect ratio per device * You want the banner to appear on desktop and tablet but not mobile, or vice versa Select the content format for this banner: | **Type** | **Description** | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Image** | Upload a static image (PNG, JPG, AVIF, WEBP, or GIF, up to 2 MB). Standard format for promotional campaigns, seasonal banners, and brand placements. | | **Video** | Display a video banner. Best for high-production campaigns where motion adds meaningful context. Supports video URLs from platforms like YouTube, Vimeo, Dailymotion, etc. | | **HTML** | Paste custom HTML for advanced use cases such as countdown timers, dynamic copy, or embedded interactive elements. Requires front-end familiarity. | Select where the banner appears relative to products on the page. | **Layout** | **Where It Appears** | | --------------- | --------------------------------------------------------------------------------- | | **1x1** | Inline within the product grid, occupying the same space as a single product tile | | **1x2** | Spans two product columns in a single row | | **1x3** | Spans three product columns in a single row | | **Full Width** | Stretches across the full width of the product grid | | **Top** | Above all products, before the grid begins | | **Bottom** | Below all products, after the grid ends | | **Below Facet** | Between the filter panel and the product grid | Configure the banner's content and interaction behavior: | **Field** | **Description** | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Banner Image** | Upload the image file. Supported formats: PNG, JPG, AVIF, WEBP or GIF. Maximum file size: 2 MB. | | **Title** | An internal title for the banner. Used in some theme implementations as display text. | | **Banner Maximum Height** | Maximum display height in pixels. Prevents oversized banners from disrupting the product grid layout. | | **Alt Tag** | Describes the banner image for screen readers and search engines. Required for accessibility. Be specific: "Summer Sale — jewelry up to 30% off" is more effective than "promotional banner." | | **Redirect URL** | The page a shopper lands on after clicking the banner. Can be a collection page, PLP, external URL, or campaign landing page. | | **Open in New Tab** | Toggle on to open the destination in a new browser tab. Recommended when linking to external sites. | Event tracking connects banner interactions to your analytics stack. Configure JavaScript events to fire when the banner loads or when a shopper clicks it. | Event | When It Fires | Common Uses | | ----------- | -------------------------------------- | ------------------------------------------------------------------ | | **Onload** | When the banner renders in the browser | Track impressions, fire tracking pixels, trigger A/B testing tools | | **Onclick** | When a shopper clicks the banner | Track CTR, record conversions, send data to retargeting platforms | To configure, paste your JavaScript event code into the Onload Event or Onclick Event field. Events execute in the browser at the corresponding moment without requiring additional page-level changes. A real-time Banner Preview panel is available on the right side of the configure screen. The preview updates as you make changes to layout and content. **Note**\ The preview shows only the content and layout, not your storefront’s actual theme. Final appearance depends on your front-end setup. Always test new banner types in a staging environment before publishing to production. | **Action** | **What It Does** | | ------------ | -------------------------------------------------------------------------------------------------------------- | | **Save** | Stores configuration changes. The banner is saved but not displayed on the storefront. | | **Activate** | Marks the banner as active. Active banners are eligible to display once attached to a live Merchandising Rule. | | **Cancel** | Discards unsaved changes. | **Important**\ Activating a banner does not make it visible on your storefront. A banner only appears once it is attached to an active Merchandising Rule. See how to **Add Banners** to **Merchandising Rules** here. Visit [**AI Merchandising → Type of Rules → Banner Rule**](/experro_discovery/merchandising/rule_types/banner_rule) for step-by-step setup instructions. # Collections Source: https://help.experro.com/experro_discovery/collections Experro **Collections** empowers merchants to curate and showcase hand-picked groups of products—whether seasonal bundles, thematic assortments, or promotional sets—directly within search results, category pages, and recommendation slots. By blending AI-driven discovery with human curation, Collections transforms your storefront into a dynamic, story-driven journey that boosts engagement and average order value—all without writing a single line of code. ## Navigation Select menu icon at the top left of the application. Next, select **Discovery** from the dropdown menu. The discovery screen will be displayed. Navigate to **Collections** from the navigation panel. ## Collections List View On the **Collections** screen you’ll see a table of all existing collections, with the following columns: | Field | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Collection Name** | The human-readable title you’ve assigned to the collection. This helps you and your team quickly identify the grouping of products (e.g., “Spring Promotions” or “Men’s Shoes”). | | **ID** | A unique system-generated identifier for the collection. Use this when referring to the collection in API calls or support tickets. | | **Channel** | The channel where this collection is active. | | **Language** | The locale or language version (e.g., “en-US,” “fr-FR”) of the collection. Displayed only if you support multiple languages. | | **Status** | Indicates whether the collection is currently **Published**, **Draft**, or **Scheduled**. Helps you see at a glance which collections are live. | | **Created By** | The username or email of the administrator who originally created the collection. Useful for audit trails and collaboration. | | **Action** | A menu (⋯) offering contextual operations such as **Edit**, **Clone**, **Publish/Unpublish**, or **Delete**. | ### Search Bar * Use the search bar to filter by collection name or ID. ### Actions Menu * Click under **Action** on any row to: * **Edit** : Edit the Collection * **Publish/Unpublish** : Publish/Unpublish the Collection * **Clone** : Clone the Collection * **Delete**: Delete the Collection ## Create New Collection You can create your own collection and then add curated products to the collection. Let us look into the process for the same. Click **Create Collection** to open the creation dialog. Provide details such as a **Collection Name**, and a description of the collection under **Describe the Collection** and a **Page Slug** will be automatically generated for you. Click **Save** to create the collection and move to the collection configuration screen. On this screen, you can configure the products that you want to curate for this collection. ### 1. Add Products to Collection Choose one of the three following methods to **Add Products to Collection**: 1. **AI Search** : Leverage Experro’s AI-powered discovery to find products by relevance and context. * **AI Search:** Provide the keyword that you want to curate the products using Experro's AI-powered search. * **Filter Products:** Use this toggle button to filter products using advanced query building with attributes such as brand, price range, inventory status, etc,. * **Max. Products Limit:** Specify the maximum number of products that you want to add to this collection. The maximum number that you can specify is 10,000 items per collection. * **Total Products:** Live count of items matching your criteria. * **Preview Products:** Click to view a paginated sample before saving. 2. **Product Query**: Create filter-based queries for precise control over collection membership. * **Product Query:** Select **Product Query** to add products to the collection by building a query. * **Configure Product Query:** Choose any combination of attributes to build a query (e.g., category = “Shoes” AND in\_stock = true). * **Max. Products Limit:** Specify the maximum number of products that you want to add to this collection. The maximum number that you can specify is 10,000 items per collection. * **Total Products:** Live count of items matching your criteria. * **Preview Products:** Verify your query logic by previewing a subset. 3. **CSV Upload**: Bulk-upload product IDs from your own system or spreadsheet. * **Select CSV Upload:** Select **CSV Upload** to add products to the collection by building a query. * **Choose File:** Import a CSV containing product IDs. You can download the sample file to understand how the csv file needs to be created. * **Max. Records:** 10,000 rows per file. * **Download Sample:** Get a template to ensure correct formatting. * **Total Products:** Shows how many valid IDs were imported. * **Preview Products:** Confirm the imported items before finalizing. ### 2. SEO Details Optimize how your collection appears in search engines and social shares: * **Title:** The page’s `` tag (e.g., “Spring Essentials Collection”). * **Meta Keywords:** Comma-separated keywords for SEO (e.g., “spring fashion, linen dresses”). * **Meta Description:** A concise summary to display under your title in search results. * **OG Image:** Upload a 1200×630-px image (PNG or JPG, ≤2 MB) for social previews. ### 3. Collection Page Content Enhance each collection page with rich content zones: * **Top of Page Content:** Add banners, hero text, or featured product modules above the product grid. * **Bottom of Page Content:** Insert FAQs, promotional banners, or related links below the products. Use the rich-text editor to format headings, lists, images, and embeds. Each block can include dynamic tags (e.g., `{collection_name}`) to personalize the content. ### 4. Publishing Your Collection Once your products, SEO metadata, and content blocks are configured: 1. **Save Draft:** Click **Save** to preserve changes. 2. **Review Preview:** Use **Preview Products** and page-preview modes to verify layout and content. 3. **Publish:** Hit **Publish** to make the collection live on your storefront. Your new collection will now appear at its designated URL and be discoverable by customers. By following this guide, you can efficiently build, optimize, and launch custom collections that leverage AI discovery, precise filtering, and tailored content—driving engagement and conversions across your site. # Navigating Discovery Dashboard Source: https://help.experro.com/experro_discovery/discovery_dashboard_interface The Experro Discovery Dashboard Interface is your centralized control panel for managing and optimizing your digital discovery experience. With an intuitive design, the interface empowers both technical and business users to monitor system status and configure key features—enabling data-driven decisions and continuous improvement across your digital storefront. ## Navigating the Discovery Interface ### Accessing the Interface Click <img alt="menu icon" /> to Open the Application Menu and then click on **Discovery** to open the discovery home screen. ### Home Screen Overview The Home screen in Experro Discovery is designed as a dynamic, data-driven hub that provides immediate insight into your store's search performance. The Home screen integrates interactive widgets that offer real-time metrics and trends to help you make informed decisions. **Key Widgets on the Home Screen** These widget gives you a comprehensive snapshot of your search performance. It displays critical metrics such as: <img alt="" /> * **Search Views:** Total number of times search results are viewed. * **Search Clicks:** Number of clicks on search results. * **Click Through Rate (CTR):** The percentage of views that convert into clicks. * **Add to Cart Rate:** Percentage of search clicks that result in products being added to the cart. * **Total Orders:** Number of orders placed as a result of search interactions. * **Total Search Revenue:** Revenue generated from search-driven purchases. * **Search Performance Over Time:** Trends in search activity across a specified period. * **Search Conversion Funnel:** A visualization of the progression from search initiation to purchase. * **Search Sessions by Device:** A breakdown showing search activity across different device types. * **Overall Search Performance:** Aggregate metrics that provide an overall evaluation of search effectiveness. By consolidating this vital information into an interactive dashboard, the Experro Discovery Home screen empowers you to quickly identify trends, make informed decisions, and continuously optimize your digital storefront—all from one convenient, visually engaging location. ### Key Navigation Elements The left-hand navigation panel organizes Experro Discovery’s primary functions into distinct tabs, making it easy to switch between managing insights, search configurations, merchandising rules, and facet settings. **Analytics** <img alt="menu icon" /> * **Overview:** Located just below the Home tab, this tab provides a suite of dashboards and reports. * **Features:** Monitor opportunities, search performance, autocomplete behavior, category engagement, and facet usage. * **Further Reading:** [Analytics Documentation](/experro_discovery/insights_and_analytics) **Search & Autocomplete** <img alt="menu icon" /> * **Overview:** Dedicated to managing and fine-tuning all aspects of search functionality. * **Features:** Configure autocomplete, search redirection, content search, synonyms, phrases, dictionaries (stopwords, spellcheck, stemming), re-ranking, and more. * **Further Reading:** [Search Configuration Guide](/experro_discovery/search) **Merchandising** <img alt="menu icon" /> * **Overview:** The hub for creating, managing, and reviewing merchandising rules. * **Features:** Access global, category-specific, and search-specific rules to boost, bury, pin, or sort products for optimal visibility. * **Further Reading:** [Merchandising Documentation](/experro_discovery/merchandising) **Facets** <img alt="menu icon" /> * **Overview:** Manage the facets that allow users to filter and refine their search results. * **Features:** Configure, update, and monitor facet filters based on product attributes like price, brand, or category. * **Further Reading:** [Facet Configuration Guide](/experro_discovery/facets) By following this guide, you'll quickly become proficient in navigating the Experro Discovery Dashboard Interface. The structured layout not only helps you monitor key performance indicators in real time but also provides the tools to effectively manage and optimize your digital discovery experience. For further details and advanced configuration options, please refer to the respective documentation links provided above. # Facets Source: https://help.experro.com/experro_discovery/discovery_usecases/facets ## Use Case: Streamlining Product Discovery with Facets ### Scenario: Navigating a Vast Product Catalog Efficiently Imagine Priyanka, who is preparing for an upcoming business trip and needs a formal outfit suitable for corporate meetings in a tropical climate. When she visits your online apparel store, she is initially overwhelmed by thousands of options that range from casual wear to formal attire. Without an effective way to refine these choices, Priyanka risks abandoning her search. ### How to Implement Faceted Navigation in Experro Follow these steps to configure and utilize facets effectively: 1. **Access the Facets Configuration:** * Log into your Experro workspace. * Navigate via the left-hand panel to **Discovery → Facets.** * The Facets screen will display the list of pre-configured facets that are available for filtering products. * Refer [Facets Configuration](/experro_discovery/facets) to view detailed steps for adding and configuring the facets. 2. **Configure and Enable Facets:** * Review the list of existing facets and adjust settings if necessary (e.g., enable or disable specific facets, modify display order). * To add new facets, click **Add Facet** and define the facet attributes such as Product Type, Material and configuration options. * Save your changes to ensure the facets are ready for customer use.\\ <img alt="" /> 3. **Refining Search Results with Facets:** * When Priyanka searches for an outfit, she can use the displayed facets to narrow down her options. For example: * **Product Type:** Select ‘Formal Wear’ to filter out casual and sportswear. * **Material:** Choose options like ‘Linen’ or ‘Cotton’ for a comfortable, breathable fit in a tropical climate. * **Color:** Pick ‘Light Colors’ (such as beige or white) that are suitable for sunny environments. * **Size:** Select her specific size to quickly find products that will fit. * **Brand:** Filter by preferred brands that are known for quality formal attire. * These facets work together to dynamically narrow down the thousands of available products to a curated list that meets all her criteria. ### Outcome: Increased Conversion and Customer Satisfaction By configuring and effectively using facets: * **Streamlined Navigation:**\ Priyanka can efficiently filter through a vast catalog, easily finding formal outfits that match her specific needs. * **Enhanced Customer Experience:**\ With a focused and relevant set of results, Priyanka experiences a smooth shopping journey—she finds her ideal outfit quickly, adds it to her cart, and completes her purchase. * **Actionable Insights:**\ Retailers can monitor facet usage patterns to gain valuable insights into customer preferences, which helps in refining inventory decisions and tailoring future merchandising strategies. * **Higher Conversion Rates:**\ Presenting only the most relevant products increases the likelihood of purchases and reduces bounce rates, leading to improved overall sales. By implementing faceted navigation through Experro Discovery, you transform product discovery from a daunting, time-consuming process into an intuitive, efficient, and engaging experience. For more detailed instructions on configuring facets, please refer to the [Facet Configuration Guide](/experro_discovery/facets). # Insights & Analytics Source: https://help.experro.com/experro_discovery/discovery_usecases/insights_and_analytics ## Use Case: Filling Catalog Gaps ### Scenario: Addressing Zero-Result Searches Imagine that several customers are repeatedly searching for "bamboo toothbrush" on your personal care eCommerce site, yet no products are returned. This recurring zero-result query indicates either a gap in your product catalog or a misconfiguration in your search settings, potentially leading to customer frustration and lost sales. ### How to Implement This Use Case with Experro Discovery Follow these step-by-step instructions to identify and resolve catalog gaps using Experro Discovery: #### Step 1: Monitor Zero-Result Searches 1. **Access the Opportunities Dashboard:** * Log into your Experro workspace and navigate to **Discovery → Analytics → Opportunities**. * On the dashboard, locate the **Zero Search Results** tab which collects data on search queries that yield no results. <img alt="" /> 2. **Analyze Zero-Result Data:** * Review the list of zero-result search terms. Identify frequently searched terms like "bamboo toothbrush" that indicate unmet demand. * Take note of the frequency and trends associated with these queries. * Refer [Opportunities](/experro_discovery/insights_and_analytics/opportunities) to learn more about the opportunities dashboard. #### Step 2: Identify and Address the Gaps 1. **Evaluate Catalog and Search Settings:** * Determine whether the zero-result query is due to a missing product or suboptimal search configuration. * If it's a catalog gap, discuss with your product team about adding the missing items. * If it's a configuration issue, adjust your search parameters or merchandising rules to handle variations (e.g., by configuring synonyms for "bamboo toothbrush" to include similar products like "eco-friendly toothbrush"). 2. **Implement Changes:** * **Catalog Expansion:**\ If the data shows strong demand (e.g., frequent searches for "bamboo toothbrush"), consider expanding your catalog by adding the product. * **Search Enhancement:**\ Use the **[Search Configuration Guide](/experro_discovery/search)** to adjust search parameters. For example, add a synonym that maps "bamboo toothbrush" to an equivalent or similar product if the exact item is not available. #### Step 3: Validate the Changes 1. **Test the Updated Configuration:** * After making the necessary adjustments, perform test searches to ensure that the previously zero-result query now returns relevant products. * Verify that customers receive a meaningful list of products when searching for "bamboo toothbrush" or its synonyms. 2. **Monitor and Iterate:** * Continue to use the Opportunities Dashboard to track zero-result queries. * Make further adjustments as needed based on ongoing analytics and customer feedback. ### Outcome * **Improved Product Assortment:**\ By identifying gaps through zero-result searches, you can expand your catalog to meet customer needs, ensuring that queries like "bamboo toothbrush" yield relevant results. * **Enhanced User Experience:**\ Customers no longer face dead ends in their searches. The system delivers comprehensive results, reducing frustration and fostering loyalty. * **Increased Conversions:**\ Addressing catalog gaps and fine-tuning search configurations lead to higher conversion rates and increased revenue, as customers are more likely to find and purchase the products they need. This use case demonstrates how Experro Discovery’s data-driven insights empower you to pinpoint and resolve catalog deficiencies, resulting in a smoother and more profitable shopping experience for your customers. # Merchandising Source: https://help.experro.com/experro_discovery/discovery_usecases/merchandising ## Use Case 1: Precision Catalog Curation with Include/Exclude Rules ### Scenario: Targeted Product Displays for a Luxury Collection Consider a fashion retailer who aims to create a premium shopping experience for customers seeking luxury accessories. The retailer’s goal is to ensure that when users search for high-end luxury items, only curated, high-quality products from selected premium brands are displayed. At the same time, products that are out-of-stock or discontinued should be completely excluded from search results. ### How It Works 1. [Configuring Include Rules](/experro_discovery/merchandising/rule_types/exclude_include) :\ The retailer uses Experro Discovery’s include rules to force the display of products from specific, curated premium brands. For example, when a user searches for "luxury watches," the system is configured to show only those items from trusted, high-end brands. 2. [Configuring Exclude Rules](/experro_discovery/merchandising/rule_types/exclude_include) :\ Simultaneously, exclude rules are applied to remove products that are out-of-stock or discontinued from search results. This ensures that customers are only presented with available and desirable products, enhancing their overall shopping experience. 3. [Rule-Based Automation](/experro_discovery/merchandising/rules) :\ Once these rules are configured, Experro’s intelligent algorithms continuously monitor customer search behavior. The system automatically updates the search results to reflect these criteria, ensuring that only relevant and in-stock luxury items appear when customers perform a search. ### How to Implement This Use Case To achieve precision in catalog curation using Include/Exclude rules, follow these instructions: 1. **Access the Merchandising Module:** * Log in to your Experro workspace. * Navigate to **Discovery → Merchandising** from the left-hand menu. * Select the appropriate rule category (typically, a **Search Rule** or **Global Rule** based on your strategy).\\ <img alt="" /> 2. **Creating the Rule:** * Click **Add Rule** and enter a rule name (e.g., "Curate Luxury Accessories") along with a brief description. * Select the rule operation as **Include** to force the display of premium products, or **Exclude** to filter out items like out-of-stock or discontinued products.\\ <img alt="" /> 3. **Define the Rule Conditions:** * For including premium products: * Set a condition such that the product attribute (e.g., Brand) equals one of the curated premium brands and add the search keyword as 'jackets' * For excluding unwanted products: * Set a condition where the specific product is excluded. * You may add additional conditions using the **Add Condition** feature to further narrow the criteria with logical operators (AND/OR).\\ <img alt="" /> 4. **Set the Duration:** * Define the active period for the rule if necessary (e.g., during specific promotional events or seasonally.) 5. **Save and Validate:** * Click **Save** to activate the rule. * Validate the configuration by searching for luxury items to ensure that only the curated products are displayed in the results. ### Outcome By using Include/Exclude rules: * **Enhanced Brand Perception:**\ Customers searching for luxury items receive a refined list featuring only high-end products, reinforcing the retailer's premium image. * **Improved Customer Satisfaction:**\ By excluding out-of-stock or discontinued items, the system ensures that only available, desirable products are shown, reducing customer frustration. * **Higher Conversion Rates:**\ Curating the product display increases the likelihood of purchase, leading to better sales performance and a more engaging user experience. ## Use Case 2: Optimized Product Placement and Promotions ### Scenario: Promoting New Arrivals While Demoting Out-of-Season Items Imagine an online retailer that has just received a fresh batch of fall jackets. With the season changing, the retailer wants to ensure that these new arrivals are prominently featured in search results and on category pages, while out-of-season summer apparel is pushed lower in the rankings or hidden entirely. This setup ensures that customers are always presented with the most relevant, timely products. ### How It Works 1. [Setting Up Merchandising Rules](/experro_discovery/merchandising/configuring_rules) :\ The retailer uses Experro Discovery’s rule-based merchandising system to create dynamic rules. Specific rules are configured to elevate (boost) products that are part of the new fall collection, while separate rules are set to demote (bury) summer products during the autumn season. 2. [Rule-Based Automation](/experro_discovery/merchandising/rules) :\ Experro Discovery’s intelligent algorithms continuously analyze customer behavior. Once the rules are in place, the platform automatically adjusts product rankings—so when a customer searches for "jackets" or browses the "Outerwear" category, the fall jackets appear at the top while summer apparel is relegated to lower positions or removed from the visible area. ### How to Implement This Use Case Follow these step-by-step instructions to set up merchandising rules within Experro Discovery to achieve optimized product placement: #### Step 1: Access the Merchandising Module 1. **Log In and Navigate:** * Log into your Experro workspace. * From the left-hand navigation panel, select **Discovery → Merchandising**. * Choose the appropriate rule category based on your desired scope (for example, a Global or Category rule if you want the changes across the entire site or within a specific product category). <img alt="" /> #### Step 2: Create a New Merchandising Rule 1. **Initiate Rule Creation:** * Click the **Add Rule** button to open the rule configuration interface. 2. **Define the Rule:** * Enter a clear and descriptive **Rule Name**, such as "Promote Fall Jackets, Demote Summer Apparel." * Optionally add a description explaining that this rule is intended to boost the visibility of new fall arrivals while burying out-of-season summer items. #### Step 3: Configure Rule Conditions for New Arrivals 1. **Select Operation:** * Choose the **Boost** operation for new arrivals. 2. **Set Conditions:** * Configure conditions to identify fall jackets: * For example, set the product category field to "Jackets & Blazers" and enter the search keyword as 'women's' 3. **Adjust Boost Level:** * Use the slider for the Boost Level Configuration to determine how much these products should be elevated. <img alt="" /> #### Step 4: Configure Rule Conditions for Out-of-Season Items 1. **Create a Separate Rule:** * Create another rule (or configure an additional condition if your system supports multiple actions) to demote out-of-season summer apparel. 2. **Select Operation:** * Choose the **Bury** operation for items that are out-of-season. 3. **Set Conditions:** * Define conditions such as setting the "Categories" attribute to equal "Summer Handbags" (or any relevant indicator that the items are not in season). 4. **Adjust Bury Level:** * Use the slider for the Bury Level Configuration to push these items lower in the search results. <img alt="" /> #### Step 5: Schedule and Save the Rules 1. **Define the Duration:** * Set the start and end dates for each rule so that they automatically activate during the autumn season and deactivate afterward. 2. **Save the Rules:** * Click **Save** to apply each rule. 3. **Test the Implementation:** * Run a sample search to confirm that fall jackets are prominently displayed and summer handbags is relegated to lower positions or removed. ### Outcome : Increased Conversions The retailer witnesses several benefits: * **Enhanced Visibility for New Arrivals:**\ Fall jackets are consistently showcased at the top, drawing customer attention and leading to higher engagement. * **Increased Conversion Rates:**\ With the most relevant products prominently featured, customers are more likely to make a purchase, leading to improved sales metrics. # Overview Source: https://help.experro.com/experro_discovery/discovery_usecases/overview Experro Discovery is more than just a collection of features—it’s a transformative solution that redefines how customers interact with your digital storefront. This section provides detailed, real-world use cases that illustrate how Experro Discovery enhances product visibility, increases search accuracy, and improves conversion rates. By exploring these scenarios, you can learn how to leverage the platform to address your specific business needs and drive measurable outcomes. Let us look into the use-cases for all the features that fall under discovery : <CardGroup> <Card title="Merchandising" icon="cart-shopping" href="/experro_discovery/discovery_usecases/merchandising"> Explore Use-Cases related to Merchandising. </Card> <Card title="Search" icon="magnifying-glass" href="/experro_discovery/discovery_usecases/search"> Explore Use-Cases related to Search. </Card> <Card title="Facets" icon="filter" href="/experro_discovery/discovery_usecases/facets"> Explore Use-Cases related to Facets. </Card> <Card title="Insights & Analytics" icon="chart-simple" href="/experro_discovery/discovery_usecases/insights_and_analytics"> Explore Use-Cases related to Insights & Analytics. </Card> </CardGroup> # Search Source: https://help.experro.com/experro_discovery/discovery_usecases/search ## Use Case: Enhanced Product Discoverability ### Scenario: Navigating the Summer Collection Emma, a fashion enthusiast, visits your online boutique in search of the perfect outfit for an upcoming beach vacation. She types "red summer dress" into the search bar, hoping to find a stylish piece that meets her needs for warm weather. However, product titles in your catalog may vary—some may be labeled “summer red dress” or “red dress for summer.” Emma requires a system that can interpret her intent and retrieve all relevant products. ### How Experro Facilitates This Experro's advanced search capabilities come into play to ensure Emma's search is fruitful: * [Semantic Understanding](/experro_discovery/search/settings) : The platform interprets the intent behind "red summer dress," recognizing that Emma is looking for dresses that are both red and suitable for summer. It understands variations like "summer red dress" or "dress for summer in red." * [Intelligent Autocomplete](/experro_discovery/search/autocomplete) : As Emma begins typing, Experro suggests relevant search terms, such as "red sundress" or "crimson beach dress," guiding her towards popular and available options. * [Synonym Recognition](/experro_discovery/search/synonyms) : Experro identifies synonyms and related terms, ensuring that products labeled as "scarlet sundress" or "ruby summer gown" are also presented in the search results. * [Merchandising Rules](/experro_discovery/merchandising/rules) : The platform applies predefined rules to boost seasonal items, ensuring that the latest summer collection appears prominently in the search results. ### How to Implement This with Experro Discovery Follow these steps to ensure that your search functionality delivers a seamless experience for users like Emma: 1. **Configure Semantic Search:** * Navigate to **Discovery → Search & Autocomplete → Settings → Core Config**. * Enable **Semantic Understanding** to allow the system to process natural language queries. * Define the product fields (e.g., Categories, Color) that should be analyzed for meaning. * Refer to [Semantic Understanding](/experro_discovery/search/settings) documentation for detailed setup.\\ <img alt="" /> 2. **Optimize Autocomplete Suggestions:** * Go to **Discovery → Search & Autocomplete → Autocomplete**. * Ensure that the Autocomplete section is fine-tuned with relevant popular keywords. * Add common variations for terms like "red summer dress" to help guide users toward appropriate suggestions. * Refer to [Autocomplete](/experro_discovery/search/autocomplete) Configuration Guide.\\ <img alt="" /> 3. **Set Up Synonym Mappings:** * Navigate to the **Synonyms** tab within **Search & Autocomplete**. * Add synonyms for key search terms. For example, map “sundress” to “summer dress” and include related terms like "scarlet" and "crimson." * This ensures that even if a product is described using different terminology (e.g., “ruby summer gown”), it is still retrieved in the search results. * Refer to [Synonyms](/experro_discovery/search/synonyms) Documentation.\\ <img alt="" /> ### Outcome By implementing these technical enhancements, Emma is presented with a curated selection of red dresses that match her search intent—even if the product titles differ. The intelligent combination of semantic search, optimized autocomplete, and synonym mapping ensures that: * **All Relevant Products are Displayed:**\ Emma finds a comprehensive list of red dresses, including variations she might not have initially considered. * **User Time is Saved:**\ With precise, real-time suggestions and a boosted display of seasonal items, Emma quickly locates her desired product. * **Conversion Rates Increase:**\ A streamlined and effective search experience leads to higher customer satisfaction and a greater likelihood of purchase. This use case illustrates how Experro Discovery transforms the product search process, ensuring that customers like Emma experience a seamless journey from query to purchase. # Configure Facet Appearance Source: https://help.experro.com/experro_discovery/facets/configure_facet_appearance Once a Facet Rule exists, you add facets to it and configure how each one is displayed on the storefront. To create the rule itself, see [Create and Manage Facet Rules](/experro_discovery/facets/create_and_manage_facet_rules). ## Adding a Facet to a Rule Open the Facet rule and click **Add Facet**. The modal asks you to choose a **Facet Type** — Catalog Field or Custom Facet. ### Catalog Field Select one or more indexed fields from your catalog. The dropdown lists each field's display name, internal name, and data type (string, number, SKU, date). You can add multiple fields in one step — each appears as a chip and becomes a separate facet on save. Catalog Field facets inherit values directly from your catalog and pick up new values automatically. ### Custom Facet Manually define values that aren't available in your catalog. Use this for curated value sets, staging facets while catalog data is being prepared, or facets built from logic combining multiple fields. <Frame> <img alt="" /> </Frame> ## The Edit Facet Screen Selecting a facet opens the Edit Facet screen with three panels: the facets list on the left, **General** and **Advance** tabs in the middle, and the **Edit Values** panel on the right. For value-level controls in the right panel, see [Manage Facet Values](/experro_discovery/facets/manage_facet_values). ## General Tab ### Display Name and Internal Name **Display Name** is the label shoppers see on the storefront. **Internal Name** is the read-only catalog field identifier. ### Facet Appearance Choose how the facet displays. The available options depend on the field type — incompatible types are greyed out. <Tabs> <Tab title="String Fields"> * **Terms** — Standard list of clickable values with checkboxes. The default for most string fields. * **Swatches** — Color swatches per value. When selected, the right panel shows a **Generate Color Code** card with a **Generate with AI** button that creates color codes from value names (for example, "Navy" produces a navy swatch). You can also pick colors manually. * **Images** — Image tiles per value. Upload one image per value in PNG, JPG, or WEBP (100 KB max). Useful when values are best communicated visually (diamond shapes, pattern types). * **Blocks** — Tappable block tiles. Common for sizes (S, M, L, XL) and short text values. </Tab> <Tab title="Number Fields"> * **Range** — The shopper enters a minimum and maximum to filter. * **Slider**, **Bucket**, **Rating** — See dedicated sections below for the configuration each one supports. </Tab> </Tabs> <Frame> <img alt="" /> </Frame> ### Slider A Slider lets shoppers drag two handles along a track to set a minimum and maximum value. Use it when shoppers want to skim a continuous range quickly, for example Price or Weight. On the storefront, the slider shows the current minimum on the left handle and the current maximum on the right handle, with a filled bar between them indicating the selected range. As shoppers drag, results refresh to reflect the new bounds. **What you configure on a Slider rule:** * Sort Order, Value Selection, and Show No. of Value (covered below). * The Advance tab toggles (tooltip, mobile/desktop collapse). Show Search Box does not apply since there are no discrete values to search. The slider’s minimum and maximum bounds come from the underlying catalog data automatically — you don’t set them in the rule. If your catalog ranges from ` $5 to $499, the slider shows $5 to $499.` <Note> **Number Fields Only:** Slider only appears for number fields. It is greyed out for string fields. </Note> ### Bucket A Bucket displays a list of predefined value ranges that you author. Shoppers tap one of the prepared ranges to filter, rather than entering values themselves. Use it when you want a clean, opinionated set of filter options — for example, Price buckets of `$0–$50, $50–$100, $100–$250, and $250+.` On the storefront, each bucket appears as a tappable row (or checkbox, depending on Value Selection). The shopper picks one or more buckets and results update to the union of those ranges. **What you configure on a Bucket rule:** * Each bucket has a lower bound, an upper bound, and a display label. * Buckets can overlap or leave gaps — the system does not enforce contiguous ranges. Be deliberate so shoppers don't see duplicates or miss products. * Sort Order controls the display order. Custom Order lets you arrange buckets manually — typically low to high for price. You create and label the buckets in the Edit Values panel — see [Manage Facet Values](/experro_discovery/facets/manage_facet_values). <Note> **Number Fields Only:** Bucket only appears for number fields. It is greyed out for string fields. </Note> <Frame> <img alt="" /> </Frame> ### Rating A Rating facet displays star-based filter options designed for review rating fields. Each row shows a star count (for example, four stars) so shoppers can filter to products at or above a given rating with one tap. On the storefront, each row in the Rating facet renders as filled and empty stars matching the row's value (or only filled stars if you enable that option). Shoppers tap a row to filter by that rating. **What you configure on a Rating rule (beyond the standard settings):** * **Rating Range** — Define the rating range by setting minimum and maximum values, for example 1 to 5. Two dropdowns (Min, Max) set the bounds. * **Rating Inclusion** — Define whether a selected rating includes higher ratings, lower ratings, or only the exact rating. Common storefront convention is "and above" — selecting four stars returns four- and five-star products. * **Show only filled stars** — When enabled, only the filled stars appear for each rating value. Empty stars are hidden. Use this for a cleaner row when shoppers don't need to see the maximum scale on every line. Rating also supports per-value labels in the Edit Values panel — you can rename a rating row's label to make it more meaningful (for example, labeling the five-star row "Top Rated"). For details, see [Manage Facet Values](/experro_discovery/facets/manage_facet_values). <Note> **Preview Limit:** The Edit Values preview shows up to 5 stars only. On the storefront, ratings display according to the Rating Range you configured. </Note> <Note> **Number Fields Only:** Rating only appears for number fields. It is greyed out for string fields. </Note> <Frame> <img alt="" /> </Frame> ## Sort Order Define how facet values are arranged for shoppers. The Sort Order dropdown offers five options: * **Custom Order** — Arrange values manually in your preferred order. Use this for editorial control, for example pinning your house brand to the top. * **Ascending (A-Z)** — Alphabetical. Best for facets shoppers scan by name (Brand, Designer). * **Descending (Z-A)** — Reverse alphabetical. * **Dynamic Ranking** — Values that shoppers click and convert on rise to the top over time. Self-tuning without manual intervention. * **Highest Product Count** — Values with the most products first — a safe default for most facets. ## Value Selection Multiple Selection lets shoppers apply more than one value at a time (for example, both Nike and Adidas). Single Selection limits them to one — use this for mutually exclusive facets such as Department or Gender. ## Show No. of Value How many values are visible by default before the shopper expands the facet. Default is 5. ## Advance Tab Toggle-only settings that affect how the facet renders: * **Display Tooltip** — Adds a tooltip icon beside the display name. * **Show Search Box** — Displays a search box above the values — useful for high-cardinality facets like Brand. * **Collapse by Default for Mobile / Desktop** — Collapses the facet on load for that viewport. * **Show Count** — Shows product counts next to each value (e.g. "Nike (42)"). <Warning> **Performance Note:** Facets with many values can slow down rendering when counts are enabled. Use Show Count carefully on high-cardinality facets. </Warning> # Create and Manage Facet Rules Source: https://help.experro.com/experro_discovery/facets/create_and_manage_facet_rules Learn how to create, configure, and manage Facet Rules in Experro Discovery. Facet Rules group one or more facets and tie them to a specific surface on your storefront. For background on what facets are and how scope works, see <a href="/discovery_suite/facets">Facets Overview.</a> ## The Facets Listing Screen Open **Discovery > Facets** in the sidebar. Each row in the listing shows the rule’s toggle, name, scope label, facets inside the rule, status, last modified, and an action menu. Use the Status and Scope filters at the top right to narrow the list, or search by rule name. <Frame> <img alt="" /> </Frame> ## Creating a Facet Rule Click **Add Facet Rule** in the top right. The pop-up has two sections — the rule name and the Facet Scope. <Steps> <Step title="Name the Rule"> Use a descriptive name that identifies the surface and intent, for example "Engagement Rings — Diamond Shape" or "Winter Jacket Search Tuning". </Step> <Step title="Choose the Facet Scope"> Pick one of four scope types: Global, Searches, Categories, or Collections. Each card describes where the rule will apply. <Frame> <img alt="Add Facet Rule scope pop-up" /> </Frame> </Step> <Step title="Choose the Apply On Setting"> For Searches, Categories, and Collections, an **Apply On** section appears below the scope cards. Pick either the "All" or "Specific" option. The Global scope does not show an Apply On section. If you pick **Specific**, the controls depend on the scope you chose: **Specific Searches** — An operator dropdown and a free-text input appear: * **Operator** — Equal to (exact match), Starts with, Ends with, or Contains. * **Search term input** — Type a term and press Enter to add it. Each term becomes a removable chip and shares the same operator. Use Equal to for exact-match terms. Use Contains or Starts with when one rule should cover a family of related queries (for example, every query containing "diamond"). **Specific Categories** — A "Select categories" dropdown appears, with no operator. Each entry shows the category name with its full path (for example, Jeans — /women/jeans/). The path disambiguates same-named categories across the tree. **Specific Collections** — A "Select collections" dropdown appears. If no collections exist in the workspace, the dropdown shows a "No data" state — create collections from the Collections module first. </Step> <Step title="Save the Rule"> Click **Save**. The rule is created as Inactive. From the rule detail screen, add facets and configure them — see [Configure Facet Appearance](/experro_discovery/facets/configure_facet_appearance/). </Step> </Steps> ## Conflict Resolution <Warning> **Most Recently Active Wins:** If two rules at the same scope conflict, the system applies the most recently active facet rule. Deactivate any rule you no longer want active rather than leaving it alongside a newer one. </Warning> ## Managing Rules A facet rule is Inactive by default. Toggle it Active from the rule detail screen or from the listing row when configuration is complete. Click any rule row to edit it. Use the action menu (three dots) on a row to duplicate or delete a rule — duplication is useful for cloning a rule into a different scope. # Manage Facet Values Source: https://help.experro.com/experro_discovery/facets/manage_facet_values Facet values are the individual options shoppers click to filter results — Nike, Macy’s, and Levi’s under the Brand facet, for example. The Edit Values panel on the right of the Edit Facet screen lets you rename values, merge similar values, hide values from the storefront, and control whether product counts appear. To open the panel, open any facet inside a rule (see [Configure Facet Appearance](/experro_discovery/facets/configure_facet_appearance).). By default the top 100 facet values are loaded. To configure values beyond the top 100, use Catalog Mapping. <Frame> <img alt="" /> </Frame> ## Panel Controls * **All Values filter** — Filter by attribute or visibility state. * **Show Count toggle** — Mirrors the Show Count setting on the Advance tab. * **Search values** — Find a specific value in a long list. Each value row shows the display name (what shoppers see), the internal name (raw catalog value), an edit icon (pencil) for rename or merge, and a show/hide icon (eye). ## Showing and Hiding Values Click the eye icon to hide a value from the storefront. Hidden values stay in the catalog and remain available to merchandising rules — they just don't appear as filter options. Click again to restore. Common uses: suppress legacy values, hide internal or test values, remove very low-count values that aren't useful as filters. ## Renaming a Facet Value Click the pencil icon and change the Display Name. The underlying catalog data is untouched. Useful when catalog values are developer-friendly but not shopper-friendly — for example, renaming "mat\_cotton\_100" to "100% Cotton". ## Merging Facet Values Merging combines multiple values into a single shopper-facing value. Products tagged with any of the source values appear when the merged value is selected. **Example:** a Color facet with Sky Blue, Navy Blue, Baby Blue, and Royal Blue can be merged into a single Blue value. Shoppers see one Blue filter, and selecting it returns products tagged with any of the four originals. ### How to Merge Values <Steps> <Step title="Select the target value"> Click the pencil icon next to the value you want as the merged target. </Step> <Step title="Choose values to merge"> Select the additional values to merge into it. </Step> <Step title="Save"> Save your changes. </Step> </Steps> <Note> **Scope-Sensitive:** Renames and merges apply at the scope of the rule. A Global rule's merge applies everywhere unless overridden by a more specific rule. </Note> ## Rating Value Labels When the facet uses the Rating appearance, each rating row in the Edit Values panel has its own editable label. Use this to rename star rows for clarity, for example labeling the five-star row "Top Rated". For the Rating appearance configuration itself, see [Configure Facet Appearance](/experro_discovery/facets/configure_facet_appearance). <Note> **Preview Limit:** The Edit Values preview shows up to 5 stars only. The storefront displays ratings according to the Rating Range configured on the General tab. </Note> ## Range-Based Facets <Warning> **No Individual Values Listed:** When a facet uses the Range or Slider appearance, the Edit Values panel does not list individual values. Instead, it shows a preview of the range inputs. For Bucket, you create and label the buckets in this panel. </Warning> # Glossary Source: https://help.experro.com/experro_discovery/glossary This glossary serves as a quick reference for common terms and concepts used in Experro Discovery. It is designed to help both technical and business users understand the language and functionalities of the platform. Understanding these terms will help you navigate and utilize Experro Discovery more effectively. ## A ### API Endpoint A specific URL provided by Experro Discovery that allows external systems to interact with its features. These endpoints facilitate data exchange and integration with other tools (e.g., CRM, ERP). ### Analytics The process of collecting and analyzing data from user interactions. In Experro Discovery, analytics track key performance indicators such as search effectiveness, conversion rates, and to inform optimization efforts. ## C ### Category Rule A merchandising rule that applies to specific product categories. These rules help tailor product displays for certain segments or groupings within your catalogue. ### Content Search The functionality within Experro Discovery that enables users to search not just products, but also associated content like descriptions, reviews, and metadata. ## D ### Dictionaries Curated lists used in search configuration to manage stopwords, spellcheck, and stemming processes. ### Discovery Refers to the entire suite of Experro Discovery functionalities that empower users to find, explore, and interact with products in a personalized manner by integrating advanced merchandising, search, and facet filtering. ### Discovery Integrations The process of connecting Experro Discovery with external systems (e.g., product catalogues, content management systems). This integration ensures data flows seamlessly between Experro and other platforms, supporting real-time updates and synchronization. ## F ### Feature Packages Bundled modules of functionality within Experro Discovery that allow businesses to choose the specific features they need. These packages can be tailored based on business requirements, from core search capabilities to advanced merchandising and analytics. ### Facet An attribute or filter that enables users to refine search results. Facets can include parameters such as price, brand, category, and more. ### Facet Filter The set of options or values that a user can select from a facet to narrow down search results. Effective facet filtering helps improve the overall search experience by allowing users to quickly find relevant products. ## I ### Indexing The process of organizing and storing data so that it can be retrieved quickly and accurately during a search. Effective indexing is critical for delivering fast, relevant search results. ### Integration The act of connecting Experro Discovery with other systems and tools. This ensures that data, such as product information and user interactions, flows smoothly between platforms. ## M ### Merchandising The strategic process of arranging and prioritizing products within search results to influence the user’s actions. Experro Discovery enables you to manage merchandising through rule-based actions that optimize product visibility and drive conversions. ### Merchandising Rule A configurable criterion used to control product display and ranking. Rules can be applied globally, to specific categories, or search queries. They include actions such as boosting, burying, pinning, sorting, and slotting. * Global Rule A merchandising rule that applies universally across all search queries or categories within Experro Discovery. * Boost A merchandising action that increases a product’s ranking in search results, making it more visible to users. * Bury A merchandising action used to lower a product’s ranking, reducing its prominence in the search results. * Pin A rule-based action that fixes a product at a specific position within the search results, regardless of other ranking factors. * Slot A merchandising technique used to designate a particular placement or “slot” in the search results for a product. ## P ### Phrases Specific groupings of words treated as a single search term, enhancing search accuracy and relevancy. ## R ### Re-Ranking A method to adjust the initial search result order based on additional criteria or real-time data, ensuring that the most relevant products are displayed prominently. ## S ### Search A core feature of Experro Discovery that enables users to quickly find products using queries. It integrates advanced functionalities such as autocomplete, synonym mapping, and re-ranking to deliver precise results. ### Search Autocomplete A feature that provides real-time suggestions as users type their queries, helping to guide them to the most relevant search terms and reducing input errors. ### Search Redirection A mechanism that automatically directs search queries to a specific landing page or curated set of results, based on predefined conditions. ### Synonyms Alternative words or phrases that are mapped to the same search results. This ensures that different query variations still retrieve relevant products. ### Stopwords Common words that are excluded from search indexing to improve performance and relevancy of search results. ### Spellcheck A feature that corrects misspelled queries, ensuring that users receive accurate search results. # Analytics Source: https://help.experro.com/experro_discovery/insights_and_analytics/analytics Experro's **Analytics** module offers a comprehensive suite of dashboards equipped with interactive widgets, enabling you to monitor, analyze, and refine various aspects of your search and merchandising performance. By leveraging these dashboards, you can make informed, data-driven decisions to enhance user experience and drive conversions. ## Autocomplete Analytics This dashboard focuses on the performance of the Autocomplete feature: * **Breakdown by Type:** Analyze the distribution of different autocomplete suggestion types, such as by products, categories, recent search etc. * **Performance Over Time:** Monitor how user interactions with autocomplete suggestions evolve over selected timeframes. * **Top Selected Suggestions:** Identify the most frequently chosen autocomplete options to understand user preferences. <img alt="" /> ### Category Analytics The Category Analytics dashboard offers insights into the performance of individual product categories: * **Category Views and Clicks:** Measure how often category pages are viewed and interacted with. * **CTR and Add to Cart Rate:** Evaluate the effectiveness of category pages in driving user actions. * **Total Orders and Revenue:** Analyze orders and revenue generated from each category. * **Performance Over Time:** Track trends in category performance. * **Conversion Funnel:** Visualize the customer journey from category view to purchase. * **Device Breakdown:** Understand how different devices influence category performance. * **Top Categories:** Identify which categories are the most popular. <img alt="" /> ### Facet Analytics The Facet Analytics dashboard focuses on user interactions with facet filters: * **Facet Interactions:** Track how frequently users interact with facets. * **Searches Involving Facets:** Monitor the number of searches that use facet filters. * **Category-Level Analysis:** Evaluate facet usage across different product categories. * **Facet Engagement Rate:** Measure the percentage of users interacting with facets. * **Most Popular Facets:** Identify which facets are most commonly used. * **Overall Facet Performance:** Review aggregate performance metrics for facet filters. <img alt="" /> By combining insights from both the Opportunities and Analytics sections, Experro empowers you to make informed, data-driven decisions that continuously refine your merchandising and search strategies. # Opportunities Source: https://help.experro.com/experro_discovery/insights_and_analytics/opportunities Experro’s Opportunities Dashboard surfaces three critical insight streams—Trending Up, Trending Down, and Zero Results—so you can continuously optimize search relevance, merchandising, and catalog completeness. By combining data monitoring with targeted actions (Try, Merchandise, Add Synonyms, Add Phrases), you’ll turn raw analytics into measurable improvements in engagement and conversion rates. ## Identifying Opportunities from the Dashboard ### Overview The **Opportunities Dashboard** organizes actionable search insights into three tabs: * **Trending Up Results:**\ Displays search terms that are gaining popularity over your selected timeline. This tab helps you identify emerging trends so you can capitalize on new customer interests. <img alt="" /> * **Trending Down Results:**\ Shows search terms that are declining in popularity. These insights allow you to pinpoint potential issues or adjust strategies for keywords that are losing traction. <img alt="" /> * **Zero Search Results:**\ Lists search terms that return no results. This highlights gaps in your product catalog or search configuration that may need attention. <img alt="" /> For each search term in these tabs, you can take various actions by clicking <img alt="menu icon" />. The available actions include: * **Try:** Test the search term to view current results. * **Merchandise:** Create or modify merchandising rules associated with the term. * **Add Synonyms:** Enhance search relevance by adding alternative terms. * **Add Phrases:** Group related words to ensure accurate search interpretation. ### Step‑by‑Step Workflow <Steps> <Step title="Access the Opportunities Dashboard"> * Navigate to **Discovery → Analytics → Opportunities**. * Choose the tab of interest (Trending Up, Trending Down, or Zero Results). </Step> <Step title="Analyze Your Data"> * **Trending Up:** Look for spikes tied to promotions, new launches, or external events. Integrate multiple data sources (e.g., marketing campaigns, social media buzz) for context. * **Trending Down:** Cross‑reference with inventory and performance metrics to pinpoint root causes—out‑of‑stock items, diminished demand, or poor display. * **Zero Results:** Group similar zero‑result terms (e.g., “bamboo toothbrush,” “eco toothbrush”) to prioritize catalog expansion or synonym additions. </Step> <Step title="Take Action on Each Term"> * Click <img alt="menu icon" /> next to a term. * Select **Try** to validate existing search behavior. * Choose **Merchandise** to open the rule engine—set up boosts, buries, pins, or slots tailored to that query. * Use **Add Synonyms** to capture related terms and **Add Phrases** for compound queries. </Step> <Step title="Validate & Iterate"> * After changes, test searches to confirm improved results. * Monitor the same tab periodically—what’s trending one week may cool off the next. Practice ongoing change management, assigning stakeholders and documenting updates. </Step> </Steps> ### Leveraging Data for Strategic Decisions * **Capitalize on Emerging Trends:**\ Use Trending Up data to adjust promotions, update landing pages, or feature products in banners—acting quickly on what’s resonating with users. * **Address Declines Proactively:**\ For Trending Down terms, consider targeted remarketing, refreshed imagery/descriptions, or adjusting stock levels to reignite interest. * **Resolve Catalog Gaps:**\ Zero Results insights drive catalog enrichment. Add new products or configure synonyms/phrases so that searches yield at least related items—even if exact matches aren’t yet in stock. * **Holistic Dashboard Best Practices:**\ Keep dashboards focused on your core KPIs (e.g., search CTR, add‑to‑cart rate). Avoid clutter—start with a straightforward question (“Which search terms underperform?”) and build around that. * **Measure & Forecast:**\ Integrate Opportunities data with broader ecommerce analytics (revenue, traffic, inventory). Use trend analysis to forecast demand and plan inventory accordingly. By continuously monitoring and acting on these three Opportunity streams, you’ll transform raw search data into targeted actions—optimizing product visibility, improving user satisfaction, and driving sustainable growth. # Overview Source: https://help.experro.com/experro_discovery/insights_and_analytics/overview Experro provides a robust Insights & Analytics suite designed to help you monitor search behavior, identify trends, and make data-driven decisions to optimize your digital storefront. This section is divided into two parts: [Opportunities](/experro_discovery/insights_and_analytics/opportunities) and [Analytics](/experro_discovery/insights_and_analytics/analytics) . Let us look into them one by one. # Action on Rules Source: https://help.experro.com/experro_discovery/merchandising/action_on_rules ## Overview Managing your merchandising rules in Experro is as crucial as creating them. This section provides a clear, step-by-step guide on how to view, update, and delete your rules using our intuitive interface—ensuring you maintain full control over your product display strategies. ### Viewing and Searching for Rules 1. **Navigate to the Rules Screen:** * From the left-hand navigation panel, click on **Discovery**. * Select **Merchandising** <img alt="menu icon" /> * Choose the desired rule category (Global, Category, or Search) according to your merchandising strategy. 2. **View Rules:** * The screen displays a list of all rules for the selected category. * Use the search bar at the top of the list to quickly locate a specific rule by name. * Click on a rule name to drill down and view its detailed configuration. <img alt="" /> ### Managing and Modifying Rules All actions—such as updating, activating/deactivating, duplicating, or deleting a rule—are available from the actions column in the rule list. 1. **Access the Actions Menu:** * Locate the rule you wish to modify. * In the actions column for that rule, click <img alt="menu icon" /> to reveal a dropdown menu with multiple options. 2. **Edit a Rule:** * Select **Edit** from the dropdown. * This opens the rule configuration interface, where you can modify details such as the rule's settings, active duration, and the triggering keyword or category.\\ <img alt="" /> 3. **Activate/Deactivate a Rule:** * Choose the **Active/Inactive** option from the actions menu to toggle the rule’s status. * This feature allows you to temporarily disable a rule without deleting it or to reactivate an inactive rule. <img alt="" /> 4. **Duplicate a Rule:** * Click **Duplicate** to create an exact copy of an existing rule. * Modify the duplicated rule as needed—for example, adjusting its schedule or tailoring it for a slightly different scenario—without starting from scratch.\\ <img alt="" /> 5. **Delete a Rule:** * Select **Delete** from the actions menu to permanently remove the rule. * Confirm the deletion in the popup prompt to finalize the removal. <img alt="" /> By following these steps, you can efficiently manage and modify your merchandising rules in Experro. This ensures that your product displays remain optimized and up to date, enabling you to continuously enhance the customer shopping experience. # Configuring Rules Source: https://help.experro.com/experro_discovery/merchandising/configuring_rules Configuring a merchandising rule in Experro is a straightforward, step-by-step process that gives you complete control over how products are displayed across your digital storefront. Whether you're setting up a global promotion or fine-tuning product order for a specific category or search query, this guide walks you through the process and provides best practices to ensure your rules are both effective and efficient. ## Creating a Merchandising Rule Creating effective merchandising rules is essential for optimizing your product discovery experience. Experro's intuitive interface makes it easy to configure rules tailored to your specific business needs. Select the apps icon at the top left of the application. Next, select Discovery from the dropdown menu. The discovery screen will be displayed. <Frame> <video> <source /> </video> </Frame> Navigate to Merchandising from the navigation panel. <Steps> <Step title="Click the Add Rule button"> Click the Add Rule button at the top right of the Merchandising listing screen. A pop-up opens where you define the scope and basic details of the rule before configuring its behavior. </Step> <Step title="Define the Scope of the Rule"> In the scope pop-up, choose where the rule will apply: * **Global Rule:** Applies to all search queries and category pages across your website. * **Category Rule:** Tailors the product display for category pages. After choosing Category, select either All Categories (applies to every category page) or Specific Categories (applies only to the categories you pick from the list). * **Search Rule:** Activates on search queries. After choosing Search, select either All Searches (applies to every search query) or Specific Searches (applies only to the search terms you enter). <Note> Only one Active rule of the same type can exist per scope. Experro will flag a conflict at save time if another active rule already covers the scope you've chosen. </Note> </Step> <Step title="Define the Functionality of the Rule"> Provide a Rule Name and Description that clearly explain the purpose of the rule. * **Boost:** Increase the ranking of a product. * **Bury:** Lower a product's ranking. * **Include/Exclude:** Force the presence or absence of certain products. * **Sort:** Rearrange products based on specific criteria. * **Pin:** Fix a product or a specific product variant at a defined position. * **Slot:** Reserve a specific position range for a product. * **Variant Slicing:** Control which variant of a multi-variant product appears as the lead tile on the results page. * **Banner:** Insert promotional content within product listings. Decide what action the rule will perform. Options include: <Frame> <img alt="" /> </Frame> </Step> <Step title="Specify the Triggering Condition (Keyword or Category)"> * **For Global Rules:** No additional triggering condition is needed; the rule applies storefront-wide. * **For Search Rules with Specific Searches:** Enter the search term(s) that will trigger the rule, and set a qualifier for each one. Qualifiers include **Equal to** (exact match), **Contains**, **Starts with**, and **Ends with**. For example, set "Equal to" with "Emerald Diamonds" to trigger only on that exact query, or set "Contains" with "diamond" to trigger on every query that includes the word. * **For Category Rules with Specific Categories:** Select the relevant category (e.g., "Diamonds") from your product catalog. * **For All Searches or All Categories scopes:** No additional triggering condition is needed — the rule already covers every page in that scope. </Step> <Step title="Configure Products Inside the Rule"> Depending on the rule type, the configuration step changes: * **Pin Rule:** Search for the product, expand it to choose a specific variant if needed, set the pin position, and drag products into the order you want. * **Variant Slicing Rule:** Choose the variant attribute to slice on (for example, color) and the priority order. * **Other rule types:** Follow the specific configuration documented for that rule type in Types of Rules. Most rule editors include a **Filter** panel so you can narrow the product list while building the rule — filter by category, attribute, stock status, or any indexed field before selecting products. </Step> <Step title="Specify the Duration"> * Set the timeframe during which the rule will be active. This is particularly useful for time-sensitive promotions (e.g., festival or seasonal sales). * Choose a start and end date so the rule activates and expires automatically. </Step> <Step title="Save and Activate the Rule"> * Once you have configured the scope, functionality, triggering conditions, products, and duration, click Save. * Every rule has an Active / Inactive toggle. Newly saved rules default to Inactive so you can review the configuration before it goes live. Switch the toggle to Active when you’re ready. * Inactive rules stay saved in the rule list but do not affect the storefront. Use Inactive to stage rules for upcoming campaigns or to temporarily pause a rule without deleting it. </Step> </Steps> ## Managing Rules from the Listing Screen The Merchandising listing screen gives you full context at a glance. Each rule row displays: * **Toggle** — Activate or deactivate the rule directly from the listing screen. * **Rule Name** — With the rule type shown alongside it. * **Scope** — The search term, category name, or "All Searches" / "All Categories" / "Global" label is shown inline. You no longer need to open each rule to check where it applies. * **Status** — Active or Inactive. * **Duration** — Start and end dates, where set. * **Modified At and Modified By** — Last edit timestamp and user. * **Action** — Edit, duplicate, or delete the rule. Use the filter and search controls at the top right to narrow the list by status, scope, or rule type. ## Best Practices for Rule Configuration * **Plan Your Strategy** — Define your merchandising objectives and identify the key metrics you want to improve before creating rules. * **Use Specific Criteria** — Set precise conditions to ensure your rules target the right products and customer segments. * **Stage Before Activating** — Save rules as Inactive first and review the configuration end-to-end. Activate only when you're confident the rule does what you intend. * **Test Your Rules** — Thoroughly test each rule after activation to confirm it works on the storefront. * **Monitor Performance** — Regularly review rule performance using Experro's analytics dashboard and make adjustments as needed. * **Prioritize Rules** — Understand the priority order of rules to avoid conflicts and ensure desired outcomes. * **Clear Naming Conventions** — Use descriptive names for rules to simplify identification and management. * **Document Your Rules** — Maintain records of rule configurations for future reference and troubleshooting. ## Key Considerations <Warning> **Sorting Rule Conflicts** — When a sorting rule is applied, pin, slot, boost, and bury rules are disabled, and vice versa. </Warning> <Warning> **One Active Rule Per Scope** — You can have only one Active rule of the same type per scope. Two active Pin Rules cannot exist on the same search term or category — Experro will block the save and ask you to deactivate the conflicting rule. </Warning> <Note> **Pin and Slot Limits:** The maximum position for pinning a product and the maximum slot range is 50, due to the display constraint of 50 products per page. </Note> ## Priority Order Experro applies rules in a defined order to manage conflicts: **Overall Rule Priority:** ``` Pin → Slot → Exclude → Include → Bury → Boost ``` <Frame> <img alt="" /> </Frame> **Example:** If both boost and bury rules are applied, the bury rule takes precedence, overriding the boost rule. By following this configuration process and adhering to best practices, you ensure that your merchandising strategy is precise, effective, and aligned with your business objectives. For more in-depth guidance on each configuration step or specific rule types, refer to the detailed documentation linked within each section. # Creating a New Variant Source: https://help.experro.com/experro_discovery/merchandising/creating_a_new_variant A rule variant is an alternate configuration of the same merchandising rule. Each variant holds its own operation, boost or bury weighting, and conditions, so you can test two merchandising strategies against each other rather than guessing which ranks better. <Frame> <img alt="" /> </Frame> ## Prerequisites * Permission to manage merchandising rules. * A plan that includes A/B testing. Without it, the option to save a variant does not appear. ## Create a Variant <Steps> <Step title="Open the rule"> In **Discovery**, go to **Merchandising** and open the rule you want to create a variant of. </Step> <Step title="Configure the variant"> Set the **Operation**, adjust the boost or bury weighting, and add the conditions you want this variant to apply. Use the product preview beside the rule to check how your configuration reorders results before you save. </Step> <Step title="Save it as a variant"> Click the arrow beside **Save**, then select **Save as a New Variant**. </Step> <Step title="Confirm it was created"> The new variant appears in the variant selector in the left panel. </Step> </Steps> <Info> **Save as a New Variant** only appears when your plan includes A/B testing. </Info> ## Switch Between Variants The variant selector sits at the top of the rule configuration panel. Open it to see every variant on the rule and switch between them. The variant currently applied to your storefront carries an **Active** badge. **Manage Variants** at the bottom of the selector opens the full variant list. Variants already in use by an experiment are marked with an experiment icon. ## Using Variants in an Experiment Once a rule has more than one variant, it becomes selectable on the **Experience** step of the experiment flow, where you map each variant to an experiment group. <Warning> Changing the configuration of a variant that a running experiment is using changes what shoppers see mid-test. Pause the experiment first, or create a new variant instead. </Warning> ## What's Next * [Action on Rules](/experro_discovery/merchandising/action_on_rules) * [Map Experiences to Variants](/experiments/a_b_testing/experience) # Field-Based Rule Conditions Source: https://help.experro.com/experro_discovery/merchandising/field_based_rule_condition Merchandising rules in Experro can now be built using conditions on any indexed field in your catalog, regardless of its type. This significantly expands the range of business logic you can express in a rule without engineering involvement. <Frame> <img alt="" /> </Frame> ## What Changed Previously, rule conditions were limited to a fixed set of fields — primarily SKU, category, and a small number of string attributes. Adding new field types or new conditions required configuration changes from the Experro team. The rule editor has been rebuilt around the full Field Settings catalog. Any field you have indexed and marked as **Filterable** is now available as a condition in your merchandising rules. Numeric, date, and Boolean fields are supported with type-appropriate operators, and multi-value fields are matched element-by-element. ## Supported Field Types in Rule Conditions | Field Type | Available Operators | Common Uses | | ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **String** | Equals, Does Not Equal, Contains, Starts With, Ends With | Text attributes and labels. | | **Number** | Equals, Greater Than, Less Than, Between, In Range | Price tiers, inventory thresholds, review score cutoffs. | | **Date** | Before, After, Between, Within Last N Days, Within Next N Days | Promote products created in the last 30 days, or bury products with a sale-end-date in the past. | | **Boolean** | Is True, Is False | Flags such as in-stock, on-sale, hero-variant, clearance-eligible. | | **SKU and Part Number** | Equals, In List | Both SKU and Part Number variants are now supported — previously only SKU was available. | | **Multi-value** | Contains Any, Contains All, Contains None | Array-style values such as a multi-category tag list or an attribute list with multiple entries per product. | ## How to Use Field-Based Conditions <Steps> <Step title="Open or create a rule"> Open an existing merchandising rule from the listing screen, or create a new rule of any type that supports conditions (Boost, Bury, Include, Exclude, Pin, Slot, or Sort). </Step> <Step title="Add a condition"> In the rule editor, click **Add Condition**. The condition builder opens. </Step> <Step title="Select the field"> Choose the field from the field list. Only Filterable fields appear in this list. If you need a field that isn't showing up, mark it as Filterable in Field Settings and re-index. </Step> <Step title="Choose the operator"> The operator dropdown automatically shows the operators that make sense for the selected field type. For a Number field you'll see Equals, Greater Than, Between, etc. For a Date field you'll see Before, After, Within Last N Days, etc. </Step> <Step title="Enter the value"> Provide the value (or values, for range and list operators). For multi-value support, the editor lets you add multiple values to a single condition. </Step> <Step title="Combine conditions"> Add additional conditions to build compound logic. Conditions are combined with **AND** by default — all conditions must be true for the rule to match a product. You can adjust the logic operator from the condition list. </Step> <Step title="Save and activate"> Save the rule. Toggle to **Active** when you're ready for it to apply on the storefront. </Step> </Steps> ## Example Use Cases * **Boost recently-added premium products** — Create a Boost rule with two conditions: *Created Date is Within Last 30 Days* AND *Price is Greater Than 200*. Surfaces new high-margin inventory at the top of category pages. * **Bury low-stock items quietly** — Create a Bury rule with the condition *Inventory Count is Less Than 5*. Products with limited stock are pushed down without being completely removed, so customers see them only after the higher-stock alternatives. * **Exclude end-of-life products** — Create an Exclude rule with the condition *Discontinued is True*. Products flagged as discontinued in your catalog are kept out of the storefront entirely. * **Promote in-season collections** — Create a Boost rule on the Search scope "winter" with the condition *Tags Contains Any "winter, cold-weather, insulated."* Lifts every product carrying any one of those tags when shoppers search for "winter." * **Surface products by sub-brand or part-number family** — Create a Boost rule with the condition *Part Number Starts With* a specific prefix. Useful for OEM-grouped catalogs where part numbers carry meaningful prefix information about the product family. ## Important Notes <Info> Field-based conditions are only available on rule types that operate on a product selection — Boost, Bury, Include, Exclude, Pin (when filtering the product list before pinning), Slot, and Sort. Variant Slicing and Banner rules use their own configuration models and do not use field conditions. </Info> <Info> **Multi-Value Field Matching:** When using Contains Any or Contains All on a multi-value field, the field must be marked as Multi-Value in Field Settings with the correct delimiter specified. Without this, Experro treats the values as a single string and the match fails. </Info> <Info> **Sensitive Data Fields:** Fields marked as Sensitive Data in Field Settings are available as condition fields in rules. This is intentional — sensitive data such as cost price can drive internal merchandising decisions without being exposed to the storefront. The condition runs server-side; the value is never returned through the Search API. </Info> # Banner Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/banner_rule ## Add Banners to Merchandising Rules After creating and activating a banner, attach it to a Merchandising Rule to control where it appears, on which pages, and for how long. ### Rule Types | **Rule Type** | **Where the Banner Appears** | | -------------------- | ----------------------------------------------------- | | **Global Rules** | Across all applicable discovery pages site-wide | | **Category Rules** | On specific category or collection browse pages | | **Search Rules** | On search result pages, triggered by specific queries | | **Collection Rules** | On custom collection pages created within Experro | ### Attach a Banner to a Rule 1. Navigate to **Discovery → Merchandising**. 2. Select the rule type: **Global**, **Category**, **Search**, or **Collection**. 3. Click **Add Rule** to create a new rule, or open an existing one. <img alt="" /> 4. In the rule configuration screen, locate the **Content & Bundle** section and click **Banner**. <img alt="" /> 5. Complete the banner rule settings: <img alt="" /> ### Configure Banner Rule Settings | Field | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | **Rule Name** | Enter a name to identify the merchandising rule, for example: "Summer Sale — Jewelry Search — June 2025." | | **Banner** | Select the banner from the dropdown. Only banners created in **Discovery → Banners** are available. | | **Banner Position** | Choose the position where the banner should appear on the page (based on the selected layout and page type). | | **Repeat on Pagination** | Enable this option to display the banner on all paginated pages. If disabled, the banner appears only on the first page. | ### Page and Category Selection Use the **Search Category** field to select the category, collection, or search context where the banner should be applied. Once selected, products related to that page are displayed in the **preview area**. ### Schedule the Banner Start and end dates are set at the rule level. 1. Click the **Duration** field in the rule configuration screen. 2. Set a **Start Date** and time. Start date defaults to the current date. 3. Set an **End Date** and time, or leave open for evergreen placements. 4. Click **Apply**. ### Save and Preview <img alt="" /> * **Save** — applies the rule. Once saved and active, the banner displays on the storefront according to the configuration and schedule. * **Preview** — validates banner placement within the product grid before publishing. # Boost/Bury Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/boost_bury Boost and Bury rules allow you to dynamically adjust product rankings in your digital storefront. These rules enable you to fine-tune which products appear more prominently and which are downplayed: * **Boost Rules** elevate a product’s position to increase its visibility and likelihood of purchase. * **Bury Rules** lower a product’s ranking to reduce its prominence. By leveraging these rules, you gain granular control over product display—allowing you to promote high-margin or high-conversion items while demoting products that are less relevant or out of stock. ## Use Case **Scenario:** An online retailer wants to promote new arrivals and demote out-of-season products. **Solution:** * Use **Boost Rules** to increase the visibility of new arrivals. * Use **Bury Rules** to decrease the visibility of out-of-season products. **Outcome:** Enhanced visibility for new products leads to increased sales, while out-of-season products are relegated to lower positions, creating a more engaging and conversion-oriented shopping experience. ## Creating Boost/Bury Rules To create a Boost or Bury rule, follow the steps outlined in the [Configuring Rules Section](/experro_discovery/merchandising/configuring_rules). Once you select the operation as **Boost/Bury**, provide the following details to configure the rule. <img alt="" /> ## Configuration Details When configuring a Boost or Bury rule in Experro, you will need to supply the following details: | **Field Name** | **Description** | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Rule Name** | Enter a unique name for the rule. | | **Operation** | Select the **Operation** as **Boost/Bury** to determine whether the rule will elevate or lower product ranking. | | **Boost/Bury Level Configuration** | Use the slider to adjust the intensity of the boost or bury effect as per your requirement. You will be able to Boost or Bury and adjust the intensity based on how you adjust the slider. | | **Field** | Choose the product attribute (e.g., price, category, stock status) on which to base the rule. | | **Condition** | Select the condition (e.g., equals, contains) to evaluate the selected field. | | **Value** | Specify the value for the condition to trigger the rule. | | **Add Condition** | Optionally, add additional conditions to refine the rule using logical operators (AND/OR). | By following these guidelines, you can effectively configure Boost and Bury rules in Experro, ensuring that your merchandising strategy precisely targets and optimizes product visibility to drive sales and enhance customer satisfaction. # Include/Exclude Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/exclude_include Include/Exclude rules give you precise control over which products must always appear or never appear in search results. These rules enable you to override default search and ranking behavior to meet specific merchandising objectives: * **Include Rules:** Force certain products to be displayed, ensuring that critical items are always visible. * **Exclude Rules:** Prevent certain products from appearing in search results, such as items that are discontinued or out of stock. This functionality is particularly useful when you need to tailor the shopping experience—ensuring that only available, relevant products are shown to your customers. ## Use Case **Scenario:**\ A fashion retailer wants to exclude out-of-stock products from search results and display only products from specific brands. **Solution:** * **Exclude Rules:** Remove out-of-stock products from search results. * **Include Rules:** Ensure that products from selected brands are prominently displayed. **Outcome:**\ Users experience an improved search experience with only available and relevant products, leading to higher engagement and increased conversion rates. ## Creating Include/Exclude Rules To create an Include or Exclude rule, follow the steps outlined in the [Configuring Rules Section](/experro_discovery/merchandising/configuring_rules). Once you select the operation as Include or Exclude, provide the details below to configure the rule. <img alt="" /> ## Configuration Details When setting up an Include or Exclude rule in Experro, you will need to supply the following details: | **Field Name** | **Description** | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | **Rule Name** | A unique name for the rule. | | **Operation** | Select whether the rule is an Include or an Exclude rule. | | **Use Advanced Query Builder** | Toggle this option to enable the advanced query builder. If enabled, click **Open Query Builder** to create complex queries. | | **Field** | If not using the advanced query builder, select the product attribute to base your condition on. | | **Condition** | Choose the condition (e.g., equals, contains) to evaluate the selected field. | | **Value** | Specify the value for the field against which the condition is evaluated. | | **Add Condition** | Option to add additional conditions using logical operators (AND/OR) for a more refined rule. | By following these guidelines, you can effectively configure Include/Exclude rules in Experro to fine-tune your merchandising strategy, ensuring that your digital storefront displays only the most relevant and desirable products. # Pin Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/pin The Pin Rule fixes products in specific positions on a search results page or category page. Beyond pinning at the parent-product level, you can now: ## Pin a Specific Product Variant You can pin at the variant level, not just the parent product. This is useful when a specific color, size, or SKU should lead the page rather than the default variant. <Frame> <img alt="" /> </Frame> To pin a variant: <Steps> <Step title="Open the Pin Rule editor" /> <Step title="Search for the product" /> <Step title="Expand the product to show its variants" /> <Step title="Select the variant you want to pin" /> <Step title="Set the pin position" /> </Steps> ## Drag-and-Drop Pinning Pinned products and variants can be reordered by dragging them into position inside the rule editor. The position number updates automatically as you reorder, removing the need to manually edit position values when reshuffling the pin list. ## Filtering Inside the Rule The Pin Rule editor includes a filter panel so you can narrow the product list before selecting products to pin. Filter by category, attribute, stock status, or any indexed field. This is especially useful on large catalogs where finding the right products in the full list would take longer than using the rule itself. # Slot Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/slot The Slot Rule in Experro allows you to designate specific positions (slots) within search results or category pages for products that meet particular conditions. This ensures that products fitting certain criteria consistently appear within a defined range of positions, thereby enhancing their visibility and aligning with your merchandising strategy. ## Use Case **Scenario:**\ An online electronics store wants to ensure that its top-rated laptops always appear within the first 10 positions of the search results for "laptops." **Solution:**\ Implement a Slot Rule to reserve the top positions (e.g., positions 1 to 10) exclusively for these top-rated laptops. **Outcome:**\ Increased visibility and sales for the top-rated products, as they are prominently displayed within the specified slots, capturing customer attention and driving higher conversion rates. ## Creating Slot Rules To create a Slot Rule, follow the steps detailed in the [Configuring Rules Section](/experro_discovery/merchandising/configuring_rules). Once you select the rule type as Slot, provide the details below to configure the rule. <img alt="" /> ## Configuration Details When configuring a Slot Rule in Experro, you will need to provide the following details: | **Field Name** | **Description** | | ----------------- | ---------------------------------------------------------------------------------------------- | | **Rule Name** | Enter a unique name for the rule. | | **Slot Range** | Specify the start and end positions for the slot range (between 1 and 50). | | **Field** | Select the product attribute on which the rule will be based (e.g., rating, category). | | **Condition** | Choose the condition to evaluate the selected field (e.g., equals, contains). | | **Value** | Specify the value that the selected field should be evaluated against. | | **Add Condition** | Optionally, add additional conditions using logical operators (AND/OR) for further refinement. | By effectively utilizing the Slot Rule, you can ensure that products meeting specific criteria are strategically positioned within search results or category pages. This targeted placement not only enhances customer engagement but also drives higher sales by prominently displaying key products. # Sort Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/sort Sort rules in Experro allow you to define the order in which products are displayed in search results and category pages. By specifying precise sorting criteria, you can ensure that products are presented in a way that aligns with your business objectives—whether that's highlighting the most relevant or highest-rated items. By configuring sort rules, you enhance the user experience by presenting products in a logical, user-friendly sequence (such as sorting by price, popularity, or rating). ## Use Case **Scenario:**\ An online retailer wants to showcase top-rated products by displaying items with the highest ratings at the top of search results. **Solution:**\ Implement a sort rule that arranges products in descending order based on their ratings. **Outcome:**\ Users are quickly guided to the most popular products, resulting in increased customer satisfaction, improved engagement, and higher conversion rates. ## Creating Sort Rules To create a sort rule, follow the steps detailed in the [Configuring Rules Section](/experro_discovery/merchandising/configuring_rules). Once you select the operation as Sort, provide the details below <img alt="" /> ## Configuration Details When configuring a sort rule in Experro, you will need to provide the following details: | **Field Name** | **Description** | | ----------------- | -------------------------------------------------------------------------------------------------- | | **Rule Name** | Enter a unique name for the rule. | | **Field** | Select the product attribute you want to use for sorting (e.g., rating, price, popularity). | | **Order** | Choose the sort order: *Ascending* (low to high) or *Descending* (high to low). | | **Add Condition** | Optionally, add additional conditions using logical operators (AND/OR) to further refine the rule. | ## Key Considerations * **Mutual Exclusivity:**\ When a sort rule is active, you cannot use boost, bury, slot, or pin rules simultaneously. Only include or exclude rules may be applied in conjunction with sort rules. * **Rule Priority:** If multiple rules are configured for the same duration and conditions, they will be applied in this order: * **Overall Rule Priority:** Pin → Slot → Boost/Bury/Include/Exclude * **Within Boost/Bury/Include/Exclude:** Exclude → Include → Bury → Boost *Example:* If both Boost and Bury rules are set, the Bury rule takes precedence, overriding the Boost rule. By effectively utilizing sort rules, you can control the sequence of product displays, ensuring that users see the most relevant items first. This alignment with your merchandising strategy not only improves the overall shopping experience but also drives higher engagement and sales. # Overview Source: https://help.experro.com/experro_discovery/merchandising/rule_types/types_of_rules Experro Merchandising leverages a versatile rule-based system to give you precise control over your product displays. In this section, you'll discover the various types of rules available — each designed to tailor your digital storefront to meet your unique business objectives. Whether you're aiming to elevate high-conversion items, filter out non-essential products, control which product variant leads the result tile, or curate a personalized shopping experience, these rules empower you to dynamically adjust product visibility and ranking. With Experro's intuitive interface and comprehensive customization options, you can easily create, modify, and manage these rules, ensuring that the right products reach the right customers at the right time. <CardGroup> <Card title="Boost/Bury Rule" href="/experro_discovery/merchandising/rule_types/boost_bury"> Adjust product rankings dynamically by boosting or burying items based on strategic priorities, seasonal trends, or performance metrics. </Card> <Card title="Include/Exclude Rule" href="/experro_discovery/merchandising/rule_types/exclude_include"> Precisely control product visibility by including or excluding specific items from search results or collections. </Card> <Card title="Pin Rule" href="/experro_discovery/merchandising/rule_types/pin"> Securely position key products — or specific product variants — at the top of search results or category pages, with drag-and-drop ordering. </Card> <Card title="Slot Rule" href="/experro_discovery/merchandising/rule_types/slot"> Allocate specific products to designated positions within a listing. </Card> <Card title="Sort Rule" href="/experro_discovery/merchandising/rule_types/sort"> Define the default sorting logic for product listings, such as by popularity, price, or newest arrivals. </Card> <Card title="Variant Slicing Rule" href="/experro_discovery/merchandising/rule_types/variant_slicing"> Control which variant of a multi-variant product appears as the lead tile on the results page. </Card> <Card title="Banner Rule" href="/experro_discovery/merchandising/rule_types/banner_rule"> Insert promotional content within PLPs or category pages to highlight key campaigns. </Card> </CardGroup> # Variant Slicing Rule Source: https://help.experro.com/experro_discovery/merchandising/rule_types/variant_slicing A Variant Slicing Rule controls which variant of a multi-variant product appears as the lead tile on a results page. For example, a shirt that comes in five colors will, by default, display whichever variant the system selects. With a Variant Slicing Rule, you can force the red variant to lead on the "summer sale" search, and the navy variant to lead on the "office wear" category page. <Frame> <img alt="" /> </Frame> ## When to Use a Variant Slicing Rule * **Seasonal campaigns** — Show the lightweight variant of a jacket on warm-weather search queries and the insulated variant during winter promotions. * **Color-led merchandising** — Lead with the trending color on category pages without removing other variants from search. * **Inventory-driven display** — Surface variants with healthy stock instead of letting low-inventory variants take the lead tile. ## Creating a Variant Slicing Rule <Steps> <Step title="Open the Add Rule pop-up and choose scope"> Click Add Rule and choose the scope in the pop-up (Global, Category, or Search) following the standard scope selection flow described in Configuring Rules. </Step> <Step title="Choose Variant Slicing as the rule type"> Provide a Rule Name and Description, then select Variant Slicing as the rule’s functionality. </Step> <Step title="Choose the variant attribute to slice on"> Select the variant attribute that determines which variant leads the tile. Common attributes include color, size, and material. Only attributes defined as variant-level in your catalog appear in the list. </Step> <Step title="Define the variant priority order"> Set the order of values for the chosen attribute. The first value that matches a product's available variants becomes the lead tile. For example, with attribute color and priority order Red, Navy, Black: a product available in Red and Navy displays Red; a product available only in Navy and Black displays Navy. Use the filter panel to narrow the product list while building the rule. </Step> <Step title="Set duration and save"> Set a start and end date if the rule is time-bound. Save the rule. It will be created as Inactive — toggle to Active when you’re ready for it to apply on the storefront. </Step> </Steps> ## Catalog Setup Prerequisites Before a Variant Slicing Rule can take effect on the storefront, the catalog itself must be set up to support variant slicing. The rule operates on top of catalog-level configuration — without that foundation, the rule has nothing to act on. * **Mark the slicing attribute as a Variant Option.** In Field Settings, the field you want to slice on (color, size, metal type, material) must be marked as a Variant Option so Experro recognizes it as a variant-level attribute. * **Ensure values are populated.** Every product you want the rule to affect must have values for the chosen variant attribute. Products missing values fall back to default tile behavior. * **Configure a Hero Variant field (recommended).** Mark one variant per product as the default lead variant using a Boolean field at the variant level. This gives the algorithm a reliable fallback when no rule or search signal dictates which variant to surface. <Tip> For full catalog-level setup details, refer to the Algorithm & Field Settings documentation, specifically the Variant Slicing Setup section under Algorithm — Relevance. </Tip> ## How Variant Slicing Resolves on the Storefront A Variant Slicing Rule does not decide the lead variant in isolation. It participates in a priority order that combines explicit search intent, active rules, personalization, and catalog defaults. When multiple signals are in play, Experro applies them in this order (highest priority first): <Steps> <Step title="Explicit search intent"> If the user's search query contains an NLP-tagged value matching the slicing attribute — for example, "red dress" on a color-sliced rule — that value wins. Experro surfaces the red variant regardless of what the rule says, because the user explicitly asked for red. </Step> <Step title="Active Variant Slicing Rule"> If a Variant Slicing Rule is active for the current scope (search term or category), its priority order determines which variant leads the tile. The first value in the rule's priority list that matches a product's available variants is selected. </Step> <Step title="Personalization signal"> If no rule applies and the user has built up a strong affinity for a specific value (for example, a long history of viewing navy products), personalization may surface the navy variant on relevant queries. </Step> <Step title="Hero Variant"> If a Hero Variant is marked on the product, it is shown as the default lead. This is the typical behavior on category pages and unspecific search queries where no other signal is present. </Step> <Step title="System default"> If none of the above apply — no rule, no signal, no Hero Variant — Experro picks the best-performing variant based on its internal ranking model. </Step> </Steps> ## Working With Hero Variant Hero Variant and Variant Slicing Rules are designed to work together, not in conflict. The Hero Variant field is the catalog-level default — the variant a merchandiser has marked as the preferred lead. A Variant Slicing Rule is a contextual override that only fires for specific search queries or category pages. A common pattern: mark the best-selling color of each product as Hero Variant in the catalog so it leads by default everywhere. Then add a Variant Slicing Rule scoped to specific seasonal searches ("winter coats," "summer dresses") to override the default with a seasonally-appropriate variant on those queries only. ## Key Considerations <Warning> **One Active Variant Slicing Rule Per Scope:** You can have only one Active Variant Slicing Rule per scope. Two active Variant Slicing Rules cannot exist on the same search term or category. </Warning> <Note> **Catalog Requirements:** Variant Slicing requires variant-level attributes in your catalog. If a product has no variants for the chosen attribute, the rule has no effect on that product and it falls back to default tile behavior. </Note> # Rules Source: https://help.experro.com/experro_discovery/merchandising/rules Experro Merchandising Rules form the foundation of our rule-based merchandising system, granting you complete control over how products are displayed — or hidden — on your digital storefront. This powerful approach allows you to tailor the shopping experience to meet your specific business goals. Whether you need to boost high-margin items during a promotional event, demote products that are underperforming, or customize displays for different customer segments, our system enables you to present the right products to the right users at precisely the right time. <Frame> <img alt="" /> </Frame> ## Key Points * **Flexibility in Merchandising:** The rule-based system supports a variety of strategies — from emphasizing new or popular products to de-prioritizing outdated or low-stock items — allowing for tailored product curation across all channels. * **Wide Range of Rule Types:** Experro supports multiple types of merchandising rules to fit various scenarios, including: * **Boost Rules:** Elevate the ranking of selected products. * **Bury Rules:** Lower the ranking of specified products. * **Include/Exclude Rules:** Force the presence or absence of certain products. * **Sort Rules:** Rearrange products based on defined criteria. * **Pin Rules:** Fix products or specific product variants in a defined position. * **Slot Rules:** Reserve a specific range of positions for targeted products. * **Variant Slicing Rules:** Control which variant of a multi-variant product appears as the lead tile. * **Banner Rules:** Place promotional content within product listings. Each rule type can be configured with precise conditions tailored to your catalog and business objectives. For detailed configuration steps, best practices, and technical documentation on each rule type, please refer to [Configuring Rules](/experro_discovery/merchandising/configuring_rules) and [Types of Rules](/experro_discovery/merchandising/rule_types/types_of_rules) from our resource center. # Scope of Rules Source: https://help.experro.com/experro_discovery/merchandising/scope_of_rules Experro Merchandising rules provide granular control over how products are presented across your digital storefront. With a layered system, you can apply these rules at different levels to meet both broad site-wide objectives and specific contextual needs, ensuring that each customer receives the most relevant product display. <Frame> <img alt="" /> </Frame> ## Global Rules (Site Rules) Global rules — sometimes referred to as site rules — apply universally across your entire website. They serve as a consistent baseline for your merchandising strategy by automatically affecting every search query and category page. * **Application:** Global rules are ideal for site-wide promotions, such as boosting high-margin products or consistently demoting underperforming items. * **Example:** Use global rules to promote high-margin products across the entire site or to demote underperforming items, ensuring a continuous influence on product ranking regardless of individual user searches. ## Category Rules Category rules allow you to tailor product displays for specific product categories. This ensures that the shopping experience is fine-tuned to each category's unique characteristics. * **Application:** These rules are applied only when customers browse a particular category, enabling targeted promotions and display adjustments. * **Example:** If a retailer wants to prioritize a specific brand of shoes within the "Footwear" category, a category rule can be created to boost those products exclusively when that category is being viewed. When you choose Category as the scope, you can apply the rule in one of two ways: * **All Categories** — The rule applies to every category page across your storefront. Use this when you want the same product behavior on all category pages without creating a Global rule that also affects search results. * **Specific Categories** — The rule applies only to the categories you select. Use this for category-by-category tuning. ## Search Rules Search rules are designed to customize search results based on specific keywords or search queries. They dynamically adjust product rankings according to customer search behavior and intent. * **Application:** These rules ensure that, when a customer enters a query like "running shoes" or "formal footwear," the most relevant and profitable products are featured prominently at the top of the results. * **Example:** A search rule can be configured to elevate products that best match the customer's query, ensuring that high-demand items are always displayed first. When you choose Search as the scope, you can apply the rule in one of two ways: * **All Searches:** The rule applies to every search query on your storefront. Use this when you want consistent behavior across the search experience without affecting category pages. * **Specific Searches:** The rule applies only to the search terms you enter. For each search term, you set a qualifier (operator) that controls how the term is matched against incoming queries. Available qualifiers include Equal to, Contains, Starts with, and Ends with. Use Equal to for exact-match terms (for example, "running shoes") and Contains or Starts with when you want a single rule to cover a family of related queries (for example, every query that contains "diamond"). ## One Active Rule Per Scope To prevent conflicting behaviors on the same surface, the following restriction applies. <Warning> You can have only one Active rule per scope, per rule type. For example, you can have one active Pin Rule and one active Variant Slicing Rule on the search term "running shoes," but not two active Pin Rules on the same term. If you try to activate a rule whose scope is already covered by another active rule of the same type, Experro flags the conflict and asks you to deactivate the existing rule first. </Warning> This restriction makes the rule hierarchy easier to reason about and removes the need to debug stacked rules competing for the same position. ## Integrated Strategy By combining Global, Category, and Search rules — and within each, the choice between an "all" application and a specific application — Experro Discovery provides a robust and dynamic merchandising framework. Each level addresses different aspects of your digital storefront. This layered approach allows you to: * Maintain consistent product presentation across the entire site. * Tailor displays to specific customer segments or product categories. * Dynamically adjust to changing search queries and customer behaviors. This comprehensive strategy empowers you to optimize product visibility and drive higher conversion rates by ensuring that every product placement aligns with your business objectives. # Recommendations Analytics Source: https://help.experro.com/experro_discovery/recommendations/analytics Navigate to **Recommendations → Analytics** from the left-hand navigation to unlock rich insights into how your AI-powered widgets are performing and driving revenue. <img alt="" /> ## Overview The **Overview** panel gives you a high-level snapshot of overall engagement and top performers: * **Key Metrics** * **Impressions**: Total times recommendation widgets were shown * **Clicks**: Number of widget clicks * **Add-to-Cart**: Items added to cart via a recommendation * **Orders**: Completed orders originating from a recommendation * **Conversion Rate**: Represents the percentage of views of recommended products that resulted in actual orders. * **Revenue**: Gross sales attributed to recommendations * **Configurable Time Series Graph**\ Select any two metrics (e.g. Impressions vs. Revenue, Orders vs. Clicks) for the X- and Y-axes to spot trends over your chosen time window. * **Top Widgets**\ A list of your highest-engaged recommendation widgets by impressions, clicks, or conversion. * **Top Products**\ Your best-performing SKUs across all widgets, ranked by revenue. ## Widget Analysis This section represents a deep dive into the performance of individual widgets. See widget-level impressions, clicks, carts, orders, conversion rate, and revenue in a compact summary. ## Revenue Reports Measure the true business impact of your recommendations: * **Revenue** Represents the total amount generated from the orders placed by shoppers. * **Direct Revenue**\ Represents the amount generated from the orders placed by shoppers without recommendation. * **Recommendation Revenue**\ Sum of all sales driven by recommendation widgets. * **Revenue Trend Chart**\ A time series plotting Direct Revenue and Recommendation Revenue to visualize how recommendations contribute over time. * **Top Revenue-Generating Widgets**\ A ranked list of widgets by total revenue, letting you quickly identify your highest-ROI placements and algorithms. By combining these three analytics sections—**Overview**, **Widget Analysis**, and **Revenue Reports**—you’ll gain a 360° view of how your Experro Recommendations drive engagement, conversions, and revenue across your entire storefront. # Configure Algorithm Source: https://help.experro.com/experro_discovery/recommendations/configure_algorithm Use this page to fine-tune how Experro’s AI recommendation algorithms behave for each widget. You can select or swap models, adjust training cadence, weight user actions, set similarity attributes, and define session-based rules—all without touching code. <Note> Any updates you make to the model will be applied during the next training session. </Note> <img alt="" /> ## Configurations ### Recommendation Model Training * **Disable Model Training** (toggle)\ Turn off automated training if you want to freeze the model in its current state. * **Frequency for Model Training**\ Specify how often (in days) Experro retrains this algorithm with fresh data. This field is available on if you keep the **Disable Model Training** toggle off. Example: “Weekly” runs weekly retraining. ### Metrics & Weightage Adjust how much each type of user interaction influences your recommendations: * **Clicks** * **Add to Cart** * **Orders** <img alt="" /> <Tip>- Increase the weight for “Orders” to prioritize products that actually convert. <br /><br />- Increase the weight for “Add to Cart” to promote products that are actively considered but not yet purchased. <br /><br />- Increase the weight for “Clicks” to surface products that are frequently engaged with but not necessarily bought.</Tip> ### Timeframe Sliding window (in days) over which user activities are considered for generating personalized recommendations. Behaviors older than this window have diminishing influence. <img alt="" /> <Tip>Set a longer timeframe if you want to capture long-term browsing patterns. A shorter window is useful for reflecting recent trends and seasonality.</Tip> ### Threshold Value Threshold Value for Recommendation AI Model. Controls how “strict” or “broad” matches must be for recommendations to surface. * **Guidance:** * Lower = broader matches (risk of irrelevant suggestions) * Higher = stricter relevance (fewer but more accurate picks) <img alt="" /> <Note> To change this setting beyond the UI default, please contact our support team.</Note> ### Attributes for Similarity Select fields for similarity. Pick the product attributes (e.g., Name, Brand, Category, Price) that the algorithm uses to determine “similarity”. Matching on the right attributes ensures more meaningful “Similar Products” and “Frequently Viewed Together” recommendations. <img alt="" /> ### Configure Algorithm Sessions Fine-tune how Experro interprets in-session user behavior to train co-occurrence-based recommendation algorithms more accurately. By defining the minimum number of interactions required for signals to be counted as meaningful, you can balance precision with coverage across your catalog. <img alt="" /> | Metric | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Viewed Together in a Session** | The number of times a product needs to be viewed in the same session as another product to be considered a “viewed together” match. | | **Bought Together in a Session** | The number of times a product needs to be bought in the same session as another product to be considered a "bought together" match. | <Tip> Setting these to “3” is recommended for most catalogs as per the industry standards. </Tip> ## Exclusion Rules Use **Exclusion Rules** to prevent certain SKUs or categories from ever appearing in a widget’s results. <img alt="" /> 1. Navigate to the **Exclusion Rules** tab. 2. Next, select the **Product Rule** or **Category Rule** tab to exclude specific products or categories from a widget. Select **Purchased Product** to exclude products that have been purchased. 3. Add Products or Categories to exclude based on the tab that you have selected. Once you’ve finished configuring each section above, click **Save** to confirm your changes. Your new settings will take effect with the next model training cycle—delivering more precise, personalized suggestions on your storefront. # Create Widgets Source: https://help.experro.com/experro_discovery/recommendations/create_widgets Follow these steps to create a new AI-powered recommendation widget in Experro: <Steps> <Step title="Open the Recommendations Tab"> * In the left navigation panel, click **Discovery → Recommendations**. * The menu has three further options: **Home**, **Analytics**, and **Widgets**. * Select **Widgets** to see your existing widgets and then click on the **Add Widget** button to create a new widget. <img alt="" /> </Step> <Step title="Launch the Add Widget Flow"> * Click **Add Widget**. * A full-screen panel appears listing all available recommendation algorithms (RFY, Frequently Bought Together, Similar Products, etc.). <img alt="" /> </Step> <Step title="Choose Your Algorithm"> * Find and click the algorithm that fits your goal (e.g. “Recommended For You” for personalized picks). * Each algorithm tile includes a brief use case description. </Step> <Step title="Name & Describe"> * In the modal that appears, fill out: * **Widget Name**: A descriptive title (e.g. “Homepage RFY Carousel”). * **Description** (optional): Notes for your team about placement, audience, or context. * Click **Save** to create your widget. <img alt="" /> </Step> <Step title="Configure Your Default (Global) Rule"> * You’re taken to the widget’s Rules screen. * A **Global** rule is selected by default—any merchandising or fallback settings configured here apply wherever this widget is rendered (homepage, PDP, cart). * Global rule is mandatory; you cannot remove it. </Step> <Step title="Add Page-Level Overrides (Optional)"> * To customize behavior on specific pages, click **Add Rule** and provide the following details : * **Rule Name**: A descriptive title. * **Description**: Notes for your team. * **Rule Type**: Select Homepage, Product, or Cart based on the context you want to target. <img alt="" /> * Each page-level rule overrides the Global rule for that context, whether Homepage, Product, or Cart page.\ <Note>You may only have one rule active for each context in a given time window.</Note> </Step> <Step title="Edit a Rule"> * Click the **Edit Rule** option against the global rule or the **Edit** option under **Actions** next to custom created widget rules. * Toggle **Merchandising** on/off and configure boost/pin/slot/sort/include/exclude rules. * Toggle **Fallback Algorithm** on/off and select your backup recommendation engine. * Click **Save** within the rule editor to apply. <img alt="" /> </Step> <Step title="Activate & Publish"> * Once all rules and settings are configured, toggle your widget **Active** if it is not already active. * Navigate to **Content Library** to map the widget you created to the storefront. * Read about [Publishing Widgets on Storefront](/experro_discovery/recommendations/mapping_widgets_to_storefront) to publish the widget on your storefront. </Step> </Steps> > **Key Concepts** > > * **Global Rule:** Applies everywhere the widget appears. > * **Page-Level Rule:** Overrides Global on homepage, product, or cart. > * **Only one rule per page type** may be active at any given time. > * **Merchandising + Fallback** toggles live inside each rule’s editor. Now that your widget and rules are in place, explore [Recommendation Algorithms](/experro_discovery/recommendations/recommendation_algorithms) to learn more about each algorithm. # Publishing Widgets on Storefront Source: https://help.experro.com/experro_discovery/recommendations/mapping_widgets_to_storefront Once your widget and rules are configured, use the Visual Builder to drag & drop it onto any page—no coding required. <Steps> <Step title="Open the Content Library"> * From the left navigation panel, navigate to **Content → Content Library → Webpages** * Find and click the page where you want to add your recommendation widget. </Step> <Step title="Launch the Visual Builder"> * On your chosen page, click **Visual Builder**. * The page preview loads alongside the Visual Builder sidebar. </Step> <Step title="Locate Recommendation Widgets"> * In the Visual Builder panel, navigate to the **Recommendation Widgets**. * You’ll see one tile per algorithm type (RFY, Frequently Bought Together, etc.). </Step> <Step title="Drag & Drop Your Widget Type"> * Click and drag the tile for your desired algorithm onto the preview canvas where you’d like it to appear. * A configuration prompt appears on the Visual Builder sidebar. </Step> <Step title="Select Your Widget Instance"> * In the prompt, click **Select Widget**. * Choose the specific widget you created (by name) from the dropdown list. </Step> <Step title="Save & Publish"> * Click **Save** in the Visual Builder toolbar to commit changes. * Then click **Publish** to push the updated page live on your storefront. </Step> </Steps> <Note> You can reposition or remove recommendation widgets at any time by reopening the Visual Builder for that page. </Note> # Overview Source: https://help.experro.com/experro_discovery/recommendations/overview Experro Recommendations enable you to deliver highly personalized and contextual product suggestions across your storefront—automatically. Whether it's showcasing frequently bought items on the cart page or suggesting alternatives on product detail pages, Recommendations help you create engaging experiences that boost conversions, order value, and customer satisfaction. <img alt="" /> This section walks you through the **core workflows and configurations** required to set up and manage recommendation widgets—no coding required. ## How Recommendations Work in Experro Experro’s AI-powered engine (Eywa) combines **real-time user behavior**, **intent understanding**, and **affinity patterns** to generate precise product suggestions. Merchants can fine-tune these outputs through rules and merchandising controls, ensuring alignment with business goals. ## Available Recommendation Algorithms Experro offers a diverse set of prebuilt algorithms designed for specific use cases: <CardGroup> <Card title="Recommended For You" href="/experro_discovery/recommendations/recommendation_algorithms/recommended_for_you"> Personalized picks based on user behavior and interests. </Card> <Card title="Frequently Bought Together" href="/experro_discovery/recommendations/recommendation_algorithms/frequently_bought_together"> Cross-sell logic based on transactional patterns. </Card> <Card title="Frequently Viewed Together" href="/experro_discovery/recommendations/recommendation_algorithms/frequently_viewed_together"> Surface items often viewed in close succession to the current product </Card> <Card title="Similar Products" href="/experro_discovery/recommendations/recommendation_algorithms/similar_products"> Showcase visually or semantically similar alternatives </Card> <Card title="Popular Products" href="/experro_discovery/recommendations/recommendation_algorithms/popular_products"> Highlight top-performing, trending SKUs </Card> <Card title="Hot New Releases" href="/experro_discovery/recommendations/recommendation_algorithms/hot_new_releases"> Display the newest arrivals or collections </Card> <Card title="Best Sellers" href="/experro_discovery/recommendations/recommendation_algorithms/best_seller"> Rank by highest sales across store or category </Card> <Card title="Recently Purchased" href="/experro_discovery/recommendations/recommendation_algorithms/recently_purchased"> Remind shoppers of items they've recently bought across sessions </Card> <Card title="Recently Viewed" href="/experro_discovery/recommendations/recommendation_algorithms/recently_viewed"> Suggest recently viewed products to keep shoppers engaged </Card> <Card title="Pick-up Where You Left Off" href="/experro_discovery/recommendations/recommendation_algorithms/pick_up_where_you_left_off"> Let users pick up where they left off </Card> <Card title="Inspired by Your Browsing History" href="/experro_discovery/recommendations/recommendation_algorithms/inspired_by_your_browsing_history"> Contextual results based on user's browsing history </Card> <Card title="Query-Based Recommendations" href="/experro_discovery/recommendations/recommendation_algorithms/query_based"> Dynamic suggestions based on search intent. </Card> </CardGroup> <Note> Explore each algorithm in detail in its [dedicated section](/experro_discovery/recommendations/recommendation_algorithms), including configuration steps, applicable rule types, and visual behavior. </Note> ## Recommendation Setup Flow Here’s a high-level view of how you’ll work with Recommendations inside Experro: <Steps> <Step title="Widget Creation"> Begin by adding a new widget from the **Recommendations** section in your admin panel. Choose the algorithm that fits your use case. </Step> <Step title="Rule Configuration"> Customize widget behavior using rules—global, query-based, page-specific, or category-level. You can also layer in merchandising logic like Boost/Bury or Pin/Slot rules. </Step> <Step title="Design & Layout"> From the **Content** tab, adjust layout settings: card formats, carousels, grid structure, labels, titles, and more. Map the created widget to the UI element where you want the recommendation widget to appear on the storefront. </Step> <Step title="Schedule & Publish"> Set activation timelines for seasonal or promotional widgets, then publish to go live instantly—no development effort required. </Step> </Steps> > Ready to get started? Begin by [creating your first widget.](/experro_discovery/recommendations/create_widgets) # Best Seller Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/best_seller The **Best Sellers** algorithm surfaces your top-performing products—those with the highest sales volume and revenue over a recent period. By showcasing proven favorites, you build trust, leverage social proof, and drive additional conversions across your storefront. <img alt="" /> <Tip>Recommended Placements <br /><br />**Home Page** : Showcase the site-wide best sellers to new visitors.\ <br />**Category Pages** : Highlight top-selling items within each category (e.g., “Top-Rated Boots”).\ <br />**Product Pages** : Display “Best Sellers” in the same category to encourage cross-selling. </Tip> ## How It Works 1. **Sales Data Aggregation**\ Continuously ingests transaction records to track purchase frequency, quantities sold, and total revenue per SKU. 2. **Time-Window Analysis**\ Applies a configurable look-back period (e.g., 7, 30, or 90 days) so that best sellers reflect current buying trends. 3. **Contextual Scoping** * **Global:** Ranks the entire catalog. * **Category:** Limits to items within the current category context. * **Product Page:** Recommends other best-selling items related by category or tag. 4. **Dynamic Updating**\ Automatically refreshes rankings in real time as new sales occur, ensuring recommendations stay up-to-date. ## Supported Rule Types * **Global** * **Home Page** * **Category** * **Product** ## When to Use * **Boost Social Proof:** Leverage proven favorites to reassure shoppers and reduce decision fatigue. * **Engage New Visitors:** For users with no history, best sellers provide a strong starting point. * **Seasonal Campaigns:** Align “Best Sellers” with seasonal collections (e.g., “Summer Best Sellers”). ## Example A shopper views a **Sofa** product page: 1. The **Best Sellers** widget displays the top 6 sofas by sales volume over the last 30 days. 2. As the customer browses, real-time sales updates ensure the list reflects any new top performers. By highlighting your most popular items, you tap into collective buying behavior—driving trust, engagement, and incremental revenue. # Frequently Bought Together Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/frequently_bought_together The **Frequently Bought Together**(FBT) widget uncovers items that customers often purchase in the same transaction—empowering you to present complementary products at exactly the right moment. FBT drives incremental revenue through cross-sell and up-sell opportunities on product detail pages, cart pages, and beyond. <img alt="" /> <Tip> **Recommended Placements**\ <br />**1. Product Page:** Show “Customers Also Bought” for the current item\ <br />**2. Cart Page:** Surface related accessories for items in cart\ <br />**3. Homepage:** Generic “Customers Also Bought” carousel for returning shoppers </Tip> ## How It Works The algorithm analyzes customers' purchase histories to find patterns of frequently bought products. It uses artificial intelligence techniques to find patterns, and then it gives recommendations that the customer intends to buy together 1. **Purchase Pattern & Association Rule Mining**\ Analyzes historical order data to identify items frequently bought together. 2. **Collaborative Filtering**\ Uses AI techniques to surface strong item-pair associations. ## Supported Rule Types You can scope FBT behavior at multiple levels, each of which can override the global settings: * **Global** (default for all placements) * **Home Page** * **Product Page** * **Cart Page** ## Behavior for Non-Logged-In Users * **With Session Activity:**\ Displays FBT based on items added or viewed in the current session. * **Brand-New Visitors:** * **Fallback Disabled:** On the product page, users will find suggestions to help them get started with the product. If the user is on the home page, it will not show any suggestions because there is no browsing history. * **Fallback Enabled:** Shows fallback algorithm suggestions to mitigate cold-start. On the product page, users will see suggestions for getting started with the product. When the user is on the home page, there are no suggestions due to the absence of browsing history. Instead, products will be displayed from Fallback. ## Behavior for Logged-In Users * **Returning Customers:**\ Leverages both their past purchase history and current session to fine-tune FBT picks. * **Freshly Registered (No History):** * **Fallback Disabled:** On the product page, users will find suggestions to help them get started with the product. If the user is on the home page, it will not show any suggestions because there is no browsing history. * **Fallback Enabled:** Fallback suggestions fill the widget, guiding new users. On the product page, users will see suggestions for getting started with the product. When the user is on the home page, there are no suggestions due to the absence of browsing history. Instead, products will be displayed from Fallback. ## When to Use FBT * **Complementary Products:** Recommend laptop bags, mice, or chargers alongside laptops. * **Accessory Upsells:** Suggest batteries or memory cards on electronics PDPs. * **Bundle Promotions:** Highlight “frequently bought combos” during checkout to lift AOV. ## Example Scenario 1. A shopper views a **leather armchair** on your PDP. 2. FBT detects that past buyers often also purchased a **throw pillow**, **footrest**, and **side table**. 3. A “Frequently Bought Together” carousel appears beneath the product details—showing those complementary items. # Frequently Viewed Together Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/frequently_viewed_together The **Frequently Viewed Together** widget analyzes what products customers tend to browse in the same session and surfaces those as suggestions—helping shoppers discover complementary items and boosting engagement. <img alt="" /> <Tip> **Recommended Placements**\ <br />**1. Product Page:** Show items often viewed alongside the current product\ <br />**2. Cart Page:** Suggest related products based on cart contents\ <br />**3. Checkout:** Offer last-minute browsed items before purchase\ <br />**4. Homepage:** Display a generic “Customers Also Viewed” feed for returning visitors </Tip> ## How It Works 1. **Interaction Matrix Construction**\ The algorithm builds a customer–product matrix capturing views and clicks. 2. **Similarity Computation**\ Products that frequently co-occur in the same sessions receive higher similarity scores, reflecting their propensity to be viewed together. 3. **Session Context Boosting**\ If the shopper has active session data, products viewed earlier in that session are boosted to the top of the recommendations. 4. **Fallback Handling**\ When no session or historical view data exists, an optional fallback algorithm (e.g., popular or hot new items) can fill the widget to avoid an empty state. ## Supported Rule Types You can scope FVT behavior at multiple levels, each of which can override the global settings: * **Global** (default for all placements) * **Home Page** * **Product Page** * **Cart Page** ## Behavior for Non-Logged-In Users * **With Session Activity:** Displays FVT based on products viewed in this session. * **Brand-New Visitors:** * **Fallback Disabled:** If the user is on the product page, it will show the suggestions that are made to get started with the current product. ⦁ If the user is on the home page, it will not show any suggestions because there is no browsing history. * **Fallback Enabled:** Shows fallback algorithm suggestions to mitigate cold start. ## Behavior for Logged-In Users * **Returning Customers:** Combines long-term view history with current session to refine FVT picks. * **Newly Registered (No History):** * **Fallback Disabled:** If the user is on the product page, it will show the suggestions that are made to get started with the current product. ⦁ If the user is on the home page, it will not show any suggestions because there is no browsing history. * **Fallback Enabled:** Fallback suggestions fill the widget, guiding new users. ## When to Use FVT * **Complementary Discovery:** Offer accessories or variants frequently explored together (e.g., phone cases with smartphones). * **Browsing Inspiration:** On PDPs, help shoppers discover related products they might otherwise miss. * **Cart Encouragement:** Surface recently viewed items to reduce drop-off before purchase. ## Example Scenario 1. A shopper views a **linen summer dress** on your PDP. 2. FVT identifies that other customers often also viewed a **straw hat**, **sunglasses**, and a **woven tote bag**. 3. A “Frequently Viewed Together” carousel appears—encouraging the shopper to explore those complementary items. # Hot New Releases Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/hot_new_releases The **Hot New Releases** algorithm surfaces the freshest additions or fastest-rising items in your catalog—keeping your storefront dynamic and on-trend. By combining product launch dates with real-time popularity signals, it delivers a curated feed of new arrivals and trending content that drives discovery and repeat visits. <img alt="" /> <Tip>Recommended Placements <br /><br />**1. Home Page** : Showcase the latest arrivals to capture visitor interest immediately.\ <br />**2. Category Pages** :Highlight new releases within that category (e.g., “New in Electronics”).\ <br />**3. Product Pages** :Suggest complementary new products alongside the viewed item.</Tip> ## How It Works 1. **Release Date Tracking**\ Products are tagged with their launch date. The algorithm prioritizes the most recent entries in your catalog. 2. **Popularity Signals**\ Early engagement metrics (views, clicks, add-to-carts) within a defined window boost items that show strong initial traction. 3. **Hybrid Ranking**\ A combined score of freshness (release recency) and momentum (popularity) determines the final ordering. <Note> Boost, Bury, and Sort rules do **not** apply to Hot New Releases. You can still use Pin, Slot, Include, and Exclude to further refine placement.</Note> ## Supported Rule Types * **Global** * **Home Page** * **Category** * **Product** ## When to Use * **Seasonal Launches**\ Promote limited-edition or seasonal products right when they drop. * **Trend Spotting**\ Surface viral or high-momentum items to capitalize on emerging trends. * **Catalog Refresh**\ Keep returning shoppers engaged by always showing something new. ## Example A shopper lands on the **Home Page** of a fashion store: 1. **Hot New Releases** displays a carousel of the newest jackets and accessories launched in the past two weeks. 2. Clicking into **“New Arrivals”** in the “Outerwear” category shows only the latest coats tagged by release date. 3. On a specific **Jacket** product page, a “Hot New Releases” widget recommends other recently added jackets that are quickly gaining popularity. By spotlighting fresh inventory, you keep your storefront feeling alive and give customers a reason to return—fueling engagement and conversions. # Inspired by Your Browsing History Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/inspired_by_your_browsing_history The **Inspired by Your Browsing History** algorithm refines recommendations by mining a shopper’s past interactions—both within the current session and across previous visits. By blending session-based signals with content-based analysis of viewed items, IBYBH delivers highly personalized suggestions that resonate with each user’s unique interests. <img alt="" /> ## How It Works 1. **Session-Based Modeling**\ Examines the sequence of pages visited, dwell times, and in-session interactions to surface products aligned with the user’s immediate browsing context. 2. **Content-Based Analysis**\ Analyzes attributes (e.g., category, brand, features) of items the user engaged with, building a profile of their long-term preferences. 3. **Hybrid Scoring**\ Combines session and content signals into a unified relevance score, ranking products that best match both recent and historical behaviors. ## Supported Rule Types * Global * Home Page * Product * Category * Search ## Behavior ### Non-Logged-In Users * **With Session Data:** IBYBH populates recommendations based on items viewed in the current session. * **Cold-Start (No Views):** * **Fallback Disabled:** Widget remains hidden. * **Fallback Enabled:** Displays a fallback algorithm (e.g., “Popular Products”) to avoid empty slots. ### Logged-In Users * **With Past & Current Sessions:** Leverages full browsing history across sessions for deeper personalization. * **New Accounts (No History):** * **Fallback Disabled:** Widget remains hidden until interaction data is collected. * **Fallback Enabled:** Shows fallback recommendations to guide first-time visitors. ## When to Use * **Personalized Engagement:** Deliver tailored suggestions that adapt to both immediate interests and established affinities. * **Feed-Based Discovery:** Enhance “infinite scroll” or content-feed experiences where users expect a continuous flow of relevant items. * **Multi-Session Continuity:** For returning shoppers, maintain personalized continuity across visits without manual curation. ## Example 1. A shopper browses several **bohemian dresses** across multiple sessions. 2. IBYBH analyzes both their recent clicks and overall browsing patterns. 3. On the **Homepage**, the widget surfaces new boho-style dresses and complementary accessories. 4. On a **Product Page**, it highlights the exact dress previously viewed plus similar items in matching colors or prints. By weaving together session context and content attributes, IBYBH keeps recommendations fresh, relevant, and deeply personalized—turning every visit into a bespoke shopping journey. # Pick-up Where You Left Off Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/pick_up_where_you_left_off The **Pick-Up Where You Left Off** algorithm seamlessly resumes a shopper’s journey by surfacing products or content based on their most recent interactions. Ideal for returning visitors, it reduces friction by guiding users back to items they viewed, added to cart, or engaged with—right at the moment they return. <img alt="" /> <Tip>Recommended Placements <br /><br />**Homepage Banner**: Welcome back carousel showcasing “Continue Shopping” recommendations. <br /><br />**Category Pages**: Highlight items the user was previously browsing within that category. <br /><br />**Product Pages**: Remind shoppers of the exact product or similar alternatives they last viewed. <br /><br />**Cart Page**: Surface items they considered before adding current items to cart.</Tip> ## How It Works 1. **Interaction Tracking**\ Captures a user’s page views, clicks, and session events (e.g., product views, cart additions). 2. **State Persistence**\ Stores the last N interactions (configurable) in a session or user profile. 3. **Contextual Resume**\ When the user returns (same device or logged-in), retrieves those interactions and recommends items “where they left off.” ## Supported Rule Types * **Home Page** * **Category** * **Product** * **Cart** * **Search** ## When to Use * **Re-Engagement Campaigns**\ Bring back lapsed users by reminding them of products they showed interest in. * **Complex Browsing Sessions**\ For sites with deep catalogs, help users pick up long discovery journeys without restart frustration. * **High-Value Product Consideration**\ Aid decision-making on expensive or research-intensive categories by resurfacing last-viewed items. ## Example A shopper browses several **laptop models** but doesn’t purchase: 1. Upon returning, the **Pick-Up Where You Left Off** widget on the **Homepage** displays the last three laptops they viewed. 2. On a **Category** page, it highlights those models alongside newly released variants. 3. If they revisit a **Product** page, it shows the exact model they left, plus closely related accessories. By seamlessly bridging sessions, PWYLO drives deeper engagement and conversion, ensuring no discovery path goes cold. # Popular Products Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/popular_products The **Popular Products** algorithm highlights the top-performing, most-engaged items across your storefront or within specific categories. By tapping into collective user behavior—views, clicks, add-to-carts, and purchases—it surfaces the products that resonate most with your audience, driving social proof and higher conversions. <img alt="" /> <Tip>Recommended Placements <br /><br />**Home Page** : Showcase the site-wide best sellers to new visitors.\ <br />**Category Pages** : Highlight trending items within each category (e.g., “Top-Rated Boots”).\ <br />**Product Pages** : Display “Most Popular” alternatives or complementary items to encourage upsell. </Tip> ## How It Works The Popular Products Recommendation Algorithm identifies and recommends items that have gained widespread popularity among users, taking into account factors such as high engagement, views, and frequent purchases. By leveraging the collective preferences of the user base, this algorithm emphasizes products that resonate well with the audience, aiming to enhance user satisfaction and drive conversions. It is particularly effective for showcasing trending or top-rated items to users, contributing to a dynamic and engaging user experience. ## Supported Rule Types * **Global** * **Home Page** * **Category** * **Product** ## When to Use * **Social Proof Boost**\ Leverage the popularity of high-engagement products to build trust and urgency. * **New Visitor Engagement**\ For anonymous or first-time shoppers, show universally liked items that appeal broadly. * **Seasonal Trends**\ Surface category-specific best sellers (e.g., “Summer Tops”) to align with current demand. ## Example A shopper explores the **Footwear** category: 1. The **Popular Products** widget displays the 10 boots with the highest combined engagement over the past 30 days. 2. On a specific **Boot** product page, “Popular Products” recommends other top-selling boots in that price range. By showcasing what’s resonating most with your audience, you tap into social proof and guide shoppers toward proven favorites—boosting confidence and conversion. # Query-Based Recommendations Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/query_based The **Query-Based Recommendations** algorithm dynamically generates personalized suggestions by interpreting a shopper’s explicit search input or business-defined query. Ideal for headless environments, QBA transforms any keyword or rule into a tailored recommendation set—without relying on a graphical UI. <img alt="" /> ## How It Works 1. **Query Parsing**\ The system ingests the user’s search term or custom query, extracting keywords, filters, and logical operators. 2. **Intent & Preference Analysis**\ Natural language processing and business rules interpret shopper intent (e.g., “leather office chair under \$200”). 3. **Data Retrieval**\ A tailored database lookup applies the parsed conditions—matching product attributes, categories, or metadata. 4. **Relevance Scoring**\ Matched items are ranked by semantic relevance, performance signals (clicks, conversions), and any active merchandising rules. 5. **Results Delivery**\ The algorithm returns a prioritized list of recommendations that best align with the original query’s intent and any configured rules. ## Supported Rule Types * Global * Home Page * Product * Category * Cart * Search ## When to Use * **Headless Integrations:** Embed personalized recommendations directly via API calls in any frontend (mobile app, CMS, PWA). * **Rule-Driven Campaigns:** Combine with business logic (“on sale,” “clearance”) for promotional or seasonal collections. * **Zero-UI Experiences:** Power chatbots or voice assistants where visual widgets aren’t available. ## Example 1. A shopper enters the query **“ergonomic mesh office chair with lumbar support”** into your site’s search bar. 2. QBA parses the keywords and applies a rule to exclude out-of-stock items. 3. It retrieves all matching chairs, ranks them by recent performance and in-stock levels, and applies any boost rules (e.g., promoted brands). 4. The top 5 chairs are returned as recommendations in a headless widget on the category page. # Recently Purchased Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/recently_purchased The **Recently Purchased** algorithm capitalizes on a shopper’s most recent transactions to suggest complementary products. By leveraging the user’s latest purchase history, you can deliver highly relevant cross-sell opportunities and keep customers engaged with items that naturally align with their current interests. <img alt="" /> <Tip>Recommended Placements <br /><br />**Order Confirmation Page**: Upsell complementary items right after a purchase completes.\ <br />**Product Pages**: Suggest related accessories (e.g., laptops & laptop bags) based on the latest order.\ <br />**Cart**: Introduce add-ons or warranty products that pair with the recently purchased item.</Tip> ## How It Works 1. **Purchase History Retrieval**\ Fetches the user’s last N orders (configurable, e.g., 3–5 most recent transactions). 2. **Complementary Item Identification**\ Analyzes attributes (category, tags, brand) of those purchased products to find related or accessory items. 3. **Dynamic Updating**\ Continuously refreshes suggestions in real time as new purchases occur, ensuring recommendations reflect the shopper’s evolving preferences. ## Supported Rule Types * **Global** * **Home Page** * **Category** * **Product** * **Cart** * **Search** ## When to Use * **Post-Purchase Cross-Sell:** Drive incremental revenue by offering accessories and complementary products immediately after a sale. * **Re-Engagement:** Retain and re-engage customers by reminding them of items that go well with their last purchase. * **Subscription & Consumables:** Ideal for consumable goods—remind users to reorder refills or related consumables. ## Example A shopper buys a **Yoga Mat**: 1. On the **Order Confirmation** page, the **Recently Purchased** widget displays complementary items like yoga blocks, straps, and towels. 2. When the user visits the **Cart** for a new purchase, they see prompts to add matching gear based on their last order. By surfacing contextually relevant items tied to recent purchases, you create seamless, value-driven cross-sell journeys that boost average order value and deepen customer loyalty. # Recently Viewed Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/recently_viewed The **Recently Viewed** algorithm resurfaces products a shopper has just browsed—leveraging real-time session data to remind users of their most recent interactions. By prioritizing these items, you can reduce churn, re-engage undecided visitors, and streamline the path back to checkout. <img alt="" /> ## Recommended Placements * **Product Pages:** Remind users of items they explored before diving into product details. * **Cart & Checkout:** Help shoppers recall complementary products they considered earlier. * **Homepage & Category Pages:** Surface personalized “resume shopping” strips to re-engage returning visitors. ## How It Works 1. **Session Tracking**\ Every product view is captured in the user’s session profile (whether logged in or anonymous). 2. **Recency Scoring**\ Items are ranked by time since last view—newer interactions appear higher. 3. **Deduplication & Capping**\ Identical products are collapsed into one entry, and you can limit the number of items shown (e.g., top 5). 4. **Fallback Logic**\ If no recently viewed data exists (e.g., new session), optional fallback algorithms (like Popular Products) can backfill the widget. ## Supported Rule Types * Home Page * Category * Product * Cart * Search ## When to Use * **Combat Decision Fatigue:** Keep recent options top of mind for users who have browsed multiple items. * **Recover Browsing Sessions:** Smoothly guide anonymous or returning shoppers back to the products they cared about. * **Boost Conversions:** Reduce friction by eliminating the need for users to manually search for items they just saw. ## Example 1. A shopper views three different “ergonomic office chairs” in one session. 2. They navigate away to browse desks, then return to a category page. 3. The Recently Viewed widget displays those three chairs in order of most recent view—letting the shopper quickly jump back to their favorite. 4. If no recent views exist, the widget falls back to showing “Popular Products” to maintain engagement. # Recommended For You Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/recommended_for_you The **Recommended For You**(RFY) widget delivers personalized product suggestions by learning from each shopper’s unique browsing and purchase history. As a dynamic “shopping assistant,” RFY adapts in real time—surfacing relevant items on the homepage, search‐no‐results pages, product detail pages, cart pages, and beyond. <img alt="" /> <Tip> **Recommended Placement** <br /><br /> 1. Place on the homepage to greet returning shoppers with tailored picks. <br /><br /> 2. Add to PDPs or zero-results pages to reengage users when no organic results match. </Tip> ## How It Works The following logical order would be used by the algorithm to generate RFY recommendations: 1. **Collaborative Filtering**\ Leverages patterns across your user base—“shoppers who viewed X also viewed Y.” 2. **Content Signals**\ Analyzes product attributes (categories, tags, descriptions) to surface items with similar properties. 3. **Session-Based Signals**\ Prioritizes products the user has interacted with during their current session. 4. **Similar Items Fallback**\ If session data is sparse, defaults to algorithmically detected similar products. ## Supported Rule Types You can scope RFY behavior at multiple levels, each of which can override the global settings: * **Global** (default for all placements) * **Home Page** * **Product Page** * **Category Page** * **Cart Page** * **Search Page** ## Behavior for Not Logged-In Users * **With Session Activity**\ RFY tracks clicks/views in the current session and populates suggestions accordingly. * **New Visitors** * **Fallback Disabled:** Widget remains hidden. * **Fallback Enabled:** Displays products from your chosen fallback algorithm. ## Behavior for Logged-In Users * **Returning Customers**\ RFY sequentially applies collaborative, content, then session logic to craft highly relevant suggestions. * **Freshly Registered (No History)** * **Fallback Disabled:** Widget remains hidden until they interact. * **Fallback Enabled:** Shows fallback recommendations to kickstart engagement. <Note> Fallback settings are a UI-level feature. The underlying AI/ML API returns an empty result if no recommendations can be generated.</Note> ## Example Scenario 1. **Context:** A shopper lands on a designer-furniture PDP for a mid-century sofa. 2. **Action:** RFY analyzes that user’s past views/purchases of coffee tables and accent chairs. 3. **Outcome:** A “Recommended For You” carousel appears beneath the product details—showing complementary pieces (side tables, cushions) that match their style. # Similar Products Source: https://help.experro.com/experro_discovery/recommendations/recommendation_algorithms/similar_products The **Similar Products** algorithm identifies items that share key characteristics (category, brand, price range, attributes) or user-behavior patterns with the currently viewed product. By surfacing visually or semantically related alternatives, it enriches the shopping experience, helps shoppers discover new options, and drives cross-sell opportunities. <img alt="" /> <Tip> **Recommended Placements** <br /><br />**1. Product Page** : Display “Similar Products” alongside the main product details to offer alternatives or complementary items.\ <br />**2. Cart Page** : Recommend products similar to those already in the shopper’s cart.\ <br />**3. Checkout Page** : Suggest related add-ons or accessories before final purchase.</Tip> ## How It Works 1. **Feature Extraction**\ Products are represented by a combination of metadata (category, brand, price, attributes) and latent factors learned from user interactions (views, purchases). 2. **Similarity Scoring**\ A similarity score is computed between the seed product and every other item in the catalog using a hybrid of metadata matching and collaborative signals. ## Supported Rule Types * **Global** * **Home Page** * **Product** * **Cart** ## When to Use * **Alternative Discovery**\ Help customers find comparable or upgraded versions of the item they are considering (e.g., a different color, style, or price tier). * **Complementary Upsell**\ Surface accessories or companion products that share attributes with the main product. * **Inventory Balancing**\ Promote in-stock items similar to out-of-stock products to reduce bounce rates. ## Example A shopper lands on a product page for a “Mid-Century Modern Leather Sofa.” 1. Experro’s **Similar Products** algorithm computes similarity across sofas in the same category, brand, and price range. 2. It ranks alternatives like “Vintage-inspired Leather Loveseat” and “Rustic Leather Sectional” based on combined metadata and past shopper behavior. 3. The page displays these options under “You May Also Like”—encouraging the shopper to explore complementary or upgraded styles. # Algorithm Source: https://help.experro.com/experro_discovery/search/algorithm_field_settings_catalog_settings/algorithm Algorithm is where you configure how Experro ranks the indexed catalog for any given search query or category page. You can have multiple algorithms, each with a name, a scope, and five configuration tabs. <Frame> <img alt="" /> </Frame> ## Algorithm Scope Every algorithm has a scope that defines where it applies on the storefront. Scope is set when creating the algorithm and cannot be changed afterward — instead, create a new algorithm. * **Global Algorithm** — One Global Algorithm exists per store. It is the default ranking configuration that applies when no scope-specific algorithm overrides it. * **Specific Searches** — Algorithm applies only when the user's search query matches the configured search terms. Multiple search terms can be added — each can use a qualifier (Equal to, Contains, Starts with, Ends with) to control how it matches incoming queries. * **Specific Categories** — Algorithm applies only on the configured category pages. Multiple categories can be added. ## The Five Algorithm Tabs Once you open an algorithm for editing, the configuration is divided across five tabs: Relevance, Performance, Personalization, Newness, and Ranking. The tabs are independent of each other — you can configure any combination — and a tab does not need to be touched if you want its defaults. ## Relevance Tab The Relevance tab controls how Experro decides which products are most relevant to a search query or category context. This is where you pick the search engine, configure variant slicing defaults, and set up parent-child grouping. <Frame> <img alt="" /> </Frame> ### Search Engine Search Engine picks the matching strategy for the algorithm. Three options are available as cards on the Relevance tab. * **Deep Text Engine** — Keyword-based matching with linguistic enrichments: typo tolerance, stemming, synonym expansion, NLP/NER tagging. The right default for most catalogs because it is fast, predictable, and well-understood. * **Gen AI Engine** — Semantic matching using the vector embeddings configured in Catalog Settings. The Gen AI engine matches by meaning rather than literal text, so a query for "comfortable office chair" can surface products described as "ergonomic desk seating." Requires Text Vector or Image Vector (or both) to be enabled in Catalog Settings. * **Hybrid Engine** — Combines Deep Text and Gen AI: keyword matches lead the result set, with semantic matches filling in where keyword recall is sparse. Recommended for long-tail and natural-language queries where users phrase intent loosely. Requires vectors enabled in Catalog Settings. <Warning> **Vectors not enabled:** If neither Text Vector nor Image Vector is enabled in Catalog Settings, the Gen AI and Hybrid engine cards are disabled with a notice pointing back to Catalog Settings. Enable the relevant vectors there before picking those engines. </Warning> ### Gen AI Engine Configuration When the Gen AI or Hybrid engine is selected, you also choose which embedding model to use. Three options are available. * **Text Semantic** — Uses product text content (title, description, attributes) to understand semantic meaning. Best for catalogs with rich textual descriptions and minimal visual differentiation between products. * **Image Understanding** — Uses image embeddings to match similar product images directly by visual similarity. Best for visually-driven categories (apparel, home decor, jewelry) where shoppers care about how something looks. * **Multi-modal (Text + Image Understanding)** — Combines text and image embeddings for the broadest coverage. Most reliable choice when in doubt — it handles both text-driven and image-driven queries. **Max Gen AI Search Result Size** — when the Gen AI or Hybrid engine is active, cap the number of semantically-matched products contributed to a result set. Use to keep response times predictable and prevent the semantic layer from overwhelming the keyword layer in Hybrid mode. ### Dominant Category or Type Identification <Warning> **HIDDEN / Legacy:** This setting is labeled HIDDEN in the current UI and is retained only for backward compatibility with existing algorithms. New algorithms should use Precision & Personalization Mode above instead. The Dominant Category setting will be removed in a future release. </Warning> For algorithms still relying on the legacy behavior, this setting controls the sample size — how many top search results Experro examines to identify the dominant category when a query does not directly tag one. The default is 50. ### Out-of-Stock (OOS) Products Controls how out-of-stock products are handled across the storefront. Pick one of two options. * **Include** — Out-of-stock products continue to appear in search results and on category pages, typically with reduced ranking. Use when you want shoppers to discover OOS products (and potentially sign up for back-in-stock notifications) rather than hiding them entirely. * **Exclude** — Out-of-stock products are removed from search results and category pages entirely. Use when displaying unavailable inventory hurts the shopping experience. <Note> **How OOS is detected:** Experro uses the Inventory field from your catalog to determine stock status. Make sure the field is correctly mapped in the Catalog Connection screen so OOS detection works as expected. </Note> ### Parent-Child Grouping Parent-Child Grouping controls whether the parent product or one of its variants appears in the result tiles. Most relevant for catalogs structured around parent products with many variants (paint colors, jewelry rings with multiple metals, apparel with sizes and colors). **Primary Group** — the default behavior. Pick the field that distinguishes parent from variant products in your catalog (usually a Type field) and the value that should lead by default. <Tip> **Use case:** A paint catalog has many parent products (paint families) each with hundreds of color variants. Setting Primary Group to "parent" means a search for "acrylic paint" shows one tile per paint family, not hundreds of individual color tiles. </Tip> **Secondary Group (conditional override)** — overrides the Primary Group when specific NLP-tagged values appear in the search query. Add as many secondary group rules as you need. For example, with Primary Group set to "parent" and a Secondary Group rule that says "if the query tags a color value, show the variant\_color product": * **Search "acrylic paint":** Returns parent products (no color tag in the query). * **Search "yellow acrylic paint":** Returns variant\_color products in yellow. <Warning> **Field requirement:** The field used as the Parent-Child signal must have NLP enabled in Field Settings with Match Type chosen, and the values must be present on every product. Without NLP tagging, the system has no way to detect when a query references a color or size. </Warning> ## Performance Tab The Performance tab boosts products that are performing well — selling more, generating more revenue, or scoring higher on a custom signal. The mechanism is independent of Relevance: a product can rank high on Relevance and be lifted further by Performance, or rank moderately on Relevance and still surface near the top because of strong Performance. <Frame> <img alt="" /> </Frame> ### Conversion Source Conversion Source defines what counts as a "good performance" signal. Three options. | Conversion Source | How It Works | Best For | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Order Count** | Counts the number of orders that included the product, regardless of quantity per order. | B2C with relatively uniform basket sizes. | | **Item Count** | Counts the total number of units sold across all orders. An order of 3 units of the same product counts as 3. | B2B and bulk-purchase catalogs where order count understates true demand. | | **Revenue** | Sums total revenue contributed by the product across all orders. | Catalogs with wide price variation where high-revenue products matter more than high-volume products. | ### Time Decay Window Time Decay defines the window of historical performance data the algorithm considers when computing the performance score. * **Rolling Window** — considers the last N days of data (typically 7, 14, 30, 60, or 90 days). The window rolls forward each day. The right default for most catalogs because it captures current performance. * **Previous Year Same Period** — considers the same N-day window from the previous year. Built for seasonal catalogs where current performance does not reflect what will sell next week. <Tip> **Use case:** A jewelry retailer in late January wants to surface the products that performed well last year in the lead-up to Valentine's Day, not the products selling well in the post-holiday lull. Switching to Previous Year for the four weeks before Valentine's Day pre-positions the right catalog for the upcoming spike. </Tip> ### Custom Performance Signal (External Data) If you have your own performance score — calculated in your ERP, PIM, or analytics warehouse — Experro can use it directly instead of computing one from Experro's own event data. This is built for customers who sell across multiple channels (eCommerce, retail, marketplaces) and have a unified performance score that already accounts for all channels. Setting it up: <Steps> <Step title="Include the score in your feed"> Ensure your product feed includes a numeric field with the performance score for each product. </Step> <Step title="Confirm the field is indexed"> In Field Settings, confirm the score field is indexed (Display Field on, Match Type set so it is searchable internally). </Step> <Step title="Switch the source to Custom"> In the Performance tab, switch the source to Custom and pick the field. </Step> <Step title="Set the weightage"> Set the weightage as you would for any other performance signal. </Step> </Steps> <Tip> **Real-world example:** A multi-channel retailer calculates a "Total Sold" score in their PIM that combines eCommerce sales, retail sales, and marketplace sales into a single weighted number. They feed this score into Experro as a custom field, then use Custom Performance Signal to rank products by true total sales velocity — not just the slice of sales that happened on the storefront. </Tip> ## Personalization Tab The Personalization tab tailors search and category results to the individual shopper based on their browsing and purchase history. <Frame> <img alt="" /> </Frame> ### Personalization on Untagged Searches Personalization now applies on search queries that do not match any category. Previously, a query such as "jewelry gift for my friend" — which carries no category tag — bypassed personalization entirely because the system had no category context to scope affinities to. The system now computes a dominant category from the search results themselves and applies personalization scoped to that dominant category. The result is that more queries benefit from personalization, including the long-tail intent queries that customers actually type. ### Global Affinities Affinities are the user signals Experro uses to personalize results — a user who has viewed many Levi's products develops a Levi's affinity. Previously, affinities were always scoped to a category. A user's Levi's affinity on jeans did not influence what they saw on shirts. Global Affinities lifts this restriction for specific fields. A field marked as a Global Affinity is treated as cross-category — a Honda affinity built up from Honda car parts also applies when the user browses Honda motorcycle accessories. When to use Global Affinities: * **Brand (most common)** — In hardware, automotive, and tools, where a single brand spans many product categories, brand affinity is naturally global. * **Color (sometimes)** — In fashion or home decor, color affinity may be global if customers tend to coordinate across product types. * **Material** — In furniture or jewelry, material preferences (oak, gold, sterling silver) often carry across categories. Some fields make sense only at the category level. Size is the canonical example — a user's "Medium" affinity on shirts has no bearing on shoe sizes. Leave these as category-scoped (the default). ### Rolling Window for Personalization Personalization supports a rolling window setting that limits how far back the system looks when computing affinities. Older interactions decay out of the user's profile, keeping personalization current to recent intent. ## Newness Tab The Newness tab boosts recently-added products so they are not buried by performance ranking before they have had a chance to accumulate sales. Newness is its own tab — independent of Performance — because the configuration is meaningfully different and customers want to tune them separately. <Frame> <img alt="" /> </Frame> ### Configuration * **Newness Field** — A date field, typically Created Date or Published Date. * **Newness Period** — How recent a product must be to qualify for the boost. Common values are 14 days, 30 days, or 60 days. * **Weightage** — How much the newness boost contributes to the final ranking score, relative to relevance, performance, and personalization. <Tip> **Why this matters:** Without newness, a freshly-launched product never appears near the top because it has zero sales history. Performance ranking would bury it permanently. Newness counter-balances this by giving recent products a temporary boost while they accumulate organic performance data. </Tip> ## Ranking Tab The Ranking tab combines Relevance, Performance, Personalization, and Newness into a final ordered list. This is where you choose the overall ranking strategy. <Frame> <img alt="" /> </Frame> ### Ranking Modes * **Relevance First** — pure relevance ordering. Performance, personalization, and newness signals are ignored. Use when you want the cleanest possible match-to-query ordering and have no commercial considerations to apply. * **Fusion (recommended default)** — blends relevance with performance, personalization, and newness into a unified score. The right default for most storefronts — products that are highly relevant and selling well rank above products that are merely relevant. * **Bucketing** — divides the result set into position buckets (positions 1–10, 11–25, 26–50, and so on) and applies different ranking logic within each bucket. Useful when you want strong relevance at the top of the page and need variety further down. ### Merchandising Priority Merchandising rules always take priority over the algorithmic ranking. A pinned product appears at its pinned position regardless of relevance, performance, or personalization scores. A boost rule lifts the boosted product even if relevance would have buried it. This is by design — merchandising rules represent explicit business intent, and Experro respects that intent over algorithmic decisions. The Ranking modes above describe how the algorithm orders the products not directly affected by merchandising rules. <Tip> **Recommended starting point:** Use Fusion as your default Ranking Mode and let merchandising rules handle the cases where you need explicit business control. This combination — algorithmic baseline plus merchandiser overrides — is how most high-performing Experro deployments are configured. </Tip> ## Saving, Activating, and Managing Algorithms ### Save and Activate When you create or edit an algorithm, you have these actions: * **Save as Draft** — Persists your changes without applying them. The storefront continues to use the previously-active algorithm. Useful for staging changes before they go live. * **Save and Activate** — Persists and applies the algorithm to the storefront. Takes effect within a few seconds. * **Preview** — Loads a preview pane showing how the algorithm would rank a sample query against the live catalog, so you can sanity-check the configuration before activating. ### Variants A variant is an alternate configuration of the same algorithm. Each one holds its own relevance, performance, personalization, and ranking settings, so you can test two ranking strategies against each other instead of choosing between them upfront. <Frame> <img alt="" /> </Frame> Click the arrow beside **Save**, then select **Save as a New Variant**. The new variant is added to the variant selector beside the **Save** button. <Info> **Save as a New Variant** only appears when your plan includes A/B testing. </Info> Open the variant selector to switch between variants. Each entry shows who last saved it and when, and the variant currently serving your storefront carries an **Active** badge. Variants already in use by an experiment are marked with an experiment icon. Once an algorithm has more than one variant, it becomes selectable on the **Experience** step of the experiment flow, where you map each variant to an experiment group. See [Map Experiences to Variants](/experiments/a_b_testing/experience). <Warning> Only one variant can be active per scope. Activating a variant deactivates the one currently serving that scope, and the algorithm conflict rules above still apply. </Warning> ### Algorithm Conflicts You can have only one active algorithm per scope. Two active algorithms cannot both target the same search term or the same category. When you try to activate an algorithm whose scope is already covered by another active algorithm, Experro flags the conflict at save time and asks you to deactivate the existing algorithm first. ### Re-index Considerations <Warning> **When a re-index is required:** Algorithm changes generally take effect without a re-index. Field Settings changes — type, searchable status, prefix search, NLP, multi-value — require a re-index. Catalog Settings vector toggles also require a re-index. Plan re-indexes for low-traffic windows. </Warning> # Catalog Settings Source: https://help.experro.com/experro_discovery/search/algorithm_field_settings_catalog_settings/catalog_settings Catalog Settings is the catalog-wide configuration layer. While Field Settings tunes individual fields, Catalog Settings tunes behaviors that apply across the entire catalog — Gen AI vector indexing, the field used as the precision and personalization signal, out-of-stock handling, color grouping, and variant slicing attributes. The screen has three tabs at the top: General, Color Family, and AI Knowledge. <Frame> <img alt="" /> </Frame> ## General Tab ### Allow Vector for Gen AI Vector indexing generates a numeric embedding for each product so the Gen AI search engine can reason about semantic similarity rather than literal keyword matches. Two independent toggles control which kinds of embeddings are generated. * **Text Vector** — Enables semantic understanding of product text content: title, description, attributes. When enabled, a search for "comfortable office chair" can surface products described as "ergonomic desk seating" even when no keywords overlap. * **Image Vector** — Enables visual-similarity matching using product images. Required for image-based engines and for image-similarity recommendations such as Complete the Look. <Note> **Prerequisite for Gen AI Engine:** The Gen AI engine and Hybrid engine choices in the Algorithm screen require at least one vector to be enabled here. If neither Text Vector nor Image Vector is on, those engine options are disabled in the Algorithm screen with a notice pointing back to Catalog Settings. </Note> <Warning> **Re-index required:** Toggling either vector on or off triggers a full re-index. Plan for a one-time index rebuild after this change. </Warning> ### Precision & Personalization Mode Precision & Personalization Mode picks the single field that Experro uses as the primary signal for product type — its dress-ness, shoe-ness, ring-ness. This signal drives several downstream behaviors: * Dominant category detection when a search returns no direct category match. * Personalization scoping — affinities are scoped to the product type represented by this field by default. * Gen AI search fallback when literal matches are sparse. Choose the Search Field for Categorization from the dropdown. Common choices: * **Categories** — Works well if your category tree is well-structured and every product is tagged to a single primary category. * **Product Type (Shopify)** — Most Shopify customers find Product Type more reliable than Categories — Categories tend to include marketing groupings such as Sale or New Arrivals that pollute precision. * **Category Level 1** — If you have a multi-level category structure where Level 1 captures the primary type (Dresses, Shoes) and Level 2/3 captures style, Category Level 1 is often the cleanest precision signal. * **Custom field (e.g. Style Category)** — Some customers maintain a separate, curated product-type field for exactly this purpose. If you have one, use it. ### Color Field Tells Experro which fields in your catalog should be treated as colors for the purpose of color-family grouping and color-based merchandising. Most customers select a single Color field, but if you have multiple color-related fields — for example Dress Color on apparel and Frame Color on jewelry — include all of them. The selected fields are also the basis for the Color Family tab. ### Variant Slicing Attributes Variant Slicing Attributes is the catalog-level list of variant attributes available for slicing on the storefront. Variant attributes you select here become available in the Algorithm screen's Variant Slicing setup and in Merchandising Variant Slicing Rules. The picker shows every field marked as Variant Option in Field Settings. Pick the attributes you want available for slicing — typically color, size, material, metal, finish. <Note> **Two layers, one feature:** Variant Slicing Attributes here defines *what* is available. The Algorithm screen's Relevance tab defines *how* the default variant is chosen. The Merchandising Variant Slicing Rule overrides the default for specific search queries or category pages. </Note> Variant Slicing on the Relevance tab decides which variant of a multi-variant product is shown as the lead tile when the product appears in search results. The attributes available here are the ones picked in Catalog Settings under Variant Slicing Attributes. For each variant attribute (color, size, etc.) you can set a default priority order. The first value in the priority list that matches a product's available variants becomes the lead tile by default. ### Hero Variant Hero Variant is the catalog-level fallback for which variant leads the tile. It is a Boolean field at the variant level — one variant per product should have `hero_variant` set to true. When no Variant Slicing Rule and no NLP-detected value dictates a variant, the Hero Variant is shown. ### Variant Resolution Priority When multiple signals are in play, Experro applies them in this order (highest priority first) to decide which variant leads the tile: <Steps> <Step title="NLP-tagged values in the search query"> For example, "red dress" forces the red variant. </Step> <Step title="Active Variant Slicing Rule"> A rule scoped to the current search or category. </Step> <Step title="Personalization signal"> The user's built-up affinity for a specific value. </Step> <Step title="Hero Variant"> The variant marked as hero on the product. </Step> <Step title="System default"> The best-performing variant by Experro's internal model. </Step> </Steps> ## Color Family Tab The Color Family tab manages how visually-similar colors are grouped together so that a search for one color also surfaces close matches. For example, a search for "red" can surface burgundy, scarlet, and maroon when these are grouped into a single family. Experro ships with a predefined color library covering the most common groupings (reds, greens, blues, neutrals, and so on). Future releases will support customer-defined libraries built from your own catalog data. <Frame> <img alt="" /> </Frame> # Field Settings Source: https://help.experro.com/experro_discovery/search/algorithm_field_settings_catalog_settings/field_settings Field Settings is where you configure every field in your indexed catalog one field at a time. The screen has two panels — a list of All Fields on the left (with an Add Field button at the bottom for custom fields) and a configuration form on the right that opens when you select a field. <Frame> <img alt="" /> </Frame> ## Accessing Field Settings <Steps> <Step title="Select the apps icon at the top left of the application." /> <Step title="Select Discovery from the dropdown menu." /> <Step title="Navigate to Catalog from the navigation panel." /> <Step title="Open the Field Settings tab." /> </Steps> ## Field List and Field Header The All Fields panel lists every field in your catalog along with its type. Selecting a field opens the configuration form on the right. The list supports a filter dropdown — narrow the list by attribute (Display Field, Not Searchable, Not Filterable, Filterable, NLP, Sensitive Data, Variant Option, Multi-Valued) or by Most Modified Date when you have a large catalog to navigate. When you open a field, the header at the top of the form shows: * **Experro Field Name** — The display name of the field inside Experro. * **Experro Internal Name** — The internal identifier used by the API and merchandising rules. * **Experro Field Type** — String, Number, Date, Boolean, SKU, Long Description, or Object. * **Catalog Field** — The corresponding field name in your source catalog (Shopify, BigCommerce, JSONL feed, custom API). * **Modified By and Modified At** — Audit trail showing who last changed this field and when. * **Coverage** — The percentage of products in your catalog that have a value for this field, with a View Stats link for the full distribution (unique value count, top values, sparse-coverage warnings). * **Header chips** — Quick-reference chips along the top show which options are currently active for the field — for example, Display Field, Sensitive Data, Variant Option, Multi-Valued. ## Adding Custom Fields The Add Field button at the bottom of the All Fields list lets you create custom fields without engineering involvement. Custom fields are configured with the same options as connector-mapped fields and participate in search, faceting, merchandising, and NLP the same way. Custom field rows are tagged as Custom Field in the type column. ## Field Configuration Options The configuration form on the right has the same set of options for every field. Not every option is meaningful for every field type — for example, Long Description fields cannot be filterable because filtering long-form text is not useful. Options that don't apply to the selected field are hidden. ### Display Field Marks the field for inclusion in the search index. Only fields with Display Field enabled are accessible from the Discovery API for search, auto-complete, category, collection, and recommendation surfaces. <Tip> **Why this matters:** Indexing only the fields you actually use keeps the index small, improves search performance, and prevents internal-only data from leaking into API responses. </Tip> ### Searchable The Searchable section controls how the field participates in user-typed search queries. It has three controls. **Match Type** — pick one: * **Exact Search** — Enable exact match searches on this field. Useful for identifiers and short attributes where the user is expected to type the value verbatim. * **Fuzzy Search** — Enable partial and approximate matches to improve recall for broader queries. Surfaces near-matches when the user makes typos or types only part of the value. * **Not Searchable** — Exclude this field from search indexing entirely. The field will not influence search ranking even if other options are enabled. **Define Field Weightage in Search** — when the field is Searchable, set how much weight matches on this field carry relative to other searchable fields. Higher weightage pushes products that match on this field toward the top of the result set. Expressed as a percentage. **Allow Prefix Search** — enable on string fields when users are likely to type only the start of a value. With prefix search enabled on a category field, a user typing "categ" matches every category beginning with "categ". <Warning> **Heads up:** Prefix search increases the size of the index and slightly slows indexing. Enable it only on fields where prefix matching genuinely helps. </Warning> ### Filterable & Merchandisable A single combined toggle that does two things — it makes the field available as a facet on storefront search and category pages, and it makes the field available as a condition in merchandising rules. The two capabilities are linked because they share the same indexed-attribute infrastructure under the hood. Long Description and Object fields cannot be marked Filterable & Merchandisable. ### Sensitive Data Marks the field as internal-only. Sensitive fields are indexed and available for internal use — search relevance, merchandising rules, performance ranking, preview — but are never returned through the Discovery API and cannot appear as a facet to end shoppers. <Tip> **Common use case:** Cost price. You need it for performance ranking and internal preview, but it should never reach the customer-facing storefront. Mark the cost price field as both Filterable & Merchandisable and Sensitive Data — it stays usable internally while being suppressed from public API responses. </Tip> ### Variant Option Marks the field as a variant-level attribute used to define product variants (color, size, metal, material, finish, and so on). Connectors such as Shopify and BigCommerce auto-detect most variant fields; mark fields manually here when importing from a custom CSV or any source where variant fields are not auto-detected. Variant Option fields appear in the Variant Slicing Attributes picker in Catalog Settings. ### Natural Language Processing (NLP) Enables natural language processing and named entity recognition (NER) on this field. When enabled, the NLP layer detects values from this field inside user search queries and uses them to refine the result set. The NLP section has four controls. **Match Type** — pick one: * **Exact** — The search query must contain an exact match of the field's value to count as an NLP/NER match. Use when you want strict, unambiguous detection. * **Fuzzy** — The search query can partially match the field's value with some variation. Use when you want to tolerate minor user typos or word variants in detection. **Resulting Effect** — pick one: * **Filter Results** — When an NLP/NER match is found in the query, results are restricted to products matching the detected value. Use for fields where the user's intent is exact — for example, color on a fashion query. A search for "red dress" filters the result set down to red dresses only. * **Boost Results** — When a match is found, matching products are lifted but non-matching products are still returned. Use for fields where the user's intent is a preference, not a hard requirement. A search for "Nike running shoes" surfaces Nike at the top while still showing Adidas and others below. **Define Boost Factor for this field** — when Resulting Effect is Boost, set how aggressively matching products are lifted. Expressed as a percentage. **Use Synonyms and Phrases for NLP/NER matching** — a sub-toggle that, when enabled, expands NLP matching to also detect synonyms and synonym phrases you have defined. A synonym group of "sneakers, trainers, running shoes" ensures all three queries match the same product set. **Exclude from NLP/NER matching** — a sub-toggle that lets you suppress specific values in the field from being used for NLP tagging even though the field itself is configured for NLP. Pick the values to exclude from the Select Field Value multi-select picker — comma-separated values can be entered, or values can be picked from the existing list. <Tip> **When to use Exclude:** Marketing categories such as "Sale," "Featured," "Under \$99," or "New Arrivals" are useful as facets and as merchandising signals but should not be treated as product-defining tags when a customer searches. Adding them to the Exclude list prevents the NLP layer from filtering or boosting on them. </Tip> ### Multi-Value Some fields contain multiple values in a single record — for example, a category field where one product belongs to several categories, separated by commas. Enable Multi-Value and pick the delimiter (comma, semicolon, pipe, underscore) so Experro can parse the field into a proper array at index time. <Note> Some field types are inherently multi-value and do not require this setting — variant option fields, for example, are always multi-value by definition. </Note> ## Editing and Saving a Field Edit Field opens the configuration form for editing. Save commits the change and queues a partial re-index for the affected field. Cancel discards changes and returns to the read-only view. The header retains the audit-trail Modified By and Modified At values so you can track changes over time. <Warning> **Re-index required:** Changes to most Field Settings options — type, searchable status, prefix search, NLP, multi-value — require a re-index before they take effect on the storefront. Plan re-indexes for low-traffic windows. </Warning> # Overview Source: https://help.experro.com/experro_discovery/search/algorithm_field_settings_catalog_settings/overview Field Settings, Catalog Settings, and Algorithm are the three configuration surfaces that control how Experro Discovery indexes your catalog and decides which products to surface on every search and category page. ## The Three Configuration Surfaces <CardGroup> <Card title="Algorithm" href="/experro_discovery/search/algorithm_field_settings_catalog_settings/quick_decision_guide"> The ranking layer. One or more named algorithms scoped to specific searches or categories, each with five configuration tabs covering relevance (including the search engine choice), performance, personalization, newness, and ranking behavior. </Card> <Card title="Field Settings" href="/experro_discovery/search/algorithm_field_settings_catalog_settings/field_settings"> The per-field configuration layer. For each indexed field, you define its type, how it participates in search and faceting, how Experro's natural language processing layer treats it, and whether it carries internal-only data. </Card> <Card title="Catalog Settings" href="/experro_discovery/search/algorithm_field_settings_catalog_settings/catalog_settings"> The catalog-wide configuration layer. Settings that apply across every product, including Gen AI vector indexing, the field used for precision and personalization, out-of-stock handling, color grouping, and variant slicing attributes. </Card> </CardGroup> ## How They Relate The three surfaces build on one another, from shaping the raw data to ranking the final results: * **Field Settings shapes the data** — it defines what each field is and how it can be used. * **Catalog Settings tunes catalog-wide behavior** on top of that data. * **Algorithm decides how the resulting indexed catalog is ranked** for any given query. <Note> Changes to Field Settings or to certain Catalog Settings options require a catalog re-index before they take effect. Algorithm changes apply immediately on save and activate. </Note> # Quick Decision Guide Source: https://help.experro.com/experro_discovery/search/algorithm_field_settings_catalog_settings/quick_decision_guide Common configuration decisions and where to make them. | I want to... | Where to configure | Setting | | ------------------------------------------------------ | ------------------ | -------------------------------------------- | | Hide a field from the storefront but use it internally | Field Settings | Sensitive Data (toggle on) | | Make a field available as a facet | Field Settings | Filterable & Merchandisable | | Treat a field as exact match in search | Field Settings | Searchable → Match Type: Exact | | Tolerate typos in search | Field Settings | Searchable → Match Type: Fuzzy | | Make typing prefix match (e.g. "categ" → category) | Field Settings | Allow Prefix Search | | Use a field for product-type tagging in queries | Field Settings | NLP → Match Type, Resulting Effect | | Boost matching products rather than filter | Field Settings | NLP → Resulting Effect: Boost Results | | Suppress specific values from NLP tagging | Field Settings | NLP → Exclude from NLP/NER matching | | Treat a comma-separated field as an array | Field Settings | Multi-Value (with delimiter) | | Enable Gen AI semantic search | Catalog Settings | Allow Vector for Gen AI → Text Vector | | Enable visual-similarity matching | Catalog Settings | Allow Vector for Gen AI → Image Vector | | Set the product-type signal across the catalog | Catalog Settings | Precision & Personalization Mode | | Hide out-of-stock products from storefront | Catalog Settings | Out-of-Stock Products → Exclude | | Group similar colors (red → burgundy, scarlet) | Catalog Settings | Color Family tab | | Make a variant attribute available for slicing | Catalog Settings | Variant Slicing Attributes | | Switch to semantic search engine | Algorithm | Relevance → Search Engine: Gen AI or Hybrid | | Pick the Gen AI embedding model | Algorithm | Relevance → Gen AI Engine Configuration | | Default which variant leads the tile | Algorithm | Relevance → Variant Slicing + Hero Variant | | Boost products by total sold across channels | Algorithm | Performance → Custom Performance Signal | | Use last-year same-week data for seasonal ranking | Algorithm | Performance → Time Decay: Previous Year | | Personalize across categories (e.g. brand) | Algorithm | Personalization → Global Affinities | | Boost newly-added products | Algorithm | Newness → Newness Field + Period + Weightage | | Use pure relevance with no commercial signals | Algorithm | Ranking → Mode: Relevance First | # Autocomplete Source: https://help.experro.com/experro_discovery/search/autocomplete ### Overview Experro’s Autocomplete feature is designed to streamline the search process and enhance user engagement. By providing real-time suggestions as users type in the search bar, Autocomplete not only accelerates the search experience but also improves the accuracy of search results. This functionality enables customers to quickly find what they’re looking for—reducing frustration and boosting conversion rates. ### Configuration Guide To configure the Autocomplete feature in Experro, follow these steps: <Steps> <Step title="Navigate to Autocomplete Configuration"> * Go to **Discovery → Search & Autocomplete** <img alt="menu icon" /> * The Autocomplete configuration screen is divided into four main tabs: * **Autocomplete Terms** * **Configurations** * **Exclusion Rules** * **Boost Terms**\\ <img alt="" /> </Step> <Step title="Autocomplete Terms Tab"> * **Add Search Term:** Click on the **Add Search Term** button to add a new term. * *Example:* Adding "dining table" will enable it for autocompletion. * **Categorization:** Once added, autocomplete terms are automatically categorized into: * **All:** Displays all available autocomplete terms. * **Manually Added:** Terms you have explicitly added. * **Generated from Search:** Terms derived from user search behavior. * **Generated from Catalog:** Terms extracted from the product catalog. </Step> <Step title="Configurations Tab"> * **Popular Keywords:** Specify the default popular search terms that appear in the search bar even before any characters are typed. * **AI Engine Settings:** Configure parameters that enhance the quality of suggestions through AI, tailoring the behavior to suit your store’s needs. <img alt="" /> </Step> <Step title="Exclusion Rules Tab"> * **Add Exclusion Rule:** Click on **Add Rule** to input a search term or pattern that should be excluded from autocomplete suggestions. * **Category Exclusions:** In the category suggestions section, click **Add Category** to specify any categories that should be removed from autocomplete results. <Note>When AI is enabled, it respects these exclusions as defined by your rules.</Note> <img alt="" /> </Step> <Step title="Boost Terms Tab"> * **Add Boost Term:** Click on **Add Term** to designate a term that should receive priority in autocomplete suggestions. * *Example:* Adding "apple watch" as a boost term ensures that when users type “app” or “wat,” "apple watch" appears prominently.\\ <img alt="" /> </Step> </Steps> By following these steps, you can fully customize Experro’s Autocomplete functionality to deliver a tailored, efficient, and engaging search experience for your users. Adjust these configurations as needed to align with your merchandising strategy and customer behavior insights. # Dictionaries Source: https://help.experro.com/experro_discovery/search/dictionaries In Experro, the Dictionaries section is dedicated to refining the search process by managing specific text-processing features. These features—Stopwords, Spellcheck, and Stemming—work together to enhance search efficiency and accuracy by ensuring that user queries are interpreted correctly. <Tabs> <Tab title="Stopwords"> ## Stopwords Stopwords are common words that are filtered out during search queries because they typically do not contribute to meaningful search results. By omitting words like “the,” “is,” or “an” from search indexing, Experro improves search efficiency and relevance by allowing the engine to focus on more significant keywords. *Example:*\ In an online apparel store, excluding stopwords ensures that a query like “the red dress” is interpreted simply as “red dress,” returning a more accurate list of relevant products. ### Use-Cases * **Improving Search Efficiency:**\ Filtering out stopwords enables the search engine to focus on more meaningful terms, leading to faster and more relevant search results. * **Reducing Noise:**\ Eliminating common, irrelevant words reduces search result noise, resulting in more precise product matches. ### Configuration Guide #### Viewing and Searching Stopwords 1. **Navigate to Stopwords:** * Use the navigation panel on the left side of the screen. * Go to **Discovery → Search & Autocomplete**, then select the **Dictionaries** tab under **Enrichment** . * The **Stopwords** tab is selected by default on the screen.\\ <img alt="" /> 2. **Search for a Stopword:** * Use the search bar at the top of the Stopwords screen to locate a specific stopword by entering the term and pressing Enter. #### Adding Stopwords 1. **Click on "Add Stopword":** * On the Stopwords screen, click the **Add Stopword** button to open the pop-up form.\\ <img alt="" /> 2. **Fill in the Fields:** | **Field Name** | **Description** | | -------------- | ---------------------------------------------------- | | **Term** | The word you want to filter out from search queries. | 3. **Save the Stopword:** * Click **Save** to add the Stopword to the list. #### Editing Stopwords 1. **Find the Stopword to Edit:** * Use the search bar to locate the stopword you wish to modify. 2. **Edit the Stopword:** * Click on the stopword to open the edit form or click <img alt="menu icon" /> under **Action** and select **Edit**. * Update the term as needed. 3. **Save the Changes:** * Click **Save** to apply your updates. #### Deleting Stopwords 1. **Locate the Stopword to Delete:** * Use the search bar to find the stopword you want to remove. 2. **Delete the Stopword:** * Navigate to the stopword, click <img alt="menu icon" /> under **Action**and select **Delete** from the dropdown menu. * Confirm the deletion in the popup prompt. By managing stopwords effectively in Experro, you can significantly enhance the precision and efficiency of search results, ensuring that users find exactly what they’re looking for. </Tab> <Tab title="Spellcheck"> ## Spellcheck The Spellcheck feature in Experro is designed to correct common misspellings in search queries, ensuring that users find the products they are looking for. By leveraging AI-based backend processes, Spellcheck maps frequently misspelt terms to their correct forms. This means that even when users make errors while typing, the search engine can automatically adjust the query and return accurate, relevant results. All you need to do is specify the commonly misspelt terms on the portal, and the system will recognize these terms as valid search queries rather than errors. *For Example:* If a user types “cher” while looking for a chair, the system automatically corrects the query to “chair,” ensuring that the correct product listings are returned. Administrators simply need to add “cher” in the Spellcheck configuration, and the term will be recognized as the intended search term. ### Use-Cases * **Correcting Misspellings:**\ For instance, if a user searches for "cher" instead of "chair," the Spellcheck feature corrects the query to display results for "chair." * **Improving Search Accuracy:**\ By correcting misspelt terms, the search engine provides more accurate and relevant results, thereby enhancing the overall search experience. ### Configuration Guide #### Viewing and Searching Misspelled Terms 1. **Navigate to Spellcheck:** * Use the navigation panel on the left side of the screen. * Go to **Discovery → Search & Autocomplete**, then select the **Dictionaries** tab under **Enrichment** .. * Select **Spell-check**. The screen will display a list of existing misspelled terms.\\ <img alt="" /> 2. **Search for a Misspelled Term:** * Use the search bar at the top of the Spellcheck screen to locate a specific term. * Enter the term and press Enter. #### Adding Misspelled Terms 1. **Click on "Add Term":** * On the Spellcheck screen, click the **Add Spell-Check** button to open the pop-up form.\\ <img alt="" /> 2. **Fill in the Fields:** <br /> | **Field Name** | **Description** | | -------------- | ---------------------------------------------------------------------------- | | **Term** | Enter the misspelled term that you want the system to recognize and correct. | 3. **Save the Term:** * Click **Save** to add the misspelled term to the list. #### Editing Misspelled Terms 1. **Locate the Term to Edit:** * Use the search bar to find the misspelled term you wish to modify. 2. **Edit the Term:** * Click on the term to open the edit form or click <img alt="menu icon" /> under **Action** and select **Edit** from the dropdown menu. * Update the necessary fields such as the **Term**. 3. **Save Changes:** * Click **Save** to apply the updates. #### Deleting Misspelled Terms 1. **Find the Term to Delete:** * Use the search bar to locate the misspelled term you want to remove. 2. **Delete the Term:** * Navigate to the term, click <img alt="menu icon" /> under **Action** and select **Delete** from the dropdown menu. * Confirm the deletion in the popup prompt to remove the term from the list. <Note> The underlying AI engine may dynamically learn from user behavior to enhance these corrections, but the administrative entries ensure that common misspellings are preemptively addressed.</Note> </Tab> <Tab title="Stemming"> ## Stemming Stemming is the process of reducing words to their root or base form, ensuring that different variations of the same word (e.g., "run," "running," "ran") are treated as equivalent. This unified treatment helps to deliver consistent and comprehensive search results, regardless of the word form used by the customer. By applying stemming, Experro enhances search accuracy and ensures that users find relevant results even when they use different tenses or word forms. ### Use-Cases * **Handling Different Tenses:**\ If users search for "running" or "ran," stemming ensures that the base term "run" is also considered, resulting in unified search results. * **Improving Search Relevance:**\ Recognizing and grouping different forms of a word allows the search engine to return a broader set of relevant results, thereby improving overall search accuracy. *Example:*\ In a sports apparel store, configuring stemming for the term "run" ensures that a search for "running shoes" or "run shoes" displays the same relevant products. ### Configuration Guide **Viewing and Searching Stems** 1. **Navigate to Stemming:** * Use the navigation panel on the left side of the screen. * Go to **Discovery → Search & Autocomplete**, then select the **Dictionaries** tab under **Enrichment** * Select **Stemming**. The screen will display a list of existing stemming terms.\\ <img alt="" /> 2. **Search for a Stem:** * Use the search bar at the top of the Stemming screen to locate a specific stem. * Enter the term you are looking for and press Enter. #### Adding Stems 1. **Click on "Add Term":** * On the Stemming screen, click the **Add Term** button to open the pop-up form.\\ <img alt="" /> 2. **Fill in the Fields:** | **Field Name** | **Description** | | -------------- | -------------------------------------------- | | **Term** | Enter the term you want to add for stemming. | 3. **Save the Term:** * Click **Save** to add the term to the list. #### Editing Stems 1. **Locate the Term to Edit:** * Use the search bar to find the term you want to edit. 2. **Edit the Term:** * Click on the term to open the edit form or click <img alt="menu icon" /> under **Action** and select **Edit** from the dropdown menu. * Make the necessary changes to the term. 3. **Save the Changes:** * Click **Save** to update the term. #### Deleting Stems 1. **Find the Term to Delete:** * Use the search bar to locate the term you want to remove. 2. **Delete the Term:** * Navigate to the term, click <img alt="menu icon" /> under **Action** and select **Delete** from the dropdown menu. * Confirm the deletion in the popup prompt. <Note>Typically, the system uses the base term to automatically generate or recognize its variations. While only one term can be added per entry, Experro’s stemming algorithm processes related forms of the word to ensure that searches return unified and relevant results.</Note> By carefully configuring and managing stemming alongside other dictionary features—such as Stopwords and Spellcheck—you can significantly improve the accuracy and efficiency of your search functionality in Experro, ultimately enhancing the overall user experience. </Tab> </Tabs> # Overview Source: https://help.experro.com/experro_discovery/search/overview Experro Search is a comprehensive solution designed to enhance user experience by providing accurate and efficient search capabilities. It offers a suite of features that can be tailored to meet specific business needs. The key features include: * **[Autocomplete](/experro_discovery/search/autocomplete) :** Provides real-time suggestions as users type their queries, improving search speed and accuracy. * **[Search Redirects](/experro_discovery/search/search_redirects) :** Allows specific search terms to direct users to designated pages, ensuring they find relevant content quickly. * **[Synonyms](/experro_discovery/search/synonyms) :** Recognizes and processes different terms with similar meanings, broadening search results to include all relevant items. * **[Phrases](/experro_discovery/search/phrases) :** Supports exact match searches for phrases, enabling users to find specific content efficiently. * **[Dictionaries](/experro_discovery/search/dictionaries) :** Utilizes custom dictionaries to understand industry-specific terminology or unique language used within your content. * **[Settings](/experro_discovery/search/settings) :** Offers configurable options to customize search behavior and appearance according to your requirements. For detailed information on each feature, please refer to the corresponding sections in this user guide. # Phrases Source: https://help.experro.com/experro_discovery/search/phrases ### Overview In Experro, a phrase is a specific combination of words that is processed as a single search entity. By defining phrases, the search engine treats inputs like "tooth brush" as one cohesive term—returning unified results (e.g., "toothbrush") rather than splitting the phrase into individual words. This improves search accuracy and ensures that users receive results that truly match their intent. ### Use-Cases * **Improving Search Relevance:**\ Defining phrases helps ensure that queries such as "tooth brush" yield results for "toothbrush," avoiding fragmentation of search results. * **Handling Common Expressions:**\ Recognize industry-specific or common compound expressions—such as "running shoes" or "smart watch"—so that they are consistently processed as a single search term. * **Accurate Product Name Matching:**\ For products with compound names (e.g., "coffee maker") or multi-word brand names (e.g., "Apple Watch"), phrases ensure that searches return the correct, intended results. ### Configuration Guide #### Viewing and Searching Phrases 1. **Navigate to Phrases section:** * Use the navigation panel on the left side of the screen. * Go to **Discovery → Search & Autocomplete**, and then select the **Phrases** tab to view the list of existing phrases. 2. **Search for a Phrase:** * Enter the desired phrase in the search bar at the top of the Phrases screen and press Enter to locate it. <img alt="" /> #### Adding Phrases 1. **Click on "Add Phrase":** * On the Phrases screen, click the **Add Phrase** button to open the pop-up form. 2. **Fill in the Fields:** | Field | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Phrase** | Enter the phrase that you want to be treated as a single search entity (e.g., “tooth brush” to ensure it’s searched as “toothbrush”). | | **Languages** | Select the language applicable to the phrase. Use the **Apply to all languages** checkbox if you want it to apply universally. | 3. **Save the Phrase:** * Click **Save** to add the phrase to your list. <img alt="" /> #### Editing Phrases 1. **Locate the Phrase to Edit:** * Use the search bar to find the phrase you wish to modify. 2. **Edit the Phrase:** * Click on the phrase to open the edit form or use the <img alt="menu icon" /> under the **Actions** field and select **Edit**. * Update the necessary fields such as **Phrase** or **Lanugage**. 3. **Save Changes:** * Click **Save** to apply the updates. #### Deleting Phrases 1. **Locate the Phrase to Delete:** * Use the search bar to find the phrase you want to remove. 2. **Delete the Phrase:** * Navigate to the phrase, click <img alt="menu icon" /> under the **Actions** tab, and select **Delete**. * Confirm the deletion in the popup prompt to remove the phrase from the list. ### Best Practices * **Consistency:**\ Regularly review and update phrases to ensure they remain aligned with current user search behavior and terminology. * **Relevance:**\ Only add phrases that reflect common expressions or compound terms frequently used by your audience, to maintain search accuracy. * **Language Considerations:**\ Ensure that phrases are added for all relevant languages, especially if your platform caters to a multilingual audience. By managing phrases effectively, you can significantly enhance the accuracy of search results, ensuring users get precise and relevant outcomes. This not only leads to a better shopping experience but also drives higher customer satisfaction and engagement. # Search Preview Source: https://help.experro.com/experro_discovery/search/search_preview Unlock a real‑time simulation of your storefront’s search journey. The Search Preview Settings feature delivers a live, front‑end style interface mimicking the shopper view across global, category, or collection contexts so merchants and marketers can fine‑tune merchandising rules, personalize search logic, monitor analytics, and control discoverability **before** pushing changes live. <img alt="" /> ## Prerequisites * You must have **Administrator** access, or explicit permissions for the Discovery modules. * Any search algorithms or merchandising rules you plan to preview should already be configured and active in your workspace. ## Opening the Search Preview There are three entry points to launch Search Preview: ### Global Search Preview 1. Navigate to **Discovery** in the main menu. 2. Click the **Search Preview** button in the top navigation bar. 3. A new window overlays your screen, displaying an empty search interface. <img alt="" /> <Info> No products load until you enter a search term or select a filter. </Info> ### Algorithm‑Specific Preview 1. Open any search **Algorithm** in the Discovery module. 2. Click **Preview** in the top‑right corner of the Algorithm settings page. 3. The preview window auto‑populates results based on the current algorithm configuration and your search term. <img alt="" /> <Tip> Use this to instantly see how ranking models, Gen AI variants, or personalization settings affect results. </Tip> ### Merchandising Preview 1. Navigate to any rule in your **Merchandising Rules** list. 2. Click the **Preview** action for that rule. 3. The search preview window then reflects the **combined impact of all the merchandising rules** on your results (boosts, buries, pins, slots, etc.). **For example**: You’ll see how promotions, exclusions, and pinning rules all interact in the live preview. ## Selecting a Search Scope Within the preview window, use the **Scope** dropdown (to the left of the search bar) to choose one of three modes: 1. **Search**: Perform a global keyword search across your entire catalog. 2. **Category**: Restrict results to product categories. 3. **Collection**: Limit results to a Experro‑defined collection. <img alt="" /> The product grid updates automatically based on your selected scope. ## Using the Search Bar and Suggestions ### Focus‑Triggered Suggestions * **Popular Searches**: Appears when you click into the search bar without typing, showing commonly used search terms. ### Typing‑Based Suggestions As you enter text, a dynamic dropdown offers: * **Recent Searches** for your user session. * **Did you mean…?** corrections for misspellings. * **Category Suggestions** matching your terms. * **Content Suggestions** (e.g., relevant blog posts or guides). * **View all (X) products** link when the result set is large. Click any suggestion to populate the search input and refresh the results grid. ## Reviewing Search Results ### Product Grid Layout * Displays product cards in a responsive grid. * Each card includes: * **Image** and **Title** (fixed) * Key metrics: Price, SKU, Views, Searches, Revenue * Performance data: CTR, Conversion % * Merchandising icons (Pin, Boost, Exclude, etc.) <img alt="" /> ### Facet Filters * Toggle the **View Facets** button to open or collapse the filter sidebar. ### Sorting Options 1. Click the **Sort** dropdown in the top‑right of the results panel. 2. Choose from: Relevance (default), Price (Low→High/High→Low), A→Z, Z→A, Newest. 3. Results reorder instantly based on your selection. ## Customizing Displayed Fields To tailor which data points appear on product cards: 1. Click **Fields** → **Edit Product Fields**. 2. In the popup, drag required fields from the Available list into the Selected list (max 10). 3. Reorder fields by dragging them up or down. 4. Click **Save** to update the product cards or **Cancel** to revert. <Info> **Locked Fields:** Image and Title cannot be removed to maintain clarity. </Info> ## Comparing Algorithm Variants Activate **Side‑by‑Side Preview** to evaluate two algorithm variants simultaneously: <img alt="" /> 1. Toggle **Side‑by‑Side** in the preview toolbar. 2. Two panes appear, each reflecting a different variant’s results. 3. Use this comparison to decide on optimal ranking or personalization strategies. <Info> **Requirement:** At least two variants must exist for this view to enable. </Info> ## Exploring the Settings Sidebar Click the **Settings** icon (top‑right) to open the sidebar, then switch between tabs: <img alt="" /> ### Discovery Settings * **Algorithm Overview**: View the algorithm’s name, scope, and currently selected variant. You can also switch between the variants here. * **Configuration Snapshot**: See Gen AI Search configuration, enrichment settings (synonyms, stopwords, etc.), and the active results ranking strategy. * **Deep Dive**: Click the edit icon next to the algorithm name to jump directly to the Algorithm page and update settings. ### Merchandising Rules * **Rule Summary**: Review all active merchandising rules—global, search‑term, category, and collection applied to your current preview. * **Toggle & Edit**: Enable or disable any rule on the fly. * **Quick Access**: Click an individual rule’s name and click on the edit icon to navigate to its full configuration screen. ### Personalization Settings * **When Disabled**: You’ll see a prompt with a button to open the Algorithm settings. From there, enable personalization under the Discovery Algorithm configuration. * **When Enabled**: A searchable dropdown appears, letting you select a user to apply their Ideal Customer Profile (ICP) to the preview. * **Sync with Algorithm**: The personalization options and ICP details reflect whatever algorithm variant is active in the above Discovery settings. # Search Redirects Source: https://help.experro.com/experro_discovery/search/search_redirects Search Redirects in Experro empower you to effortlessly guide users to specific pages or search results based on their queries. By intercepting a user’s search term and mapping it to a predetermined URL or results page, this feature streamlines navigation and ensures that customers are quickly directed to the most relevant content. * **Enhanced User Experience:**\ Redirects immediately take users to the content that best matches their queries, reducing search time and providing a smooth, intuitive journey. * **Promotion of Key Content:**\ Administrators can highlight important pages or promotional content—such as a "Contact Us" page or a seasonal product collection—by automatically redirecting relevant queries to these destinations. * **Improved Search Relevance:**\ By funneling users to specifically curated pages, search redirects help ensure that search results align with user intent, boosting both engagement and satisfaction. ## How It Works Experro intercepts user search queries and compares them with preconfigured redirect rules. When a query matches a rule, the system automatically sends the user to the designated URL or results page. For example, if a user searches for “contact information,” the system can be set to redirect them directly to your "Contact Us" page. Similarly, a search for a specific product name might trigger a redirect to that product’s detail page. ## Managing Search Redirects Managing search redirects is intuitive and centralized within the Experro Dashboard. Follow these steps to view and manage redirect rules: 1. **Access the Redirects Interface:** * Navigate to **Discovery → Search & Autocomplete → Redirects** from the left sidebar. * The interface displays a list of all active redirect rules, allowing you to search, view, and manage them. <img alt="" /> 2. **Viewing and Searching:** * Use the search bar to quickly locate a specific redirect rule by name. * On this screen, you can view its detailed configuration, including the search term(s) and target URL. 3. **Managing Redirects:** * **Add a Redirect:** * Click the **Add Redirect** button. * In the popup, enter the **Search Terms** (press Tab to confirm the term), specify the **Target URL**, and select the **Language** to determine the correct URL slug. * Click **Save** to activate the redirect rule.\\ <img alt="" /> * **Edit a Redirect:** * Navigate to the rule, click <img alt="menu icon" /> under **Actions** column , then select **Edit**. * Modify details such as the **Search term** or **Target URL**, and click **Save** to update the rule. * **Delete Redirects:** * Navigate to the rule, click <img alt="menu icon" /> under **Actions** column , then select **Delete**. * Confirm the deletion in the popup prompt. You can also select multiple records using checkboxes and delete them in bulk. ## Best Practices * **Relevance:**\ Ensure each redirect rule directly aligns with the user query and leads to content that meets their needs. * **Testing:**\ Regularly test redirect rules to confirm they lead to the correct destinations and maintain a seamless user experience. * **Transparency:**\ When applicable, inform users that a redirect has occurred and offer them options to navigate to alternative content if needed. * **Maintenance:**\ Periodically review and update your redirect rules to reflect changes in your website content, promotions, or evolving user behavior. By effectively integrating search redirects, you can optimize the search experience within Experro—helping users quickly access the most pertinent content and driving higher engagement and conversion rates. # Synonyms Source: https://help.experro.com/experro_discovery/search/synonyms Synonyms in Experro are alternative words or phrases that are treated as equivalent during search queries. By mapping different terms that share the same meaning, synonyms enhance search relevance and ensure that users find the products they are looking for—even if they use varied terminology. This mechanism reduces the chances of returning no or irrelevant results for complex search queries. Example: For a website selling electronics, adding “mobile” as a synonym for “cell phone” ensures that a search for either term returns the same set of products. ## Use-Cases * **Improved Search Relevancy:**\ When a customer searches for “sofa,” synonyms like “couch” ensure that all relevant products are displayed, even if different terms are used in the product catalog. * **Maintain Consistency:**\ By bridging the gap between varied terminologies (e.g., “TV” and “television”), synonyms deliver consistent results, reducing user frustration. * **Language Localization:**\ Supporting multiple languages ensures that synonyms are relevant for diverse audiences. For instance, “mobile” might be used as a synonym for “cell phone” in certain regions, ensuring a unified search experience. ## Configuration Guide ### Viewing and Searching Synonyms 1. **Access the Synonyms Section:** * Use the navigation panel on the left side of the screen. * Navigate to **Discovery → Search & Autocomplete**, then select the **Synonyms** tab. * The screen will display a list of existing synonym rules. * Use the search bar at the top to locate a specific synonym by entering the term or synonym you are looking for. <img alt="" /> ### Adding Synonyms 1. **Click on "Add Synonyms":** * On the Synonyms screen, click the **Add Synonyms** button to open the pop-up form. 2. **Fill in the Fields:** | **Field Name** | **Description** | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Term** | Enter the primary term for which you want to add synonyms. | | **One Way / Two Way** | **One Way** maps only from the primary term to its synonym (e.g., “trainers” → “sneakers” but not the reverse) while **Two Way** creates a reciprocal mapping so that either term (e.g., “sneakers” or “trainers”) returns results for both. | | **Synonyms** | Enter the synonym(s) for the term. Type each synonym and press the tab key to confirm it. You can add multiple synonyms in this manner. | | **Languages** | Select the language for which the synonym applies. Use the checkbox **Apply to all languages** if applicable. | 3. **Save the Synonym:** * Once you have entered all required information, click **Save** to add the synonym to your list. <img alt="" /> ### Editing Synonyms 1. **Find the Synonym to Edit:** * Use the search bar to locate the synonym you wish to modify. 2. **Edit the Synonym:** * Click on the synonym to open the edit form, or navigate to the the term and click <img alt="menu icon" /> under the **Action** field , then select **Edit**. * Update the necessary fields (e.g., **Term, One Way/Two Way setting, Synonyms, Languages**). 3. **Save Changes:** * Click **Save** to apply the updates. ### Deleting Synonyms 1. **Select the Synonym to Delete:** * Use the search bar to locate the synonym you want to remove. 2. **Delete the Synonym:** * Hover over the synonym, click <img alt="menu icon" /> under the **Action** field, and select **Delete** from the dropdown menu. * Confirm deletion in the popup prompt. By following these steps, you can effectively manage synonyms in Experro, enhancing and streamlining search relevance. ## Best Practices for Managing Synonyms To maximize the effectiveness of synonyms and maintain high search relevance across your storefront, follow these best practices: ### Use Domain-Relevant Synonyms Add synonyms that align with your product catalog and customer vocabulary. For example, in fashion: “sneakers” ↔ “trainers”; in furniture: “sofa” ↔ “couch.” Avoid overloading your search engine with irrelevant or rarely used alternates. ### Choose the Right Mapping Type Use **Two-Way Synonyms** when both terms are commonly interchangeable (e.g., “TV” and “television”), and **One-Way Synonyms** when you want to drive traffic from a broader term to a specific variant (e.g., “trainers” → “Nike Air Max”). ### Localize for Multilingual Audiences Create synonyms specific to languages or regions. Use the **Select Channel** to apply synonyms only where they are contextually accurate, ensuring better experiences for international shoppers. ### Avoid Overlapping or Redundant Synonyms Avoid configuring synonyms that already exist within your catalog data or tagging system. Too many synonym entries can reduce precision and may confuse the engine, returning irrelevant results. ### Leverage Search Insights Use **Search analytics** to find popular queries that return no results. These are often opportunities to add missing or unexpected synonyms based on real customer language. ### Don’t Use Synonyms as a Crutch Avoid relying on synonyms to fix broader data issues (e.g., inconsistent product naming or missing metadata). Synonyms should enhance search—not cover for catalog hygiene problems. ### Review Regularly Synonyms aren’t “set it and forget it.” Periodically review them alongside your evolving product range, customer behavior, and seasonal trends to keep mappings fresh and relevant. By implementing these best practices, you’ll ensure that Experro Synonyms help bridge the gap between how users search and how products are described—leading to better discovery and higher conversion rates. # Connect your store Source: https://help.experro.com/plug_and_play/bigcommerce_integration/connect_your_store ## Prerequisites for BigCommerce Integration To prepare your BigCommerce store for Experro Discovery, make sure you have: 1. **BigCommerce Control Panel Admin Access**\ Administrator rights to the BigCommerce control panel, including the ability to create and manage Store “API Accounts.” 2. **API Account Creation Capability**\ Access to **Settings** → **Store Level API Accounts** to create a V2/V3 API token with the required OAuth scopes. 3. **Desired API Scopes Defined**\ Identify the OAuth permissions you need (e.g., Store Catalog, Customers, Orders, Themes, Content) before token creation. (These details will also be provided in this integration guide.) 4. **Downloaded Credentials File**\ Ability to securely download and preserve the `.txt` file containing your **access token**, **client ID**, **client secret**, and **API path**—this file cannot be retrieved again. 5. **Experro Admin Panel Access**\ A Workspace Admin role in Experro to navigate to **Workspace Settings** → **Store Integration**, select BigCommerce, and enter the credentials. 6. **Store Hash Identification**\ Knowledge of the BigCommerce Store Hash (from the API path URL: `https://api.bigcommerce.com/stores/<storehash>/v3`) for input during Experro configuration. ## Connect to the Store Connecting to your store consists of two main steps: * **Create an API Token in BigCommerce** * **Configure the Integration in the Experro Admin Panel** ### Create an API Token in BigCommerce <Steps> <Step title="Access Store‑Level API Accounts"> * Log in to your BigCommerce admin panel. * Navigate to **Settings** → **Store‑Level API Accounts**.\\ <img alt="" /> </Step> <Step title="Create a New API Account"> * Click **Create API Account**. * For **Token Type**, select **V2/V3 API Token**. * Give the account a descriptive name (e.g., `exp_discovery`). * The **API Path** will be populated automatically.\\ <img alt="" /> </Step> <Step title="Configure OAuth Scopes"> * In the scopes list, enable the permissions required by Experro for full functionality. Refer to the BigCommerce admin panel screenshot provided below. <div> <img alt="Detailed diagram showing required OAuth scopes" /> </div> </Step> <Step title="Save and Retrieve Credentials"> * Click **Save**. A `.txt` file containing your **Client ID**, **Client Secret**, **Access Token**, and **API Path** will automatically download. <Info> Store this file securely.</Info> </Step> </Steps> ### Configure the Integration in the Experro Admin Panel <Steps> <Step title="Navigate to Store Integration"> * In Experro, go to **Workspace Settings** → **Store Integration**. * Choose **BigCommerce** and Click **Add Platform**. * Click **Install** to begin configuration. <img alt="" /> * Click **Add Store**. </Step> <Step title="Enter Store Details"> * **Environment:** Select **Production** or **Development**. * **Store Name:** Enter a memorable identifier (e.g., `BigCommerce_store`). </Step> <Step title="Provide API Credentials"> * **Store Hash:** Extract the `<storehash>` from your API Path (`https://api.bigcommerce.com/stores/<storehash>/v3`). * **Store Token:** Paste the **Access Token** from the downloaded `.txt` file. * **Client ID** and **Client Secret:** Also copied from the `.txt` file.\\ <img alt="" /> </Step> <Step title="Test Connection"> * Click **Test API** to verify that Experro can connect to your store. * Upon success, click **Next**. </Step> <Step title="Configure Data Synchronization"> * **Languages:** Select the storefront language(s). * **Channel:** Choose which sales channel to integrate.\\ <img alt="" /> </Step> <Step title="Establish Connection"> * Click **Connect**. Experro will begin importing your catalog, orders, and customer data. </Step> </Steps> With these steps completed, your BigCommerce store is now connected to Experro, unlocking advanced discovery, merchandising, and analytics capabilities. ## Customise UI Once connected, you can head over to our [UI Customization guide](/plug_and_play/ui_customisation) to design your discovery interface. ## Theme Integration Once the UI customisation is complete, follow the [Theme Integration guide](/plug_and_play/bigcommerce_integration/theme_integration) to make your changes live on BigCommerce. # Overview Source: https://help.experro.com/plug_and_play/bigcommerce_integration/overview Integrating your BigCommerce store with Experro enables seamless synchronization of product, order, and customer data, allowing you to leverage Experro’s AI-driven search, merchandising, and analytics on your storefront. The full integration workflow consists of three key phases: <Steps> <Step title="Connect to Your Store"> Establish a secure link between your BigCommerce admin and Experro Discovery by installing and configuring the custom Experro app. </Step> <Step title="Customize Your UI"> Tailor the look and feel of search bars, autocomplete dropdowns, product listings, facets, and more directly from the Experro Admin Panel to match your brand’s style. </Step> <Step title="Publish to Production"> Apply your UI changes and search configurations live to your storefront by pushing the Experro components into your BigCommerce theme. </Step> </Steps> Once the [Store is Connected](/plug_and_play/bigcommerce_integration/connect_your_store), you can head over to our [UI Customization guide](/plug_and_play/ui_customisation/overview) to design your discovery interface, and then follow the [Theme Integration guide](/plug_and_play/bigcommerce_integration/theme_integration) to make your changes live on BigCommerce. # Theme Integration Source: https://help.experro.com/plug_and_play/bigcommerce_integration/theme_integration Here’s how to publish your Experro UI customizations to your BigCommerce storefront once you’ve finished connecting the store and configuring your UI: ## Prerequisites * **Store Connection:** You’ve already connected your BigCommerce store in Experro (see [Store Integration](/plug_and_play/bigcommerce_integration/connect_your_store) for details). * **UI Customization Complete:** All desired changes under **UI Customization → Search Results**, **Layout**, **CSS & JS**, etc., have been configured and saved in the Experro Admin Panel. * **Experro Default Theme:** These steps apply when you’re using the Experro Default Theme on your store. <Steps> <Step title="Modify Your BigCommerce Theme"> 1. **Open BigCommerce Admin**\ Log in to your BigCommerce control panel. 2. **Edit Theme Files** * In case of multiple storefronts, Navigate to **Channels** → Select your desired storefront. * In case of single store, Navigate to **Storefront** → **Themes**. * Select **Edit Theme Files**.\\ <img alt="" /> 3. **Locate the Category Template** * In the file tree, open `templates/pages/category.html`.\\ <img alt="" /> 4. **Insert the Experro Container** * Identify and comment out (or remove) the existing product‐grid wrapper where you want Experro to render. * Replace it with: ```html theme={null} <div style="min-height: 100vh;"> <div id="exp-cat-page-selector"></div> </div> ``` <img alt="" /> 5. **Save & Apply**\ Click **Save** to commit your changes. BigCommerce will re‐apply the updated template immediately. </Step> <Step title="Inject the Experro Initialization Script"> 1. **Open Experro Admin Panel**\ Go to **Discovery → UI Customization → CSS & JS**. 2. **Paste the Initialization Snippet**\ In the **JavaScript (JS) Editor** section, enter: ```js theme={null} window["Experro"].BeforeInit(` window["Experro"].SetConfig({ "desktop_view": { "autocomplete_replace_with": "input", "autocomplete_block_selector": "<your_search_selector>", }, "mobile_view": { "autocomplete_replace_with": "icon", "autocomplete_block_selector": "<your_search_selector>", } }); `); ``` 3. **Save Changes**\ Click **Save** in the CSS & JS tab. </Step> <Step title="Optional: Personal Branding for Experro Default Theme"> * If you’re using **Experro Default Theme**, you can override its CSS variables to match your brand. * In the same **CSS & JS** tab (under the **CSS** editor), paste the following: ```css theme={null} :root { --exp-container-width: 1400px; --exp-card-image-aspect-ratio: 3 / 4; --exp-color-gray-dark: #333; --exp-color-gray-light: #757575; --exp-color-light: #fff; --exp-border-color: #e8e8e8; --exp-sale-badge-color: #fff; --exp-sale-badge-background-color: #be5048; --exp-custom-badge-color: #fff; --exp-custom-badge-background-color: #8b5cf6; } ``` * Adjust **any** of these `--exp-…` variables to suit your fonts, colors, and layouts. </Step> <Step title="Inject the Experro is Live Script"> * In the Experro Admin Panel, go to **Discovery → UI Customization → CSS & JS**. * In the **JavaScript (JS) Editor** section, enter: ```js theme={null} window["Experro"].BeforeInit(` window["Experro"].SetConfig({ "is_live": true }) `); ``` </Step> <Step title="Preview and Publish"> 1. **Preview Locally**\ Use your storefront’s preview mode to verify that: * The Experro container is rendering your custom UI. * Search and facet components behave as expected on both desktop and mobile. 2. **Publish to Production** * When you’re satisfied, click **Publish** in the Experro Admin Panel. * Your Experro Discovery UI and behavior changes will go live on your BigCommerce store. </Step> </Steps> By following these steps—updating your theme template, injecting the Experro initialization script, and then publishing—you’ll ensure that your Experro Discovery enhancements appear seamlessly on your BigCommerce storefront. # UI Customisation Source: https://help.experro.com/plug_and_play/bigcommerce_integration/ui_customisation ## Customise your UI Once connected, you can head over to our [UI Customization guide](/plug_and_play/ui_customisation/overview) to design your discovery interface. # Advanced UI Settings Source: https://help.experro.com/plug_and_play/css_customisation This guide outlines all the advanced options available within the Plug & Play integration of Experro. These settings can be updated directly through the UI using the Custom **JS** tab in Experro's UI Customization panel allowing you to tailor how your components behave. Here is the sample code to be pasted in the Custom **JS** tab in Experro's UI Customization panel. Replace the values in `<>` with your own selectors and change the default values as per your requirements. Here is the detailed explanation of each setting: ``` window["Experro"].BeforeInit(` window["Experro"].SetConfig({ "content_page_desc_count": 200, "product_desc_count": 70, "autocomplete_desc_count": 50, "is_search_redirect_enabled": true, "is_live": false, "add_to_cart_behavior": "redirect", "spellcheck_enabled": false, "compare_limit": 4, "did_you_mean_limit": 1, "desktop_view": { "autocomplete_block_selector": "<your_autocomplete_block_selector>", "autocomplete_input_selector": "<your_autocomplete_input_selector>", "autocomplete_result_selector": "<your_autocomplete_result_selector>", "autocomplete_replace_with": "input", "category_page_selector": "<your_category_page_selector>", "search_page_selector": "<your_search_page_selector>", "swatch_visibility_scope": "limited", "swatch_visibility_type": "image", "placeholder_animation_type": "typing" }, "mobile_view": { "autocomplete_block_selector": "<your_autocomplete_block_selector>", "autocomplete_input_selector": "<your_autocomplete_input_selector>", "autocomplete_result_selector": "<your_autocomplete_result_selector>", "autocomplete_replace_with": "icon", "category_page_selector": "<your_category_page_selector>", "search_page_selector": "<your_search_page_selector>", "swatch_visibility_scope": "limited", "swatch_visibility_type": "image", "placeholder_animation_type": "typing" } }) `); ``` ## Global Settings These settings apply universally across the platform. | **Setting** | **Description** | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `content_page_desc_count` | Maximum number of characters to show for content descriptions. (Default: `200`) | | `product_desc_count` | Truncation limit for product descriptions across product listings. (Default: `70`) | | `autocomplete_desc_count` | Character limit for product descriptions shown in the autocomplete dropdown. (Default: `50`) | | `is_search_redirect_enabled` | If enabled (`true`), certain queries will auto-redirect to specific landing pages. | | `add_to_cart_behavior` | Determines add-to-cart behavior: `redirect` (takes user to cart) or `modal` (inline popup). | | `spellcheck_enabled` | If set to `true`, activates spelling correction in search & autocomplete suggestions. | | `is_live` | Indicates whether Experro is live on the store. Set to true to enable live features or false for development mode. | | `compare_limit` | Restricts the number of products that can be added for comparison. (Only for BigCommerce. Default: `4`) | | `did_you_mean_limit` | Limits the number of "Did You Mean" suggestions displayed. (Default: `1`) | ## Desktop View Settings These selectors define how Experro’s frontend plug-in integrates with your desktop layout. | **Setting** | **Description** | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `autocomplete_block_selector` | Selector where the autocomplete block (icon or input) will be inserted. | | `autocomplete_input_selector` | Selector holding the autocomplete input. | | `autocomplete_result_selector` | Selector where autocomplete results should be rendered. | | `autocomplete_replace_with` | Replaces search bar with either `icon` or `input` field. | | `category_page_selector` | Selector for injecting category page product results. | | `search_page_selector` | Selector for injecting search results on search listing pages. | | `swatch_visibility_scope` | Controls how many swatches to show: `limited` (default) or `all`. | | `swatch_visibility_type` | Type of swatch display: `image`, `text`, or `color`. Default: `image` | | `placeholder_animation_type` | Determines the animation style of the search box placeholder text. Possible values: `typing`, `rotation`, `fade`. | ## Mobile View Settings These settings mirror the desktop options but are scoped specifically for mobile layouts. | **Setting** | **Description** | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `autocomplete_block_selector` | Selector to position autocomplete block in mobile view. | | `autocomplete_input_selector` | Input selector for mobile autocomplete. | | `autocomplete_result_selector` | Where the mobile autocomplete results should render. | | `autocomplete_replace_with` | Mobile option to toggle between search `icon` or full `input` field. | | `category_page_selector` | Selector for rendering mobile category listings. | | `search_page_selector` | Selector for rendering mobile search result pages. | | `swatch_visibility_scope` | Mobile-specific swatch scope visibility: `limited` (default) or `all`. | | `swatch_visibility_type` | Swatch display mode for mobile: `image`, `text`, or `color`. | | `placeholder_animation_type` | Determines the animation style of the search box placeholder text. Possible values: `typing`, `rotation`, `fade`. | By configuring these settings, you gain full visual and behavioral control over how Experro plug-and-play features integrate into your site experience across both desktop and mobile storefronts. # FAQs Source: https://help.experro.com/plug_and_play/faq ## General <Accordion title="Q1. What is the Experro Plug & Play feature?"> A: Plug & Play lets merchants quickly enable Experro’s AI‑driven search, merchandising, and analytics on their storefront without custom development. You install a small app or install token, configure settings in the Experro Admin Panel, then publish the UI components (search bar, facets, etc.) directly to your live store. </Accordion> <Accordion title="Q2. Which eCommerce platforms does Plug & Play support?"> A: Currently Shopify and BigCommerce. Support for additional platforms is planned for future releases. </Accordion> ## Prerequisites <Accordion title="Q3. What do I need before starting a Shopify integration?"> * A Shopify store with admin access * Permission to create a custom app and configure API scopes * A safe place to store the generated Admin API access token (you see it only once) </Accordion> <Accordion title="Q4. What do I need before starting a BigCommerce integration?"> * A BigCommerce store with admin access * Permission to create a Store‑level API account * The downloaded `.txt` file containing your API token, Client ID, and Client Secret </Accordion> ## Shopify Integration <Accordion title="Q5. How do I connect my Shopify store to Experro?"> 1. In Shopify Admin: **Settings → Apps & Sales Channels → Develop apps → Create app**. 2. Set the App Name, then under **Configure Admin API scopes**, enable all required scopes (e.g., `read_products`, `write_themes`, etc.). 3. Return to the Overview tab and click **Install**, then copy the displayed access token. 4. In Experro Admin: **Workspace Settings → Store Integration → Add Store**. * Select **Shopify**, enter Environment, Store Reference Name, Shopify Domain, Admin API Token, API Key, and API Secret. * Test credentials, then configure language and metafield namespaces. * Click **Connect**. </Accordion> <Accordion title="Q6. How do I publish Experro in Shopify once the UI is customized?"> > *Only for Experro Default Theme.* 1. In Shopify Admin: **Online Store → Themes → Customize**. 2. On the category/listing page, **Add Section → Custom Liquid**. 3. Paste: ```html theme={null} <div style="min-height: 100vh;"> <div id="exp-cat-page-selector"></div> </div> ``` 4. Hide the default product grid, then **Save**. 5. In Experro Admin **UI Customisation → CSS & JS**, paste the required JS snippet. 6. Click **Publish**; your Experro Discovery UI goes live. </Accordion> ## BigCommerce Integration <Accordion title="Q7. How do I create the API token in BigCommerce?"> 1. In BigCommerce Admin: **Settings → Store API Accounts → Create API Token**. 2. Choose **V2/V3 API Token**, name it (e.g., `exp_discovery`), leave Path default, select OAuth scopes as needed. 3. Click **Save** to download a `.txt` file containing your Client ID, Client Secret, Access Token, and API Path. </Accordion> <Accordion title="Q8. How do I connect BigCommerce to Experro?"> 1. In Experro Admin: **Workspace Settings → Store Integration → Add Platform → BigCommerce → Install**. 2. Enter Environment, Store Reference Name, then from your `.txt` file: * **Store Hash** (from the API Path URL) * **Client ID**, **Client Secret**, **Access Token** 3. Test API connection, then configure language and metafield namespaces. 4. Click **Connect**. </Accordion> <Accordion title="Q9. How do I publish Experro in BigCommerce?"> > *Only for Experro Default Theme.* 1. In BigCommerce Admin: **Storefront → Themes → Edit Theme Files**. 2. Open `templates/pages/category.html`, comment out the existing product grid container and replace with: ```html theme={null} <div style="min-height: 100vh;"> <div id="exp-cat-page-selector"></div> </div> ``` 3. Save & Apply. 4. In Experro Admin **UI Customisation → CSS & JS**, paste the provided JS snippet. 5. Save, Preview, and Publish. </Accordion> *** ## Troubleshooting & Support <Accordion title="Q10. What if my connection test fails?"> * Double‑check your API credentials (token, keys, store hash/domain). * Ensure the required scopes are enabled and that your store has API access. * If issues persist, contact Experro Support with a screenshot of the error. </Accordion> <Accordion title="Q11. Can I customize the look & feel after integration?"> Yes—use the **UI Customisation** section in Experro Admin to adjust Theme, Layout, Search Results, Autocomplete, CSS & JS, and Translations. See the [UI Customisation guide](/plug_and_play/ui_customisation) for details. </Accordion> <Accordion title="Q12. Do I need to repeat these steps for new environments?"> For separate dev and prod stores, repeat the integration and publish steps in each environment using the appropriate credentials and store references. </Accordion> These FAQs should address the most common questions encountered during Plug & Play integration with Shopify and BigCommerce. If you have additional questions, please reach out to our support team or consult the full documentation. # Overview Source: https://help.experro.com/plug_and_play/magento_integration/overview ## Magento–Experro Integration Overview To enable Experro’s search, recommendations, and analytics on your Magento store, you’ll complete **two main phases**: 1. **Store Integration** * **Install & enable** the Experro Connector module in Magento. * **Link** your Magento store to Experro by adding the store in the Experro Admin, copying the generated token, and pasting it into Magento’s “Connect to Experro” settings. * **Verify** the connection to ensure data sync (products, customers, orders). 2. **Theme Integration** * **Inject** Experro’s front‑end scripts into your store’s footer. * **Configure** the base URL, e‑commerce variables, and CSS/JS templates so that Experro UI components render correctly on your storefront. * **Save Configuration** to activate the new theme integration. Once both phases are done, Experro will be fully wired into your Magento site—back end synced and front end enhanced—delivering a seamless shopping experience. # Connect your store Source: https://help.experro.com/plug_and_play/magento_integration/store_integration This guide is divided into two major segments: * **Adding the Experro Extension to Magento** * **Configuring the Magento–Experro Integration** ## 1. Adding the Experro Extension to Magento ### Overview In this section, you will add the Experro extension to your Magento installation. Follow these steps carefully to ensure that the module is correctly installed and visible in the Magento Admin panel. ### Prerequisites * Ensure that you have already downloaded the Experro Connector ZIP file to your server. * Contact the Experro Support Team if you do not have the required file. ### Installation Steps <Steps> <Step title="Extract the Experro Connector Module Files"> Extract the ZIP folder into the Magento root directory at the following path: ```bash theme={null} MagentoRoot/app/code ``` </Step> <Step title="Verify the Folder Structure"> Confirm that the extracted folder structure appears as: ```bash theme={null} MagentoRoot/app/code/Experro/Connect ``` </Step> <Step title="Run Magento Compilation Commands"> Open your terminal in the Magento root directory and execute the following commands one by one: ``` php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f php bin/magento indexer:reindex # Only if required php bin/magento cache:clean php bin/magento cache:flush chmod 777 -R var pub generated ``` </Step> <Step title="Module Confirmation"> Once the installation is complete, log in to your Magento Admin panel. You should see the Experro module logo in the left sidebar. To verify connectivity, navigate to: ``` Admin > Experro > System Status ``` </Step> </Steps> ## 2. Configuring the Magento–Experro Integration ### Prerequisites * Ensure that you have already uploaded the Experro Connector ZIP file to your server as shown in the previous section. ### Integration Steps <Steps> <Step title="Magento Admin Access"> * Log in to the Magento Admin panel. * Navigate to **Experro Connect**. <img alt="" /> <img alt="" /> </Step> <Step title="Experro Admin Configuration"> * Log in to the Experro Admin panel. * Navigate to the **Platform** section. * Select **Install Magento Integration**. * Click **Add Store** and fill in the required details (Environment, Store name, Magento store URL, Channel, and Language). * Click **Next**. <img alt="" /> </Step> <Step title="Copy Experro Token"> * The system will redirect you to a new page displaying the Experro token. * Copy the displayed token. <img alt="" /> </Step> <Step title="Connect to Experro from Magento"> * Return to the Magento Admin panel. * Click on the **Connect to Experro** button. <img alt="" /> </Step> <Step title="Enter Connection Details"> * You will be redirected to a connection form. * Paste the Experro token (copied earlier) and fill in the other required details. * Click **Next**. <img alt="" /> </Step> <Step title="Store Details Page"> * The store details page will now be displayed in Magento. <img alt="" /> </Step> <Step title="Verification"> * Navigate to **Experro**, and click the **Verify** button. <img alt="" /> </Step> <Step title="OAuth Details Configuration"> * After clicking **Verify**, you will be redirected to the **OAuth Details** page. * Copy the store details information from the Magento Admin panel into the respective fields. * Click **Next**. <img alt="" /> </Step> <Step title="Final Storeview Configuration"> * Complete the final details on the **Storeview Details** page. * Click **Connect**. * You should see a confirmation message: > **Store added successfully** * The system will then redirect you to the store listing page, where your newly added store will be displayed. <img alt="" /> </Step> </Steps> This guide should help you smoothly integrate Magento with Experro. # Theme Integration Source: https://help.experro.com/plug_and_play/magento_integration/theme_integration ## Overview In this section, you’ll inject the Experro theme scripts into your Magento storefront via the Admin panel. These scripts will load your custom UI templates, CSS/JS, and wire up all e‑commerce variables and selectors. ## Steps <Steps> <Step title="Log in to Magento Admin"> Open your Magento Admin panel in your browser. </Step> <Step title="Navigate to the Storefront Configuration"> * Go to **Content → Configuration**. * Select the Store and language as per your requirement. </Step> <Step title="Locate the Footer HTML"> * Expand **Other Settings → Footer**. * Scroll to **Miscellaneous HTML**. </Step> <Step title="Inject the Experro Theme Scripts"> In the **Miscellaneous HTML** editor, paste the following block **(replace all `<…>` placeholders as noted below)**: ``` <script id="exp-custom-script"> window["ExpBaseUrl"] = "<your_experro_base_url>" fetch(`https://${window["ExpBaseUrl"]}/apis/ui-customization/public/v1/versions/published?fields=*&locale=en-us`, { method: "GET", }).then(response => { return response.json(); }).then(customResponse => { window["ExpConfigs"] = { ecommerce_variables: { conversion_rate: 1, page_type: "page", currency_code: "USD" } }; window["ExpTemplates"] = { templates: {}, css_and_js: {} }; const { ui_version_settings } = customResponse.Data?.item; const templates = { ...ui_version_settings.templates }; const css_and_js = { ...ui_version_settings.css_and_js }; delete ui_version_settings.ecommerce_variables; delete ui_version_settings.templates; delete ui_version_settings.css_and_js; Object.assign(window["ExpConfigs"], ui_version_settings); Object.assign(window["ExpTemplates"].templates, templates); Object.assign(window["ExpTemplates"].css_and_js, css_and_js); }).catch(error => console.error("Fetch error:", error)); </script> <script src="https://${window["ExpBaseUrl"]}/exp-themes/core/v1/main.min.js"></script> ``` </Step> <Step title="Determine Your <your_experro_base_url> and replace it in the above script"> 1. In **Experro Admin**, go to **Workspace Settings → Channels**. 2. Open **Channel Settings**. 3. Switch to the **Languages** tab. 4. Copy the **Language URL** corresponding to your store’s locale. 5. Replace `<your_experro_base_url>` in the script with this URL. </Step> <Step title="Replace Liquid Variables"> * For each `"<liquid_variable>"`, substitute the appropriate Magento Liquid variable. </Step> <Step title="Save Configuration"> * Click **Save Configuration**. Your Experro theme is now integrated into your Magento storefront. Visitors will see your custom UI components and e‑commerce data wired up automatically. </Step> <Step title="Page‑Specific Script & Selector Injection"> To enable Experro features on specific page types, you must insert **two separate pieces** into your theme templates: * **Configuration Script** – Add the `<script>` block to configure `ecommerce_variables` in the relevant PHTML or layout file. * **Placeholder Container** – Add the `<div id="exp-*-page-selector">` container in the HTML where Experro should render its widgets. </Step> <Step title="Category Listing Page"> * **Configuration Script** (e.g., in `view.phtml` before the product loop or via `catalog_category_view.xml`): ``` <script> Experro.SetEcommerceConfig({ "active_category": "<liquid_variable>", "category_name": "<liquid_variable>", }); </script> ``` * **Placeholder Container** (place this in your category template where listings appear): ```html theme={null} <div style="min-height: 100vh;"> <div id="exp-cat-page-selector"></div> </div> ``` </Step> <Step title="Product Detail Page"> * **Configuration Script** (add at top of `view.phtml` or via `catalog_product_view.xml`): ```html theme={null} <script> Experro.SetEcommerceConfig({ "product_sku": "<liquid_variable>", "product_id": "<liquid_variable>", "product_title": "<liquid_variable>", "product_price": "<liquid_variable>", }); </script> ``` </Step> <Step title="Checkout Page"> * **Configuration Script** (add at the start of `onepage.phtml` or via `checkout_index_index.xml`): ```html theme={null} <script> Experro.SetEcommerceConfig({ "cart_length": "<liquid_variable>", "order_id": "<liquid_variable>", "checkout_id": "<liquid_variable>", }); </script> ``` </Step> <Step title="(Optional) Search Results Page"> * **Placeholder Container** (in `search_result_index.xml` or `form.mini.phtml` to wrap search results): ```html theme={null} <div style="min-height: 100vh;"> <div id="exp-search-page-selector"></div> </div> ``` </Step> </Steps> # What is Experro Plug & Play? Source: https://help.experro.com/plug_and_play/overview The Experro “Plug & Play” feature delivers enterprise‑grade, AI‑powered search and discovery capabilities to your storefront in minutes—without deep developer involvement. Designed for merchants who want fast access to generative AI search, merchandising controls, and analytics, Plug & Play connects your e‑commerce platform to Experro, automatically syncs your catalog data, and exposes a simple UI for both look‑and‑feel customization and powerful search tuning. <img alt="" /> ## Overview of Plug & Play With Experro Plug & Play, you can: * **Instantly Enable AI Search:** Embed Experro’s search bar, autocomplete, and suggestion components into your store with just a few clicks. * **Customize On‑Site UI:** Adjust fonts, colors, placement, and behavior of search components directly via Experro’s Theme Editor or your own CSS/JavaScript overrides—no rebuilding your theme required. * **Leverage Generative AI Tuning:** Fine‑tune autocomplete suggestions, query understanding, synonyms, and stopword rules through an intuitive dashboard. * **Control Merchandising Rules:** Manage boost, bury, pin, slot, include/exclude, and sort rules at global, category, or search‑term scope—all from one central interface. * **Gain Real‑Time Insights:** Access Experro’s Opportunities and Analytics dashboards to track zero‑result searches, trending queries, facet interactions, and overall search performance. * **Scale Across Platforms:** Start on Shopify or BigCommerce today and seamlessly extend to other platforms as your needs evolve. <img /> This modular integration decouples your front end from complex backend setup. Once installed, your team can iterate on UI styling and search behavior without touching server‑side code. ## Supported Platforms <CardGroup> <Card title="Shopify" href="/plug_and_play/shopify_integration"> Install via the Shopify App Store or integrate using the Experro Admin panel to synchronize your product catalog and activate discovery. </Card> <Card title="BigCommerce" href="/plug_and_play/bigcommerce_integration"> Download the Experro app from the BigCommerce Marketplace or integrate using the Experro Admin panel to launch AI‑powered search and merchandising. </Card> </CardGroup> Each platform connector follows the same Plug & Play principles: minimal setup, full control over UI styling, and a unified Experro dashboard for search tuning and analytics. # Connect your store Source: https://help.experro.com/plug_and_play/shopify_integration/connect_your_store ## Steps to Connect to the Store <Steps> <Step title="Create an App from Shopify Dev Dashboard "> 1. Go to the **Shopify Dev Dashboard**. <img alt="" /> 2. Navigate to **Apps**. 3. Click **Create App**. <img alt="" /> 4.Enter the **App name**. <img alt="" /> 5. Add the **App URL**. ([https://admin.experro.app/](https://admin.experro.app/)) <img alt="" /> 6. Disable **Embed App in Shopify Admin**. <img alt="" /> 7. Select the required **API scopes**. A list of required Admin API scopes ready to configure: ``` read_customers,read_inventory,read_metaobjects,write_online_store_pages, read_online_store_pages,read_orders,read_product_listings,read_products, read_publications,read_locales,write_content,read_content,write_themes, read_themes,read_translations ``` 8. Disable **Use Legacy Install Flow**. <img alt="" /> 9. Click **Release**, enter the version name, and confirm the release. <img alt="" /> 10. After installation Under **Settings**, you will get: * a. **Client ID** and **Client Secret** under the API credentials, **copy both tokens**. <img alt="" /> </Step> <Step title="Install the App on Shopify Store"> 1. Go to the **Home** section in the Developer Dashboard. 2. Click **Install App**. <img alt="" /> 3. Select your Shopify store. <img alt="" /> 4. Click **Install** to complete the installation. <img alt="" /> </Step> <Step title="Open Experro Admin Panel"> 1. Log in to **admin.experro.com**. 2. Click **Connect Store** from the dashboard. <img alt="" /> 3. Select **Shopify** as the platform. 4. Click **Add Platform**. 5. Click **Install** to proceed. <img alt="" /> 6. Click on **Add Store** Button <img alt="" /> 7. Select the **Industry**. 8. Enter the **Store Name**. 9. Confirm the **Store Domain**. 10. Add **Client ID** and **Client Secret Code**. 11. Click on the **Next** Button. 12. Select the **Shopify Language**. 13. Click **Connect**. <img alt="" /> </Step> <Step title="Confirm Store Connection"> 1. Verify the store status appears as **Connected** in Experro. 2. Initial data synchronization begins automatically. </Step> </Steps> # Overview Source: https://help.experro.com/plug_and_play/shopify_integration/overview Integrating your Shopify store with Experro Discovery unlocks seamless AI‑powered search, merchandising, and analytics—all managed from a single pane of glass. The full integration workflow consists of three key phases: The full integration workflow consists of three key phases: <Steps> <Step title="Connect to Your Store"> Establish a secure link between your Shopify admin and Experro Discovery by installing and configuring the custom Experro app. </Step> <Step title="Customize Your UI"> Tailor the look and feel of search bars, autocomplete dropdowns, product listings, facets, and more directly from the Experro Admin Panel to match your brand’s style. </Step> <Step title="Theme Integration"> Apply your UI changes and search configurations live to your storefront by pushing the Experro components into your Shopify theme. </Step> <Step title="Recommendation Widget (Add On)"> Add and configure recommendation widgets to display personalized product suggestions across key storefront pages. </Step> </Steps> Once the [Store is Connected](/plug_and_play/shopify_integration/connect_your_store), you can head over to our [UI Customization guide](/plug_and_play/ui_customisation/overview) to design your discovery interface, and then follow the [Theme Integration guide](/plug_and_play/shopify_integration/theme_integration) to make your changes live on Shopify. # Recommendation Widget Source: https://help.experro.com/plug_and_play/shopify_integration/recommendation_widget ### Steps to Integrate <Steps> <Step title="Open the Shopify Theme Editor"> * In your Shopify Admin, navigate to **Online Store → Themes**. * Click **Edit Themes**. <img alt="" /> * Navigate to the page from the search bar where you want to add the Experro widget. </Step> <Step title="Add the Experro Container to Your Page"> * Click **Add section**, then choose **Experro Recommendation Widget**, drag and place it where you want on your page. <img alt="" /> </Step> <Step title="Required parameters configuration"> <img alt="" /> * Select or enter the required parameters as needed: * **Widget ID:** Experro Widget ID from the Experro Admin Panel. <img alt="" /> * **Widget Title:** Enter the main title that will be displayed at the top of the widget. * **Widget Sub Title (Optional):** Add a secondary line of text below the title to provide additional context or messaging. * **Products Limit:** Specify the total number of products to be displayed within the widget. * **Products per Row:** Define how many products should appear in a single row on desktop view. * **Products per Row (Mobile):** Set the number of products to be displayed in a single row on mobile devices for better responsiveness. * **Enable Slider:** Turn ON to display products in a slider format; if turned OFF, products will be shown in a grid layout. * **Show Arrows:** Enable this option to display left and right navigation arrows in the slider. * **Show Pagination (Dots):** Enable this option to show pagination dots that indicate the number of slides and current position. * **Autoplay:** Turn ON to allow the slider to automatically move through products without user interaction. * **Autoplay Speed (ms):** Set the time interval (in milliseconds) between each slide transition during autoplay. * **Slides to Scroll:** Define the number of product slides that move at a time when navigating the slider. <Info> Make sure to enter the Similar Product Widget ID in the Widget ID field on the PDP page to ensure the Similar Products widget displays correctly. </Info> <img alt="" /> </Step> <Step title="Save Your Theme Settings"> * Click **Save** at the top right to persist your changes in Shopify. </Step> </Steps> By following these steps, you’ll have a fully configured, **Experro Recommendation Widget** integrated into your Shopify storefront enabling personalized product suggestions and an enhanced shopping experience. # Theme Integration Source: https://help.experro.com/plug_and_play/shopify_integration/theme_integration ## Shopify Once your Experro Discovery store connection is live and you’ve finalized all UI customizations in the Experro Admin Panel, the last step is to publish those changes to your Shopify storefront. These instructions apply when you are using the **Experro Default Theme**. If you’ve integrated a custom theme or any other inbuilt theme, please follow your theme’s specific instructions or reach out to support. ### Prerequisites Before you begin, ensure that: * Your Shopify store is successfully connected in Experro. * All desired UI Customization tabs (Theme, Layout, Search Results, Autocomplete, CSS & JS, Translations) have been configured and saved. * You have access to your Shopify Admin with permission to edit Themes and Theme Code. * You are working on the **Experro Default Theme** (otherwise steps may vary). ### Steps to Integrate <Steps> <Step title="Open the Shopify Theme Editor"> * In your Shopify Admin, navigate to **Online Store → Themes**. * Click **Edit Themes**. <img alt="" /> * Navigate to the listing page. Select default collection from the page selection dropdown. <img alt="" /> </Step> <Step title="Add the Experro Container to Your Collection/Listing Pages"> * Click **Add section**, then choose **Exp Category Result**, drag and place it where you want on your page. <img alt="" /> </Step> <Step title="Hide the Native Product Grid"> * Still within that template, locate the default **Product Grid** section. * Click the eye icon to **hide** it (so it doesn’t conflict with Experro’s rendering). <img alt="" /> </Step> <Step title="Add the Experro Container to Your Search Results Pages"> <Info> This step is not compulsory. However, if you want to include the Experro search results UI, follow the steps below: </Info> * Navigate to the page using the search bar. * Click **Add section**, then choose **Experro AI Search Result**. * Click **Save**. <img alt="" /> </Step> <Step title="Optional: Personal Branding for Experro Default Theme"> * If you’re using **Experro Default Theme**, you can override its CSS variables to match your brand. * In the same **CSS & JS** tab (under the **CSS** editor), paste the following: ```css theme={null} :root { --exp-container-width: 1400px; --exp-card-image-aspect-ratio: 3 / 4; --exp-color-gray-dark: #333; --exp-color-gray-light: #757575; --exp-color-light: #fff; --exp-border-color: #e8e8e8; --exp-sale-badge-color: #fff; --exp-sale-badge-background-color: #be5048; --exp-custom-badge-color: #fff; --exp-custom-badge-background-color: #8b5cf6; } ``` * Adjust **any** of these `--exp-…` variables to suit your fonts, colors, and layouts. </Step> <Step title="Inject the Experro is Live Script"> * Before injecting the Experro is live script, please ensure that you use the preview mode from Experro Admin panel to verify that Experro is rendering your custom UI. * After previewing your custom UI and search experience, you can make it live by injecting the Experro Live Script into your site. * In the Experro Admin Panel, go to **Discovery → UI Customization → CSS & JS**. * In the **JavaScript (JS) Editor** section, enter: ```js theme={null} window["Experro"].BeforeInit(` window["Experro"].SetConfig({ "is_live": true }) `); ``` </Step> <Step title="Save Your Theme Settings"> * Click **Save** at the top right to persist your changes in Shopify. </Step> <Step title="Publish Your Theme"> * Navigate to **Themes**, find **Experro Default Theme** if not already selected , and click **Publish**. * Confirm when prompted. Your updated theme, complete with Experro Discovery UI, is now live. </Step> </Steps> By following these steps, you’ll have a fully integrated, plug‑and‑play connection between your Shopify storefront and Experro Discovery—empowering you to deliver a world‑class discovery experience from day one. # UI Customisation Source: https://help.experro.com/plug_and_play/shopify_integration/ui_customisation ## Customise your UI Once connected, you can head over to our [UI Customization guide](/plug_and_play/ui_customisation/overview) to design your discovery interface. # Autocomplete Source: https://help.experro.com/plug_and_play/ui_customisation/autocomplete ## Autocomplete Settings The Autocomplete module lets you fine‑tune every aspect of how search suggestions and product previews appear as users type in your search bar. You can configure the trigger threshold, choose from multiple layout templates, control which suggestion blocks are shown (products, search terms, categories, content pages), and define mobile‑specific behaviors—all from one unified interface. ### 1. Enabling Autocomplete * **Toggle On/Off**\ Enable or disable Autocomplete globally for desktop and mobile views. * **Trigger Threshold**\ Specify how many characters a user must type before suggestions appear (options: 2, 3, 4, or 5; default: 3). ### 2. Popover Layout Choose the visual arrangement of suggestion blocks: | Layout | Description | | ---------------------- | --------------------------------------------------------------------------- | | **Vertical** (default) | Suggestions list vertically on the left; product previews on the right. | | **Horizontal** | Search terms, categories, and content appear above; product previews below. | | **Minimalistic** | A compact list combining all suggestion types. | *** ### 3. Product Card Layout #### View Mode * **Grid View** (default)\ Displays product thumbnails in a multi‑column grid. * **List View**\ Shows products in a single column with extended details. #### Attributes to Show Select which fields appear on each product card. At least one is required; defaults are **Image**, **Name**, and **Price**. Additional options include: * SKU * Brand * Short Description * Rating * Inventory Level Drag‑and‑drop to reorder, or remove attributes with a single click. ### 4. Suggestion Blocks Enable, disable, and configure each block of the Autocomplete dropdown: | Block | Toggle | Count (1–20) | Additional Options | | ---------------------------- | :----: | :----------: | ------------------------------- | | **Product Suggestions** | ✔️ | Default 5 | Show product count | | **Search Term Suggestions** | ✔️ | Default 5 | Highlight matching text | | **Category Suggestions** | ✔️ | Default 5 | Show product count per category | | **Content/Page Suggestions** | ✔️ | Disabled | — | Use drag‑and‑drop in the “Search Result Order” panel to change the vertical ordering of these blocks. ### 5. Quick‑Click Suggestions Define what appears when users click into the search box **before** typing: * **Popular Searches**\ Show most‑searched terms (count configurable 1–20; default 5). * **Recent Searches**\ Display the user’s own recent queries (configurable 1–20; default 5). * **Search Product Recommendations**\ If no input, show a pre‑built recommendation widget or custom product list when user clicks on the search box. ### 6. No‑Results Handling * **Custom No‑Results Message**\ Enter the custom message; include `<%= searchTerm %>` to dynamically insert the user’s query. * **Fallback Recommendations**\ Toggle on to display a recommendation widget titled by you; toggle off for no suggestions. ### 7. Mobile View Overrides All of the above settings can be overridden for mobile: * **Layout**: Choose between **Horizontal** or **Minimalistic** layouts. * **Block Order & Visibility**: Enable or disable blocks independently from desktop. * **Trigger Threshold**: Optionally set a higher or lower character count for mobile. Use the **Desktop/Mobile** tabs at the top of the Autocomplete page to switch contexts. By tailoring these Autocomplete settings, you’ll deliver faster, more relevant suggestions that guide shoppers to the right products with fewer keystrokes—driving engagement and conversions. # Custom CSS & JS Source: https://help.experro.com/plug_and_play/ui_customisation/css_and_js The Custom **CSS & JS** tab in Experro's UI Customization panel provides a straightforward interface for injecting custom styles and scripts into your storefront. This feature is particularly useful for developers and designers aiming to implement specific design tweaks or interactive functionalities that go beyond the default customization options. <img alt="" /> ### Key Features * **Visual Editor Access**: Utilize the built-in visual editor to write and manage your custom CSS and JavaScript code. This editor offers syntax highlighting and a user-friendly interface to streamline the coding process. * **Global Application**: Any code added here will be applied globally across your storefront, ensuring consistent styling and behavior throughout your site. * **Enhanced Customization**: Tailor your storefront's appearance and functionality to match your brand's unique requirements, enabling a more personalized shopping experience for your customers. ### Usage Guidelines * **CSS Customization**: Apply custom styles to elements by targeting specific classes or IDs. This allows for precise control over the visual aspects of your storefront, such as colors, fonts, spacing, and layout adjustments. * **JavaScript Enhancements**: Introduce interactive elements or modify existing behaviors by writing custom JavaScript. This can include features like dynamic content updates, event handling, or integrating third-party libraries. * **Best Practices**: Ensure that your custom code is well-structured and does not conflict with existing scripts or styles. It's advisable to test your code in a staging environment before deploying it to your live storefront. By leveraging the Custom CSS & JS tab, you can achieve a higher level of customization, allowing your storefront to stand out and provide a unique user experience. # Layout Source: https://help.experro.com/plug_and_play/ui_customisation/layout ## Page Layout ### Overview The **Page Layout** setting determines where the facets (filter panels) appear on your category and search results pages. Proper facet placement is crucial for seamless navigation, helping shoppers refine large product lists quickly and intuitively. Experro offers four positioning options—Left, Right, Top, and None—so you can tailor the layout to match your storefront’s design and your customers’ browsing habits. You can individually configure layout settings for both **Desktop View** and **Mobile View**, allowing you to tailor the experience based on how users access your store. ### Facets Position Options #### Left (Default) * **Description:** Displays facets in a fixed sidebar on the left side of the page. * **Use Case:** Ideal for most desktop e‑commerce sites where users expect traditional left‑hand filters. This layout keeps filters immediately visible without obscuring product listings. #### Right * **Description:** Moves the filter sidebar to the right side of the page. * **Use Case:** Useful when your site’s primary navigation or promotional banners occupy the left margin, or when you want to create a more balanced visual flow with facets on the opposite side. #### Top * **Description:** Renders facets in a horizontal bar above the product grid. Filters stack or scroll horizontally, depending on screen width. * **Use Case:** Excellent for mobile‑first or narrow‑width designs where vertical space is at a premium. Keeps filtering options within thumb reach without requiring a sidebar. #### None * **Description:** Hides facets entirely from the category and search pages. * **Use Case:** Best for minimalistic layouts, single‑product collections, or curated stores where filtering is unnecessary. Eliminates visual clutter when there are very few items to browse. #### Custom * **Description:** Allows for a fully customized facet layout. Enables users to define unique placements tailored to their store’s design and functionality needs. Contact the Experro Support Team to create your custom layout. * **Use Case:** Best for brands with unique UI/UX requirements, such as personalized shopping experiences or interactive product discovery pages. An example would be a store that integrates AI-driven recommendations alongside custom filtering. ### How to Configure Facets Position 1. **Navigate to UI Customization**\ In the Experro Admin Panel, go to **Discovery → Store Integration → UI Customization**. 2. **Locate Page Layout Section**\ Scroll to the **Page Layout** section where “Facets Position” is displayed. 3. **Select Desired Position**\ Click the radio button next to **Left**, **Right**, **Top**, or **None** to choose your layout. 4. **Save Your Changes**\ After selecting, click **Save** at the bottom of the panel. Your storefront will update immediately to reflect the new facet placement. 5. **Preview & Publish**\ — Use the preview environment to verify the layout on both desktop and mobile. — When satisfied, publish to your live store so customers experience the updated design. ### Best Practices * **Match Your Theme:** Ensure facet placement complements your overall page structure—e.g., if your main menu is on the left, consider moving facets to the right. * **Mobile Considerations:** For mobile-heavy traffic, the **Top** position often provides the most ergonomic filtering experience. * **Test User Flows:** After changing layouts, run quick usability tests (or review analytics) to confirm users still find and use filters as intended. * **Iterate Based on Data:** Leverage Experro’s Analytics dashboards to see how facet location impacts engagement metrics (e.g., filter clicks, conversion rate) and adjust accordingly. ## Product Grid Layout The **Product Grid Layout** settings let you control how products display on your category and search results pages—across both grid and list views, pagination behavior, and product counts. By tailoring these options, you can balance visual appeal, performance, and usability to suit your catalog size and customer browsing habits. <img alt="" /> ### 1. Default Listing View Choose how products initially render when a shopper lands on a product listing. * **Grid View (Default)**\ Products display in a multi‑column grid, maximizing the use of horizontal space and emphasizing imagery. Ideal for visually‑driven categories (fashion, home décor) where thumbnails are key to engagement. * **List View**\ Products display in a single‑column list with expanded details (descriptions, specifications, ratings). Perfect for comparison‑heavy categories (electronics, B2B) where text and data drive purchase decisions. ### 2. Number of Products per Grid Row Control how many products appear side‑by‑side in **Grid View**: | Products per Row | When to Use | | ---------------- | -------------------------------------------- | | **1–2** | Showcase large images or high‑end products. | | **3** (Default) | Balanced view—good for most catalogs. | | **4–5** | Enable rapid browsing for large inventories. | Adjust this setting to optimize for image size, whitespace, and overall page length. ### 3. Pagination Style Determine how additional products load as users explore your catalog: * **Show Pages**\ Displays numbered page links at the bottom. Shoppers can jump to any page—ideal for large catalogs where specific navigation matters. * **Infinite Scroll**\ Loads more products automatically (or via a “Load More” button) as the user scrolls. Encourages continuous browsing, especially suited for mobile or social‑style shopping experiences. ### 4. Number of Products per Page Set the total number of items fetched on each pagination or scroll event: * **Range:** Choose any value (e.g., 12, 24, 48, 100) to balance load time and page length. * **Default:** 24 products per page. Higher counts reduce pagination clicks but may impact performance on slower connections. ### 5. Show Product Count Toggle the display of the total product count at the top and/or bottom of the listing (e.g., “1,234 Products”): * **Enabled (Default):** Provides shoppers with context on catalog size. * **Disabled:** Delivers a cleaner layout for minimalistic or curated collections. ### How to Configure 1. **Access Layout Settings**\ Navigate in the Experro Admin Panel to **Discovery → Store Integration → UI Customization → Layout**. 2. **Select Your Options** * Under **Default Listing View**, choose **Grid** or **List**. * Adjust **Products per Grid Row** via the dropdown. * Choose **Pagination Style**: **Show Pages** or **Infinite Scroll**. * Enter your desired **Products per Page**. * Toggle **Show Product Count** on or off. 3. **Save & Preview**\ Click **Save** to apply changes, then preview on both desktop and mobile to ensure the layout meets your design and performance goals. 4. **Publish to Live**\ When satisfied, publish your customizations so shoppers experience the updated layout immediately. ### Best Practices * **Test Across Devices:** Verify grid density and pagination on desktop, tablet, and mobile. * **Monitor Performance:** Use Experro’s Analytics to track page load times and abandon rates after layout changes. * **Offer Choice:** Consider enabling view toggles so shoppers can switch between grid and list. * **Iterate Based on Data:** Adjust “Products per Page” and pagination style based on session length and conversion metrics. ## Product Card Layout The **Product Card Layout** settings enable you to tailor how individual products appear in your grid or list views. You can choose between Experro’s built‑in template or build a fully custom card, then configure which attributes, buttons, and badges are shown. This ensures each product card aligns with your brand’s visual identity and functional requirements. <img alt="" /> ### 1. Template Selection **Use Default Template** * Applies Experro’s standard card design, optimized for clarity and performance. * Includes responsive styling, hover effects, and built‑in support for badges and action buttons. **Create Custom Template** * Opens Experro’s built‑in code editor where you can modify the HTML/EJS structure. * Starts from the default template, so you only need to tweak specific elements. * **Warning:** Switching back to the default will discard all custom code changes. ### 2. Visible Product Attributes Select which product fields appear on each card. Drag to reorder; click the trash icon to remove. | Attribute | Description | | ----------------------- | ------------------------------------------------------------------------ | | **Product Image** | Mandatory: displays the main product thumbnail. | | **Product Name** | Shows the title. | | **Price** | Displays list and sale prices (follows your storefront’s pricing rules). | | **SKU** | Shows the stock‑keeping unit for inventory tracking. | | **Brand** | Displays manufacturer or brand name. | | **Description Summary** | Brief excerpt (Grid: 50 chars; List: 250 chars) to provide context. | | **Rating** | Shows average rating from your review system. | | **Inventory Level** | Displays “In Stock” or available quantity. | *** ### 3. Action Buttons Enable or disable interactive buttons to drive conversions directly from the card. * **Image Rollover**\ On hover, swaps to a secondary image (if available) to showcase alternate views. * **Add to Cart** * **Button Text:** Customize the label (e.g., “Add to Bag”). * **Button Image:** Upload a graphic instead of text. * **Quantity Selector:** Show an input field so customers choose quantity before adding. * **Choose Options**\ (for products with variants) * **Button Text:** e.g., “Select Size.” * **Button Image:** Use an icon or custom image. ### 4. Badges & Overlays Highlight special product statuses directly on the card. * **On Sale Badge**\ Automatically appears when a product has a discounted price. * **Custom Badge**\ Enter a badge label (e.g., “New Arrival,” “Limited Edition”). Upload a badge icon or background if desired (PNG, JPG, SVG, GIF; ≤ 2 MB). ### 5. Default Thumbnail If a product lacks an image, a fallback thumbnail ensures visual consistency. * **Upload Format:** PNG, JPG, SVG, or GIF (max 2 MB) * **Usage:** Applied automatically to any product missing media. ### 6. Require Sign‑In to View Prices Toggle on to hide prices for anonymous visitors and prompt sign‑in. * **Behavior:** * Unauthenticated users see a “Sign In to View Price” link. * Clicking redirects to your storefront’s login page. ### 7. Price Rounding Define how prices round on the product card (e.g., to nearest whole dollar, .99 endings). ### How to Configure 1. In the Experro Admin, go to **Discovery → Store Integration → UI Customization → Layout → Product Card Layout**. 2. **Template**: Select **Use Default** or **Create Custom**. 3. **Attributes**: Check boxes for each field you wish to display; drag to reorder. 4. **Buttons**: Expand **Configure Action Buttons**, toggle on desired buttons, and customize text/icons. 5. **Badges**: Enable On Sale or enter a Custom Badge label and upload an icon. 6. **Default Thumbnail**: Click **Upload**, select your fallback image, and save. 7. **Require Sign‑In**: Toggle the switch on/off. 8. **Price Rounding**: Choose your rounding convention from the dropdown. 9. Click **Save**, then **Publish** your changes to deploy to your live storefront. ### Best Practices * **Keep It Clear:** Only display the most essential attributes to avoid overcrowding the card. * **Drive Action:** Position the primary action button prominently—use contrasting colors for “Add to Cart.” * **Maintain Consistency:** Ensure your custom template’s typography and spacing match your overall theme. * **Test Variants:** If using Image Rollover or Choose Options, verify that variant images and option links work as intended. * **Monitor Performance:** Use Experro Analytics to track click‑through rates on buttons and refine your layout based on real user behavior. ## Sort Options ### Overview Sort Options let you control the order in which products appear on category and search result pages. By offering both system‑defined and custom sorting methods, you ensure shoppers can organize product listings in ways that match their needs—whether that’s seeing newest arrivals first, browsing budget‑friendly items, or applying your own business‑specific ranking logic. <img alt="" /> ### System‑Defined Sorting Options These are built‑in sort modes you can toggle on or off. When enabled, they appear in the storefront’s sort dropdown: * **Relevance (Default):** Ranks products by how closely they match the user’s search terms or selected category. * **Featured Items:** Surfaces products you’ve explicitly marked as “featured,” perfect for highlighting promotions or best‑sellers. * **Price: Low → High:** Shows the most affordable items first, useful for budget‑conscious shoppers. * **Price: High → Low:** Puts premium or high‑value items at the top, ideal for premium or luxury catalogs. * **Newest Items:** Displays the latest additions first—great for fast‑fashion or frequently updated catalogs. * **Oldest Items:** Surfaces legacy or clearance stock first, handy when you need to clear out older inventory. ### Custom Sorting Fields Beyond the standard options, you can define your own sort criteria based on any product attribute: 1. **Display Name:** The label your customers see in the sort dropdown (e.g., “Sort by Rating”). 2. **Field:** The catalog field to sort on (e.g., `rating`, `inventory_level`, `carat_weight`). 3. **Sort Order:** Choose **Ascending** (ASC) or **Descending** (DESC). Custom sorts let you tailor the browsing experience—for example, sorting by customer reviews, stock levels, or any specialized attribute you’ve added to your catalog. ### Configuration Guide 1. **Navigate to Sort Options**\ In the Experro Admin Panel, go to **Discovery → UI Customization → Sort Options**. 2. **Enable/Disable System Sorts**\ Use the toggles beside each built‑in option (Relevance, Featured, Price, etc.) to include or hide them in the storefront. 3. **Add a Custom Sort** * Click **+ Add Field** beneath the Custom section. * Enter the **Display Name**, select the **Field**, and choose **ASC** or **DESC**. * Click **Save** to make it available to customers. 4. **Set the Default Sort**\ Choose which sorting method appears first when a user lands on a category or search page. 5. **Preview & Publish**\ Switch between desktop and mobile views in the preview pane to confirm your sort dropdown looks and behaves correctly. Then click **Publish** to apply changes live. ### Best Practices * **Keep It Focused:** Offer only the most relevant sorts—too many options can overwhelm shoppers. * **Clear Labels:** Use customer‑friendly names (e.g., “Price: Low → High” rather than “price\_asc”). * **Logical Order:** Place the most commonly used sorts (Relevance, Featured, Price) at the top of the dropdown. * **Test Regularly:** Track which sorts customers use most via analytics, and refine your available options over time. * **Performance Considerations:** Ensure that custom sorts on large datasets remain responsive; consider server‑side indexing or caching for heavy fields. By thoughtfully configuring and labeling your sort options, you empower shoppers to quickly zero in on the products they want—driving engagement, reducing frustration, and boosting conversions. # Overview Source: https://help.experro.com/plug_and_play/ui_customisation/overview The UI Customization page in Experro Discovery provides a centralized, visual interface for tailoring every aspect of your storefront’s look and feel—without touching your live theme code. From selecting a cohesive theme to fine‑tuning layout and behavior for both desktop and mobile, this page empowers you to align Experro’s search, merchandising, and recommendation components with your brand’s unique style and UX requirements. On this page you will find six main configuration panels: 1. **Theme**\ Quickly switch between predefined themes, preview them in context, and apply your favorite to ensure a consistent design language across search bars, autocomplete popovers, and recommendation widgets. 2. **Layout**\ Control the placement and presentation of facets, product grids, pagination, and product counts—independently for desktop and mobile—so shoppers enjoy an intuitive browsing experience on any device. 3. **Search Results**\ Override your global layout and display settings specifically for search result pages. Choose distinct grid or list views, sorting options, no‑results messages, and fallback recommendations to optimize every search journey. 4. **Autocomplete**\ Configure the behavior and appearance of real‑time suggestions. Select popover layouts, decide which blocks appear (terms, products, categories, etc.), and customize the look of autocomplete product cards to guide users instantly toward relevant results. 5. **CSS & JS**\ Inject custom styles or scripts directly into Experro’s components via a built‑in editor. Use this panel to make pixel‑perfect adjustments or add interactive behaviors without modifying your storefront’s core assets. 6. **Translations**\ Localize every UI label by overriding default text keys. Support multiple languages, search and filter translation keys, and preview changes in real time—ensuring your store speaks your customers’ language. Together, these controls give you complete ownership over how Experro’s powerful discovery features integrate visually and functionally into your storefront, enabling a seamless, on‑brand shopping experience for your customers. # Search Results Source: https://help.experro.com/plug_and_play/ui_customisation/search_results ## Search Results Customization The **Search Results** tab in UI Customization lets you tailor every aspect of how search results appear to your customers—on both desktop and mobile. While general layout and display settings apply by default, here you can override them specifically for search results, ensuring that product listings, filtering, sorting, and messaging align perfectly with your brand and user experience goals. ### Device View Selection At the top of the page, use the **Desktop View** and **Mobile View** toggles to switch between device-specific settings. This ensures your search results are optimized for different screen sizes: * **Desktop View:** Configure wider layouts, multi‑column grids, and detailed product cards. * **Mobile View:** Enable compact layouts, single‑column grids, and streamlined cards for touch navigation. ### Overriding Default Settings By default, the search results page inherits the **Layout**, **Grid**, **Card**, and **Sort** configurations defined in the general **UI Customization → Layout** tab. To customize search results independently: 1. Toogle **Use different page layout for search results** 2. Toggle **Use different product grid layout for search results** 3. Toggle **Use different product card layout for search results** 4. Toggle **Use different sort options for search results** <img alt="" /> Once enabled, each section below becomes configurable for search results only. ### Search Result Settings **Purpose:** Configure core search page behaviors. * **Show Search Box:** Toggle visibility of the search input on the results page. * **Show Content Pages:** Include content pages (e.g., FAQs) alongside product results. * **Search Result Page URL:** Set or override the URL slug by creating a custom page in BigCommerce and link the URL here (default: `/search-results/`). <img alt="" /> <Tip> Keeping the search box visible encourages users to refine their queries on the fly.</Tip> ### No Results Settings **Purpose:** Customize messaging and fallback when a search yields zero products. * **No Results Message:** Enter up to 6 words of friendly copy (e.g., “Sorry, no matches for `<%= searchTerm %>`”). * **Dynamic Tag Replacement:** Use the `<%= searchTerm %>` tag to inject the user’s query into your message automatically. <img alt="" /> For Example, “We couldn’t find any ‘\<%= searchTerm %>’. Here are some popular items instead.” ### Recommend Fallback Products **Purpose:** Display alternative or popular products when no exact matches exist. * **Enable Recommendations:** Toggle on to curate a fallback recommendation widget. * **Source Configuration:** Choose the recommendation widget and the title for the recommendation widget. **Outcome:** Keep users engaged by offering relevant alternatives, reducing bounce rates from no‑result searches. # Theme Source: https://help.experro.com/plug_and_play/ui_customisation/theme ## Overview The **Theme** tab in Experro’s UI Customization lets you instantly transform the look and feel of your search, autocomplete, and recommendation components to match your storefront’s branding—no coding required. Select from our curated, mobile‑friendly themes, preview them in context, and apply your choice with a single click. ## Key Features * **Instant Preview**\ View each theme in action across the Category List, Search Results, Autocomplete dropdown, and Recommendations widget before you commit. * **One‑Click Apply**\ Select your preferred theme and hit **Save**—Experro will automatically update all search‑related UI components in your storefront. * **Extensible Library**\ Our backend supports adding new themes or uploading custom theme packages, ensuring you can expand your visual toolkit as your brand evolves. ## Selecting & Previewing a Theme <Steps> <Step title="Open the Theme Tab"> Navigate to **UI Customization → Theme**. </Step> <Step title="Browse Available Themes"> Each theme tile displays a thumbnail and a brief description. </Step> <Step title="Preview in Context"> Click **Preview** to preview the storefront with the selected them in action. </Step> <Step title="Compare Styles"> Select another theme and preview it again to compare the styles until you find the perfect match. <img alt="" /> </Step> </Steps> ## Applying Your Theme <Steps> <Step title="Select Your Theme"> After previewing, click the theme’s radio button to mark it as your choice. </Step> <Step title="Save Your Selection"> Click **Save** at the bottom of the Theme tab to persist your choice in Experro. </Step> <Step title="Publish to Store"> Once styling and any other UI customizations are complete, navigate to **Publish** button and deploy to production. The new theme will replace your previous look across all search‑related elements. </Step> </Steps> Once you’ve configured each tab under **UI Customization**, simply click **Publish** to apply your changes. ## Best Practices * **Brand Consistency**\ Choose a theme whose typography and color accents align with your primary storefront palette to maintain a unified customer experience. * **Preview on Multiple Devices**\ Use Experro’s preview carousel on desktop, tablet, and mobile to confirm responsive layouts before publishing. * **Leverage Custom CSS/JS**\ For fine‑tuned adjustments beyond the theme settings, switch to the **CSS & JS** tab and apply targeted overrides without affecting your core theme. * **Version Control**\ Keep track of which theme you publish and when—this makes it easy to roll back if you need to revert to a previous look. By following these steps, you can effortlessly tailor Experro’s search UI to your brand’s unique style—ensuring a seamless, on‑brand experience from the moment customers begin typing in your search bar. # Translations Source: https://help.experro.com/plug_and_play/ui_customisation/translations ## Translations Tab The Translations tab enables you to localize all static labels within your Experro Discovery UI, ensuring that every shopper sees familiar terminology in their preferred language. You can view, search, and update each translation key directly in the Experro Admin Panel—no code changes required. ### Key Features * **Multi‑Language Support**\ Translate any UI label into one or more store languages. If a translation is left blank, Experro will fall back to the default text. * **Search & Filter**\ Quickly locate specific labels by typing keywords into the search bar. Filter both keys and values in real time. * **Live Preview**\ Changes take effect immediately in the preview pane, so you can verify translations before saving. * **Bulk Save**\ After editing multiple entries, click **Save** once to apply all your translations at once. ### Translation Fields | Key | Description | | ----------------------------------- | ------------------------------------------------------ | | `sidebar_heading_search_suggestion` | Heading for the search suggestion section | | `sidebar_heading_categories` | Heading for the category filter section | | `sidebar_heading_content_pages` | Heading for content pages filter | | `sidebar_heading_recent_search` | Heading for recent search terms | | `sidebar_heading_popular_search` | Heading for popular search terms | | `empty_result_placeholder` | Placeholder text shown in the search box before typing | | `refine_by` | Label for the refine filter section | | `clear_all` | Button label to clear all applied filters | | `load_more` | Button label to load additional items | | `sort_by` | Label for the sort dropdown | | `next` | Label for pagination “Next” | | `prev` | Label for pagination “Previous” | | `on_sale` | Badge label for on‑sale items | | `no_result_message` | Message when no products are found | | `no_result_message_sub` | Subtext when no products are found | | `quick_view` | Button label for quick‑view functionality | | `compare` | Button label for the compare feature | | `wishlist` | Button label for the wishlist feature | | `out_of_stock` | Label for out‑of‑stock products | | `view_all` | Text for “View all X products” | | `pagination_summary` | Summary text for pagination | | `auto_correct_message` | Message suggesting a corrected search term | ### How to Use 1. **Navigate to Translations**\ In the Experro Admin Panel, go to **Discovery → UI Customization → Translations**. 2. **Search for Keys**\ Enter any part of a key or value into the search bar to filter the list. 3. **Edit Values**\ Click into the **Value** column next to each key and enter your translated text. Use placeholders (e.g., `{searchTerm}`) exactly as shown. 4. **Save Changes**\ Once all your edits are complete, click **Save**. All translations will be immediately applied to your storefront. *** ### Best Practices * **Consistency:**\ Use consistent terminology across similar labels to avoid confusing shoppers. * **Placeholders:**\ Do not modify placeholders (e.g., `{total_count}`, `{searchTerm}`), as they are dynamically replaced at runtime. * **Review & Test:**\ Preview your storefront in each language to ensure translations fit within UI constraints and maintain context. * **Fallbacks:**\ Always provide translations for core navigation labels; any missing translations will revert to the default language text. By leveraging the Translations tab, you can deliver a seamless, localized discovery experience that resonates with customers around the globe. # Using Experro Discovery Source: https://help.experro.com/plug_and_play/using_experro_discovery Experro Discovery is the powerful engine behind your storefront's intelligent search, autocomplete, and personalized product recommendations. To learn more about how Discovery works and how you can leverage it to improve user experience and drive conversions, check out our full documentation: Explore [Experro Discovery](/experro_discovery) # FAQs Source: https://help.experro.com/proof_of_value/faq ## Frequently Asked Questions ### Does the Experro pixel / Analytics SDK slow down my site? No. The SDK bundle is small, served from Experro’s CDN, and loaded asynchronously. It hooks into the page via non‑blocking event listeners and streams events in the background, so it doesn’t pause the main thread or delay your page from rendering. ### Can we add the SDK before our full product catalog or models are ready? Yes. You can deploy the SDK at any time. For high‑quality commerce attribution (products, variants, categories, collections), it works best once your catalog and models are wired into the storefront so event payloads contain stable IDs/SKUs. If you only need behavioral tracking (sessions, clicks, custom events), you can start immediately with your tenant, workspace, environment, channel IDs, and `app_key`. ### Who is responsible for wiring events on our site? Experro ships the core tracker and a set of built‑in commerce events. Your team decides **where** in the codebase to call those events (for example, search results pages, PDP templates, cart components). If you’d like help mapping your UX to the SDK, Experro can provide best‑practice guidance and sample implementations. ### How does the SDK know when a user searches or adds to cart? The SDK exposes a queue‑style API (`ExpAnalytics.q.push([...])`). You invoke the appropriate built‑in keys (such as `product_searched`, `product_added_to_cart`, `checkout_completed`) at the right moments in your UI—for example, after search results load, when an item is added to cart, or when an order completes. The SDK then wraps that payload and sends it to your analytics endpoint with your Experro headers (`x-tenant-id`, `x-workspace-id`, `x-env-id`, `x-channel-id`, `x-channel-locale`). ### Which events are available out of the box? Experro covers the full shopper journey: * **Discovery**: `ac_impression`, `ac_click`, `product_searched`, `search_no_results`, `ac_zero_impression` * **Browse & PDP**: `category_viewed`, `collection_viewed`, `widget_viewed`, `product_viewed`, `product_variant_viewed` * **Cart & Checkout**: `product_added_to_cart`, `product_remove_from_cart`, `cart_viewed`, `checkout_initiated`, `checkout_completed` * **Identity**: `auth_events` (`change_id`, `user_details`) * **Custom**: Any `add_event` you define, with your own counts, sums, durations, and segmentation fields. ### Is anything else required beyond adding the script? In most cases, no. You include the script tag and initialize it with your IDs and analytics URL. Additional server‑side work is only needed if your Content Security Policy (CSP) currently blocks Experro’s CDN or your analytics endpoint (see the CSP section below). ### What data is sent from the browser? Do you store PII? Every event contains an anonymous identifier, timestamp, page URL, your Experro context headers (tenant/workspace/env/channel/locale), and the payload you choose to send (SKUs, facets, totals, etc.). IP information is transmitted for transport and security purposes but can be truncated or discarded according to your data policies. We recommend **not** sending raw PII inside `segmentation`; instead, rely on stable user IDs managed through `change_id` and `user_details`. **Example event payload (request body):** ```json theme={null} { "key": "product_searched", "sum": 24, "segmentation": { "search_term": "running shoes", "search_location": "page", "sku": ["RS-001", "RS-002"], "facets": [{"field": "size", "value": "10"}], "currency": "USD" } } ``` ### Do we need different snippets for staging and production? You use the same script bundle in all environments. Environment separation comes from configuration: `envId`/`environmentId`, `analyticsUrl`, and your app key. For testing, point the SDK at a staging base URL and staging environment ID; for go‑live, deploy the same snippet with production values. ### What storage mechanisms does the SDK rely on? By default, the SDK uses local or session storage to maintain identifiers and to buffer events if needed. Cookie usage is optional and can be enabled based on your requirements and policies. ### Should we QA before rolling out to production? Yes. While the core tracker is well tested, it’s important to verify your specific event hooks. Run through key flows—search, product view, add‑to‑cart, checkout—and confirm that events appear in the browser network panel and within your Experro Analytics dashboards as expected. # Load the Analytics SDK Source: https://help.experro.com/proof_of_value/load_sdk We recommend installing the Experro Analytics SDK on all pages that are important for understanding user behavior and commerce performance, and avoiding pages that contain highly sensitive data such as account management or payment details. The most important pages for the SDK to be loaded on are: * Any page with a search bar * Search result pages (PLP) * Browse/collection pages (PLP) * Product detail pages (PDP) * Cart and Checkout pages ### Installation Options You can load the Experro Analytics SDK in two primary ways: <CardGroup> <Card title="Script Injection" icon="code" href="/analytics_sdk/load_sdk_direct"> Recommended for production embed the SDK snippet directly in your storefront templates. </Card> <Card title="Google Tag Manager (GTM)" icon="cube" href="/analytics_sdk/load_sdk_gtm"> Use GTM to manage the SDK as a Custom HTML tag with DOM Ready or All Pages triggers. </Card> </CardGroup> > For most merchants, **Script Injection** provides the most reliable data collection and is less likely to be blocked by ad blockers. *** <Info> For full configuration options and advanced initialization examples, see the **Installation** and **Initialization** guides in the Analytics SDK section. </Info> # Script Injection Source: https://help.experro.com/proof_of_value/load_sdk_direct We recommend installing the Experro Analytics SDK on all pages that are important for understanding user behavior and commerce performance, and avoiding pages that contain highly sensitive data such as account management or payment details. The most important pages for the SDK to be loaded on are: * Any page with a search bar * Search result pages (PLP) * Browse/collection pages (PLP) * Product detail pages (PDP) * Cart and Checkout pages ### Script Injection (recommended) Add the SDK snippet directly to your storefront template, typically just before the closing `</head>` tag: ```html theme={null} <script defer src="https://experro-pov.myexperro.com/experro-analytics-library/CUSTOM_JS_SDK_NAME.js"></script> ``` This method ensures the SDK loads as part of your core storefront experience and is less likely to be blocked by ad blockers. > **Tip:** If you have multiple layouts or templates, ensure the snippet is included in all templates that render key commerce and discovery pages. *** <Info> For other loading options such as Google Tag Manager, see **Load the SDK – Google Tag Manager (GTM)**. </Info> # Google Tag Manager (GTM) Source: https://help.experro.com/proof_of_value/load_sdk_gtm If you prefer not to modify your storefront templates directly, you can load the Experro Analytics SDK via Google Tag Manager (GTM). This is convenient for teams that manage scripts centrally through GTM, though note that tag managers can be blocked by some ad blockers. ### Prerequisites * Access to your site’s GTM container (web) * Your Experro Analytics configuration values (tenant, workspace, environment, channel, etc.) ### Step-by-Step: Install the SDK via GTM 1. **Sign in to GTM**\ Go to [tagmanager.google.com](https://tagmanager.google.com), and open the appropriate **Account** and **Container** (Workspace) for your site. 2. **Create a new Tag** * In the left-hand navigation, click **Tags**. * Click **New** → **Tag Configuration**. * Choose **Custom HTML** as the tag type. 3. **Add the Experro SDK snippet**\ In the **HTML** text area, paste the Experro SDK snippet, for example: ```html theme={null} <script defer src="https://experro-pov.myexperro.com/experro-analytics-library/CUSTOM_JS_SDK_NAME.js"></script> ``` Adjust the configuration values (`YOUR_TENANT_ID`, `YOUR_WORKSPACE_ID`, etc.) to match your environment. 4. **Configure tag advanced options** * Leave **Support document.write** unchecked/blank. * Under **Advanced Settings**, set **Tag firing options** to **Once per page**. * Leave other advanced settings at their defaults. * Give your tag a descriptive name, for example: `Experro Analytics SDK`. 5. **Create a Trigger** * In the left-hand navigation, click **Triggers** → **New**. * Click **Trigger Configuration** and choose **DOM Ready** (or **All Pages** if preferred). * Leave other options as their defaults. * Name the trigger, for example: `Experro SDK – DOM Ready`. 6. **Associate the Tag with the Trigger** * Go back to your **Experro Analytics SDK** tag. * Under **Triggering**, select the trigger you just created (`Experro SDK – DOM Ready`). 7. **Publish the container** * Click **Submit** → add a version description if desired → **Publish**. Once published, GTM will load the Experro Analytics SDK on every page where the trigger conditions are met. > **Note:** Loading the SDK via GTM is convenient but can be affected by ad blockers or script restrictions. For maximum data quality and coverage, Script Injection is still recommended for production environments. *** <Info> For direct installation guidance, see **Load the SDK – Script Injection**. </Info> # Overview Source: https://help.experro.com/proof_of_value/pixel_overview The Experro pixel (Analytics SDK) is a JavaScript snippet added to your website. It captures anonymous clickstream activity such as searches, clicks, page views, and commerce events and sends this data to Experro, where it is de‑identified and used to power Experro’s AI and analytics so shoppers can find the products and content they’re looking for. The pixel is engineered to be lightweight and non‑blocking. It loads asynchronously, relies on event listeners to observe behavior, and does not interfere with the browser’s main thread or your site’s rendering performance. For common questions about behavior, data, and performance, see the **Pixel / Analytics SDK FAQs**. If you have additional questions that aren’t covered there, please reach out to your Experro point of contact. # Experro POV Overview Source: https://help.experro.com/proof_of_value/pov_overview Investing in AI is a high-impact enterprise decision, and leaders need proof not promises before committing. The Experro's Proof of Value was purpose-built to give brands that confidence. Designed by skeptics, for skeptics, it provides a structured, low-risk way to see Experro’s Generative AI Platform deliver measurable outcomes personalized to your products, customers, and business objectives before scaling across your organization. ### Overview The Experro's Proof of Value program is a structured 6-step process designed to demonstrate how Experro's modern platform delivers measurable business impact before full-scale adoption. <img alt="Proof of Value Overview" /> <Steps> <Step title="Scoping & Kick-off"> This phase aligns all stakeholders on objectives, success criteria, and timelines. We define use cases, key KPIs, data requirements, and the scope of the PoV to ensure Experro’s capabilities are evaluated against your specific business goals. </Step> <Step title="Catalog Feed"> Your product catalog is securely ingested into Experro through a one-time feed. This enables Experro’s AI engine to understand your product taxonomy, attributes, pricing, and relationships laying the foundation for intelligent search, personalization, and recommendations. </Step> <Step title="Pixel / SDK Integration"> Experro’s lightweight pixel (SDK) is deployed on your storefront. This integration captures real-time, anonymous shopper behavior such as searches, clicks, and interactions, without disrupting your existing architecture or performance. Our team will prepare the pixel tailored to your site and your team just have to load it. It's less than 30 mins for your team. </Step> <Step title="Signal Collection & AI Tuning"> As behavioral signals flow in, Experro team will configure and tune the platform's algorithms and features to help you evaluate your business objectives. This tuning phase ensures the AI adapts to your customers’ intent, preferences, and browsing patterns for maximum relevance and accuracy. </Step> <Step title="Review"> In this review stage, Experro presents performance insights and results from the PoV. Stakeholders gain visibility into improvements across discovery, engagement, and conversion, along with actionable recommendations. </Step> <Step title="ROI / Business discussion"> The final step translates results into a data-backed business case. Using PoV performance metrics, we quantify projected value and ROI, and align on business priorities and next steps for scaling Experro across your enterprise. </Step> </Steps> ### Why Proof of Value? <AccordionGroup> <Accordion title="📈 Understand Site-Wide Shopper Behavior with Real-Time Intelligence" icon="microscope"> By combining anonymous behavioral data with your catalog, Experro’s AI reveals how shoppers truly interact with your site turning raw signals into actionable insights that improve discovery, engagement, and conversion. </Accordion> <Accordion title="🤖 Decode Shopper Intent Across Interactions and Journeys" icon="lightbulb"> Through a custom-built Experro Analytics dashboard, teams gain clear visibility into shopper intent, interactions, and end-to-end journeys. Interactive analytics allow you to explore anonymous user behavior in real time, dynamically filtered by the business KPIs that matter most—such as Revenue per Visitor (RPV), Average Order Value (AOV), Conversion Rate, and more. Across the Experro Analytics experience, AI-powered insights highlight what’s working, uncover friction points and “dead-ends,” and reveal opportunities to optimize discovery and engagement. Experro also provides transparency into how its AI makes decisions—explaining how models continuously learn and self-optimize to improve performance against your most critical eCommerce KPIs. </Accordion> <Accordion title="📈 Confirm Experro's Value" icon="chart-mixed"> Once sufficient high-quality behavioral data is collected during The Proof of Value, Experro translates insights into a clear, data-backed business case. This analysis outlines the projected performance lifts and measurable value you can expect when Experro Analytics is fully deployed—giving stakeholders confidence in the ROI before scaling across your site. </Accordion> <Accordion title="🌟 Join Leading Brands Driving Smarter Commerce" icon="star"> Join innovative, market-leading brands across eCommerce, SaaS, and digital platforms that have validated Experro’s impact through The Proof of Value. These organizations partner with Experro to confidently prove ROI, unlock deeper customer insights, and deploy AI-driven search, personalization, and analytics that strengthen business performance. By leveraging real shopper data and measurable outcomes, they deliver more relevant, seamless, and customer-centric experiences at scale. </Accordion> </AccordionGroup> ### What Effort Does It Require? #### Fewer Than 30 Minutes on Your End * Upload a one-time data catalog directly to Experro (sub 20 min). * Load SDK script on your production website (sub 10 min). #### Everything Else Is Handled by Experro We have a team of engineers that are focused on building The Proof of Value for you. Our engineers & data scientists apply their years of experience to: * Ingest your data catalog into our systems. * Build tracking scripts to collect anonymous clickstream data, tailored to your current UX. * Monitor the quality of clickstream data collected by the SDK, fine-tuning your custom SDK to gather the most accurate behavioral data possible to suit your needs. * Feed this data catalog & clickstream data into Experro's analytics pipelines to generate insights & optimized reports for you. * Spin up a custom UI to emulate your production site but powered by Experro Analytics to clearly identify how we can help improve your user understanding and analytics experience. ### What Is the Timeline? The standard Proof of Value takes **3 to 4 weeks**, with less than 30 minutes of effort needed on your end. *** # Create widget Source: https://help.experro.com/theme-development/create-custom-widget/create-widget # How to create a widget #### What is widget? When you open Experro Visual Builder, you'll notice a side panel on the right sidebar labeled "Basic Components", "Theme Components", etc. Within each section, you'll find various icons representing widgets. These widgets can be dragged and dropped onto the page. Once a widget is dropped, the associated component will be rendered on the page. <img alt="image-1.png" /> #### How can you create a Widget? To create a widegt you can follow the below steps, Follow the bellow directory structure in `base-theme`. ```txt theme={null} src └── components ├── cms-library └── index.ts ├── widgets └── index.ts └── index.ts ``` ##### Step 1: Create a component folder in `cms-library`.\ e.g, The folder named `exp-test-component` contains three files: 1. `index.ts`: This file serves as an entry point for the component. 2. `exp-test-component.tsx`: Responsible for returning the component's JSX. 3. `exp-test-component-controller.tsx`: Implements all the business logic of the component. This includes tasks such as fetching data through API calls and manipulating the data that will be rendered by the component. ##### Step 2: Add an entry for the newly created component to the `index.ts` file located in the `components` folder. You will understand how to do this by examining the contents of the `index.ts` file. ##### Step 3: Create a new file in the Widget folder that will be responsible for displaying the `widget` on the Visual Builder's side panel. ##### Step 4: * To view the widget, you need to register the newly created widget file in the `index.ts` file of the widget folder. * In the `index.ts` file within the widget folder, you will notice that all existing widgets are imported, and their files are added to a `widget` named array. This process ensures that your newly created widget becomes visible on the side panel of the Visual Builder. After following the aforementioned steps, you will be able to adhere to the structure outlined below. ```txt theme={null} src └── components ├── cms-library ├── exp-test-component ├── exp-test-component.tsx ├── exp-test-component-controller.tsx └── index.ts ├── widgets ├── exp-test-component.tsx └── index.ts └── index.ts ``` ##### Let's take a look at the content of newly created component, `exp-test-component.tsx` ```js theme={null} /** * Renders an exp-test-component component. * @param props - Components props. * @returns */ const ExpTestComponent = (props: any) => { const { id, component_content, } = props; return ( <div> // ...components JSX </div> ); }; export default ExpTestComponent; ``` `index.ts` ```js theme={null} import ExpTestComponent from './exp-test-component'; export { ExpTestComponent }; ``` `components > index.ts` ```js theme={null} // ...existing components imports import { ExpTestComponent } from './exp-test-component'; const components = [ //...existing components, ExpTestComponent, ] export default components; ``` ##### Now let's checkout the `widget` file, ```txt theme={null} ├── widgets ├── exp-test-component.tsx └── index.ts ``` `exp-test-component.tsx` ```js theme={null} import { Widget } from 'experro-storefront'; import { ExpTestComponent } from '../cms-library/exp-test-component'; const initialValue: any = { contentModel: '', traitConfig: [] }; const ExpTestComponentWidget = Widget.createWidget({ component: ExpTestComponent, label: '<div class="gjs-fonts gjs-f-b1 custom-widget brand-logo">Test Component</div>', category: 'Theme Components', content: '<ExpTestComponent data-cms-widget="true"/>', widgetName: 'ExpTestComponent', widgetProperties: { defaults: { name: 'Test Component', attributes: { component_content: JSON.stringify(initialValue), }, activeOnRender: true, traits: [ { type: 'experro-storefront', name: 'component_content', }, ], }, }, }); export default ExpTestComponentWidget; ``` > #### Changes to Be Verified > > To associate a component with the widget, follow the steps outlined in the code snippet above, where the component is imported as `ExpTestComponent`. > > Ensure that you pass the same component, unchanged, to the `Widget.createWidget()` object. For the `component` key of that object, simply assign the component. In the `content` key, provide the value as `<ExpTestComponent data-cms-widget="true"/>`, but be sure to update the line according to the name of your new component. > > Similarly, provide the name of the component to the `widgetName` key. > > Review all the changes in the code snippet provided above. `widgets > index.ts` ```js theme={null} // ...existing widgets imported import ExpTestComponentWidget from './exp-test-component.tsx'; const widgets = []; // ...existing widgets pused in to widgets array widgets.push(ExpTestComponentWidget); export default { widgets }; ``` This process enables you to create a new custom widget within the Experro Storefront Base Theme. Now that we understand what a widget is and how to create it, let's explore [What traits?](./what-is-trait) are present within the widget. # Get model internal name Source: https://help.experro.com/theme-development/create-custom-widget/get-model-internal-name # How to get the Internal Name (Content Model Internal Name) ? #### Step 1: Sign in to your Experro admin panel using the provided credentials, then access the workspace you are assigned to. #### Step 2: Choose the **Content Model** option from the side panel. <img alt="image-5.png" /> #### Step 3: Upon selecting the **Content Model** option, you'll see two accordions: one labeled *Models* and the other labeled *Components*. From here, choose a **Model** for which you want to retrieve the **Internal Name**. <img alt="image-6.png" /> #### Step 4: Click on the *Edit* option, which will open a pop-up displaying information about the *Content Model*. Within this pop-up, you'll find a field labeled **Internal Name**, and its value represents your **Content Model's Internal Name**. <img alt="image-7.png" /> You can provide this Internal Name to the Widget's configuration to retrieve data of a **Content Model's** record or records. Alternatively, you can utilize this internal name to access the data of the Content Model's records. # How to use traits Source: https://help.experro.com/theme-development/create-custom-widget/how-to-use-traits Using traits is as straightforward as providing a JSON configuration to the `initialValue` object in the widget file. Firstly, it's essential to understand the `initialValue` object and its fields, along with how they are specified and assigned values. In each widget file, you will encounter the `initialValue` object, which is necessary and should be assigned to the `widgetProperties` in `Widget.createWidget()`. In this object, you will find the `default` key, where you need to pass the `initialValue` object as a stringified value within the `attribute` key. This setup allows you to access the value in the props of the integrated component of the widget. #### Trait's Types <Info> If you're interested in exploring various types of traits, feel free to check out the document titled ["Types Of Available Traits"](./types-of-traits). </Info> Here's how you can implement this in the code snippet below. ```js theme={null} const initialValue: any = { //... traitConfig: [], }; const ExpTestWidget = Widget.createWidget({ component: ExpTestComponent, label: "<div class='gjs-fonts gjs-f-b1 custom-widget link-section'>Link</div>", category: "Basic Components", content: "<ExpTestComponent/>", widgetName: "ExpTestComponent", widgetProperties: { defaults: { name: "Link", attributes: { component_content: JSON.stringify(initialValue), }, activeOnRender: true, traits: [ { type: "experro-storefront", name: "component_content", }, ], }, }, }); ``` <Warning> You have to pass `component_content`, **Where `component_content` is a reserved keyword for the experro-storefront,** and that key will be accessible in the component's props. However, ensure consistency by using the same key on both sides: the key you pass in the widget file's attribute should be accessed with the same key in the component's props.</Warning> *** <Info>Before diving into understanding the configuration of traits, if you wish to explore the available trait types, you can refer to the documentation titled "Available Traits and Their Types." This documentation provides comprehensive information about the traits that are available and the types they belong to.</Info> *** Let's comprehend this concept with the example of the existing `cta-layout-1.tsx` widget in the `base-theme`. <img alt="image-2.png" /> As observed, the `cta-banner` widget incorporates multiple traits such as selecting the 'Data Source' via a `Drop Down`, a trait for 'Show Heading' represented by a `checkbox`, 'Heading Text' which is a `text` input, 'Heading color' trait offered through a `color-picker`, and several `Widget` file. To enable these traits to appear on the `CTA Banner` or any other `Widget's` side panel, you must specify the configuration for each trait in the widget file of the `Widget` file. Here is a `initialValue` object of `CTA Banner`, ```js theme={null} const [OR, AND] = ["OR", "AND"]; const [WIDGET_CHECK_TRUE, WIDGET_CHECK_FALSE] = ["on", "off"]; const [CONTENT_LIBRARY, FREE_FORM] = ["contentLibrary", "freeForm"]; const initialValue: any = { contentModel: "", headingText: "", dataSource: FREE_FORM, modelInternalName: "cta_banner", showHeadingText: WIDGET_CHECK_TRUE, contentPosition: "justify-left", preLoadImage: WIDGET_CHECK_FALSE, headingColor: "#191919", traitConfig: [ { type: "exp_dataSourceDropDown", }, { type: "exp_contentModalPopUp", modelInternalName: "cta_banner", dependent: "dataSource", subDependency: CONTENT_LIBRARY, }, { type: "exp_checkbox", displayName: "Show Heading", internalName: "showHeadingText", }, { type: "exp_text", displayName: "Heading Text", internalName: "headingText", dependencyConfig: { config: [ { name: "showHeadingText", value: [WIDGET_CHECK_TRUE], }, { name: "dataSource", value: [FREE_FORM], }, ], operator: AND, }, }, { type: "exp_colorPicker", displayName: "Heading Color", internalName: "headingColor", dependent: "showHeadingText", subDependency: WIDGET_CHECK_TRUE, }, { type: "exp_dropDown", displayName: "Content Position", internalName: "contentPosition", options: [ { name: "Left", value: "justify-left" }, { name: "Center", value: "justify-center" }, { name: "Right", value: "justify-right" }, ], dependencyConfig: { config: [ { name: "showTagLine", value: [WIDGET_CHECK_TRUE], }, { name: "showHeadingText", value: [WIDGET_CHECK_TRUE], }, ], operator: OR, }, }, { type: "exp_checkbox", displayName: "Pre Load Image", internalName: "preLoadImage", dependent: "dataSource", subDependency: CONTENT_LIBRARY, }, { type: "exp_imageSelector", displayName: "Background Image", internalName: "backgroundImage", dependent: "dataSource", subDependency: FREE_FORM, }, ], }; ``` The `initialValue` object shows how traits are configured. Each object in the `traitConfig` array represents a trait visible on the side panel. It's important to understand terms like `dependent`, `subDependency`, and `dependencyConfig`, and know when to use them based on your needs. This understanding is key to setting up traits effectively. ##### What is internalName? All the trait values will be accessible in the components `props` and `comonent_content` as well. You can access the trait values using the key you specified in the trait object as the 'internalName'. Where it is must to provide the 'internalName' for each trait exapt some trait type which are already metioned in ###Available trait types. For example, `internalName: "showHeadingText",` `internalName: "preLoadImage"`. ##### What is displayName? The value you provide for the 'displayName' key in the trait object will be displayed as the **label** of the trait on the side panel. This label serves as a descriptive title for the trait, helping users understand its purpose or function. *** Let's go through each object provided in the `traitConfig`. ```js theme={null} { type: "exp_dataSourceDropDown", }, ``` This is a custom trait type provided by the `experro-storefront`. To use it, you only need to specify the `type` in the `traitConfig` object, as shown in the `initialValue` object above. This trait provides a dropdown with two values to select from: "**Content Library**" and "**Free Form**". The selected value will be available in the `dataSource` key, which is predefined. *** Alright, let's examine the second trait object, `exp_contentModalPopUp`. ```js theme={null} { type: "exp_contentModalPopUp", modelInternalName: "cta_banner", dependent: "dataSource", subDependency: CONTENT_LIBRARY, }, ``` This trait displays two fields on the side panel. The first field is labeled '**Content Model**', showing the name of the Content Model. The second field is labeled '**Content Model Record**'. When clicked, it opens a `pop-up` listing all the records associated with that Content Model in Experro's admin panel. <img alt="image-3.png" /> As depicted in the image above, the '**Content Model**' field is displaying '**CTA Banner**'. To integrate it with another Content Model, simply provide the '*Internal Name*' of the desired Content Model, which you can obtain from Experro's admin panel. Pass this Internal Name as the value for the 'modelInternalName' key in the object above. <Alert>If you're unsure about where to find the **Internal Name**, you can refer to the guide on how to obtain the Internal Name. You can find it in the section titled ['How to get the Internal Name'](./Get-model-internal-name.md/#how-to-get-the-internal-name-content-model-internal-name).</Alert> For example: `modelInternalName: 'zig-zag-banner'` An important aspect to note is that after selecting a record from the pop-up, the details of the selected 'Content Library Record' will be available under the key '**contentModel**'. You can access this data in props by destructuring '*component\_content*' and accessing the key "**contentModel**". From the records data, you can retrieve the actual record data by making an API call. You'll need to pass the data obtained in '**contentModel**' as parameters for the API call. Next, you can see the key provided is '**dependent**' and '**subDependency**'. #### What is *dependent* & *subDependency*? 1. **dependent:** ```txt theme={null} In the CTA Banner widget, it's necessary for this trait to be visible on the sidepanel only when a 'dataSource' is selected. For instance, if the 'dataSource' trait has a selected value, then this trait will become visible on the side panel. Although we used the 'dataSource' trait as an example, you can and should provide any other valid trait '*internalName*'. From the provided `traitConfig`, examples could include '*showHeading*', '*headingText*', and so on. ``` 2. **subDependency:** ```txt theme={null} This is an enhancement built upon the '**dependent**' key provided within a trait object. It operates by making a field visible only when the value of another trait meets specific criteria. For instance, if the '*dataSource*' trait has a selected value of '*contentLibrary*', then this trait should become visible. Therefore, the value passed to the '**dependent**' trait should match the internal name of the trait value you specified. ``` *** Alright, let's examine the second trait object, `exp_checkbox`. ```js theme={null} { type: "exp_checkbox", displayName: "Show Heading", internalName: "showHeadingText", }, ``` This trait presents a checkbox labeled as '*Show Heading*'. When the checkbox is checked, it returns the value '*on*'; when unchecked, it returns '*off*'. *** #### What is dependencyConfig? As you may have observed in the [What is *dependent* & *subDependency?*](#what-is-dependent--subdependency) section, '*dependent*' and '*subDependency*' bind a single trait to the trait you're specifying as the dependency. In contrast, the **dependencyConfig** enables you to associate a single trait with multiple traits and their respective values. For instance, consider the trait for 'Heading Text'. We intend for this trait to be visible when the value of '*showHeadingText*' is '*on*' AND '*dataSource*' is '*freeForm*'. To achieve this, we've included the `config` array containing all `dependencyConfig` objects structured as `{ name: 'internalName Of Other Trait' , value: 'Value for which you are binding a trait'}`. Finally, you'll need to specify an `operator` for the **dependencyConfig**. You can use 'AND' to ensure that all the objects passed in **dependencyConfig's** **config** must match the cases. Alternatively, you can use 'OR' to match any one case from the **config**. *** Next, up is `exp_text` with `dependencyConfig`. ```js theme={null} { type: "exp_text", displayName: "Heading Text", internalName: "headingText", dependencyConfig: { config: [ { name: "showHeadingText", value: [WIDGET_CHECK_TRUE], }, { name: "dataSource", value: [FREE_FORM], }, ], operator: AND, }, }, ``` As observed in the above trait object, this trait pertains to 'Heading Text', offering a 'Text Input' for input. Its value will be accessible within the component's props using the key specified in '*internalName*' as '`headingText`'. Let's break down the **dependencyConfig** for better understanding. In the **config** array, you can see that this trait relies on two other traits: '*showHeadingText*' must be '*on*', and '*dataSource*' must be '*freeForm*'. Since we've set the operator as '*AND*', both conditions must be met for the dependency to take effect. *** Now, let's take a look at `exp_imageSelector` type, ```js theme={null} { type: "exp_imageSelector", displayName: "Background Image", internalName: "backgroundImage", dependent: "dataSource", subDependency: FREE_FORM, }, ``` This trait type will provides a out put as below image, <img alt="image-4.png" /> You'll notice three tabs labeled 'Desktop,' 'Tablet,' and 'Mobile' for viewing image links, which you can input into the "Image Link" text area. When you input an image link for the desktop tab, it automatically populates the same link for the Tablet and Mobile views. Additionally, you have the option to provide three different images for each specified device. You also have the option to select images from Experro's 'Media Manager' by clicking on the provided '*Choose file from Media Manager*' button. <Info>Choose file from Media Manager\` will not work while you are developing theme in your local system.</Info> According to this trait, it is identified by the `internalName` attribute, which is set as *backgroundImage*. Therefore, you will retrieve the value of this trait from the component's props under the key named *backgroundImage*. You simply need to assign that value to the `src` prop of the **ExpImage** Common-component. *** By using and customizing these traits, you have the flexibility to make the necessary changes to your widget as required. Now, let's grasp how we can seamlessly [Integrate the widget](./integrate-a-component-with-widget) we've created with a component. # Integrate a component with widget Source: https://help.experro.com/theme-development/create-custom-widget/integrate-a-component-with-widget As you have seen in the ['How to create widget's section's Step: 1'](./create-widget/#step-1), that we have already created a component and make sure to make a neccesary changes in respactive `index.ts` files as well in following **Steps** of it. In Step 1 of the ['How to create widget's section's Step: 1'](./create-widget/#step-1), section, you've observed that we've created a component and ensured that the necessary changes are made in the respective `index.ts` files as well, as outlined in the subsequent steps. When you made your Widget, you likely created a folder for the component. In this folder, you have files like a .tsx file which returns JSX, where you define how the component looks and an index.ts file that goes along with it. ```txt theme={null} src └── components ├── cms-library ├── exp-test-component ├── exp-test-component.tsx ├── exp-test-component-controller.tsx └── index.ts ``` For the component file, which in our scenario is named `exp-test-component.tsx`, it might vary based on your requirements. The file name could also be different depending on the specific component you're creating. The component file may appear similar to the snippet below: `exp-test-component.tsx` ```js theme={null} /** * Renders an exp-test-component component. * @param props - Components props. * @returns */ const ExpTestComponent = (props: any) => { const { id, component_content } = props; return <div>// ...components JSX</div>; }; export default ExpTestComponent; ``` In the component's props, you'll receive all the traitConfig objects with their internalName keys as props. For instance, if traitConfig includes a trait like this: ```js theme={null} { type: "exp_checkbox", displayName: "Show Heading", internalName: "showHeadingText", } ``` Its internalName would be showHeadingText. When you need to access the selected and updated value of this trait, you can directly destructure it from the props, and you'll obtain the value of the trait "Show Heading" in it. ```js theme={null} const { id, showHeadingText } = props; ``` > #### Default `id` as a prop <Info>You'll notice that each component receives a default prop named `id`. This prop is automatically provided to each component integrated with the widget. You can directly destructure it from the component's props.</Info> *** `exp-test-component-controller.tsx` To implement all the business logic for the component, we'll create a component-controller file, responsible for managing all the business logic. In the context of developing a React component, it's important to centralize all state management, including `useState`, `useEffect`, and other state manipulations, within this file exclusively. The `exp-test-component.tsx` will solely focus on rendering JSX based on the state managed in the controller file. So, at this point, we'll retrieve the data of the selected **Content Model** record. The selection is made from the pop-up of the trait type **exp\_contentModalPopUp**. This trait returns data in terms of the selected record's `id`, from which we'll fetch the record's data by making an API call in the controller file. So, basic struture look's like for the each controller file as below snippet. ```js theme={null} const ExpTestComponentController = (props: any) => { const { id, contentModel, modelInternalName } = props; /* This key need's to be unique for all the component you create for the Drag-&-Drop. * const modelKeyForSSR = "tes-component-ssr"; */ /* In this context, a reducer has been implemented to efficiently manage and handle * multiple states simultaneously, thus streamlining the process of state manipulation. */ const { componentDataDispatcher, setComponentDataDispatcher, isComponentLoaded, }: any = ExpComponentDataDispatcher({ id, modelInternalName, modelKeyForSSR: modelKeyForSSR, }); let parsedContentModel: ContentModelDataInterface | undefined; if (contentModel?.trim().length) parsedContentModel = JSON.parse(contentModel); /* You will find this useEffect which looks same in each component in which is * responsible for making an utilizig a common fuinction which gets data data of selected * record baised on the "internalName" and the "parsedContentModel". */ useEffect(() => { if (isComponentLoaded) { setComponentDataDispatcher({ type: expCommonDispatcherKeys.fetchingData, }); if (contentModel?.trim()?.length) { (async () => { setComponentDataDispatcher({ type: expCommonDispatcherKeys.dataFetched, data: await (parsedContentModel, modelInternalName, modelKeyForSSR, id), }); })(); } } }, [contentModel]); }; return { componentDataDispatcher, contentModel, }; export default ExpTestComponentController; ``` *** #### ExpComponentDataDispatcher This serves as a standard dispatch method, offering a dispatcher. Within this common utility, we've integrated a '**useReducer**' hook. Primarily, it accepts `id`, `modelInternalName`, and `modelKeyForSSR` as arguments. As a result, it furnishes three essential components crucial for component implementation: `componentDataDispatcher`, `setComponentDataDispatcher`, and `isComponentLoaded`. Here's a breakdown of the provided elements: * `componentDataDispatcher`: This object contains two values: `{isLoading, componentData}`. * **isLoading**: This state is a boolean value (`true/false`) indicating whether the component's data is being fetched or not. Different states utilized within the `useEffect` update the value of this state. * **componentData**: This state holds the data of the record obtained after making an API call, facilitated by the common method '`getContentLibraryData`'. * `setComponentDataDispatcher`: This serves as a setter method for the state, similar to when using `useState`. You specify an object containing type and state values, which are then set by the reducer. * `isComponentLoaded`: This state holds a boolean value (`true/false`), responsible for indicating whether the component's data has already been fetched or not. *** In conclusion, this controller returns: ```js theme={null} { componentDataDispatcher, contentModel, } ``` So, let's utilize this values in component, after that component should look like, ```js theme={null} /** * Renders an exp-test-component component. * @param props - Components props. * @returns */ const ExpTestComponent = (props: any) => { const { componentDataDispatcher, contentModel } = ExpTestComponentController(props); return <div>// ...components JSX</div>; }; export default ExpTestComponent; ``` Now, you can utilize the `componentDataDispatcher`, which contains the `isLoading` and `componentData` state values. You can utilize the `componentDataDispatcher`'s `isLoading`, `componentData`, and `contentModel` to display the loader of the component or a message indicating to "Select a record". All the data required for the component will reside in the `componentDataDispatcher`'s `componentData` key. You can utilize this data to render the component and return JSX accordingly. With Experro Storefront, integrating a component with a widget is a breeze, and customizing it to your exact specifications couldn't be simpler. # Types of traits Source: https://help.experro.com/theme-development/create-custom-widget/types-of-traits experr-storefront offers a range of traits for seamless integration with the component, each designed to enhance and expand the capabilities of your storefront. Traits provided by the experr-storefront are as follows: 1. #### exp\_text ( Textbox ): The `exp_text` trait adds a text box to the sidebar of the visual builder, allowing for easy content editing. To render `exp_text`, pass the below object to the trait configuration. ```js theme={null} { type: "exp_text", displayName: "Experro Storefront", internalName: "experroStorefront", } ``` When you include `exp_text` in the traitConfig array of the component's initial value, a text box will be rendered in the sidebar of the UI builder. The `displayName` will serve as the label for that text box. <img alt="image-8.png" /> *** 2. #### exp\_textArea ( Text Area ): The `exp_textArea` trait adds a text Area to the sidebar of the visual builder. traitConfig Object: ```js theme={null} { type: "exp_textArea", displayName: "Experro Storefront", internalName: "experroStorefront", } ``` <img alt="image-9.png" /> *** 3. #### exp\_checkbox ( Checkbox ): The `exp_checkbox` trait adds a Checkbox to the sidebar of the visual builder. traitConfig Object: ```js theme={null} { type: "exp_checkbox", displayName: "Experro Storefront", internalName: "experroStorefront", } ``` <img alt="image-10.png" /> *** 4. #### exp\_colorPicker ( Color Picker ): The `exp_colorPicker` trait adds a Color Picker to the sidebar of the visual builder. ```js theme={null} { type: "exp_colorPicker", displayName: "Experro Storefront", internalName: "experroStorefront", } ``` <img alt="image-11.png" /> *** 5. #### exp\_dropDown (Drop Down): The `exp_dropDown` trait adds a Drop Down to the sidebar of the visual builder. ```js theme={null} { type: 'exp_dropDown', displayName: 'Experro Storefront', internalName: 'experroStorefront', options: [ { value: 'value1', name: 'name 1' }, { value: 'value2', name: 'name 2' }, { value: 'value3', name: 'name 3' }, ] }, ``` The `options` array is used to populate the dropdown, where each object in the array represents an option. The `name` property specifies the display name for the option, while the `value` property specifies the actual value of the option. The `displayName` will be used as the placeholder for the dropdown, prefixed with `Select`. <img alt="image-12.png" /> *** 6. #### exp\_dataSourceDropDown ( Experro-Storefront Datasource Dropdown ): The `exp_dataSourceDropDown` is used to render a dropdown menu from which you can select the data source for your component. There are two types of data sources: 1. Content Library 2. Free Form This trait can be used as a separator for the data. If you want to use data from Experro's content library and also support inserting data from the sidebar settings in the same component, you can use this trait as a flag to determine the data source. ```js theme={null} { type: 'exp_dataSourceDropDown', } ``` For this trait, there will be no `internalName` or `displayName` as they are fixed. The `internalName` is `dataSource`, which is a reserved keyword and cannot be used for other traits' `internalName`. <img alt="image-13.png" /> *** 7. #### exp\_contentModalPopUp( Experro-Storefront Content Modal Popup ): `exp_contentModalPopUp` trait is used when data is sourced from Experro's content library. It displays a selection list in a popup, showing records from Experro's content library for that component. ```js theme={null} { type: 'exp_contentModalPopUp', modelInternalName: '<internal-name-for-component-content-modal>', } ``` This component also has a fixed internalName of contentModel, which is a reserved keyword. `modelInternalName` is the modal internal name of the content model. which so ever content models internal name is passed from here that content modals records will shown in the popup The `modelInternalName` is the modal internal name of the content model. Whichever content model's internal name is passed here, that content model's records will be shown in the popup. <img alt="image-14.png" /> *** # What is trait Source: https://help.experro.com/theme-development/create-custom-widget/what-is-trait When you drag and drop a widget that renders an associated component, you'll see different options on the side panel. These options include checkboxes for 'show/hide' headings, dropdowns for 'heading size' options, a 'color-picker' for heading color, and some default options provided by the Experro Storefront. These options are known as traits within the Experro Storefront. Here in below image you can see options for the `hero-carousel` component. <img alt="image.png" /> Here you can see the some Trait's for the `hero-carousel`, like, | Trait | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CONTENT\_MODEL\_POP\_UP | This trait takes a content model internal name as a configuration value and displays a list of records associated with that content model. It provides the selected Content Model records data as props to a component within the cms-library, effectively integrating the component with the widget. | | TEXT | It's a simple text input where any value entered will be passed as a prop to a component. | | CHECKBOX | It provides the value 'on' if the checkbox is selected and 'off' if the checkbox is unchecked. | | DROPDOWN | It displays multiple values to select from, accepting an options array of JSON where each object has the structure name: 'Name to Show', value: 'Value which you will get in component' . | | COLOR\_PICKER | A simple color picker provides the selected color's hex value in the component's props. | Here, we comprehend the concept of traits; let's delve into [How we can effectively utilize them](./how-to-use-traits). # About cli Source: https://help.experro.com/theme-development/experro-cli/about-cli Experro CLI is a command-line interface tool that you use to initialize environment file, fetch data from server, build, and deploy the theme. ## Installation You are already familiar with the process of installing the CLI. For reference, here is the command to install the CLI: ```sh theme={null} npm i -g experro-cli ``` After installation, you'll get `experro-cli` command in terminal. Use the following command to show everything that's available: ```sh theme={null} experro-cli --help Usage: experro-cli [OPTIONS] <command> Help Options: -h, --help Show this help message Available commands: build Build the app environment Environment related commands init Init the project server Start the local server version Version creation ``` Some of the commands accept options. Option names are prefixed with double dash (`--`) characters. If options requires the value, it should be in `--option-name=value` format. *** ### Available Commands ## To use this commands you will need to have `CLI token` created, if you don't have CLI token, [Get CLI Token](./get-cli-token). <Info> #### `init` *** This command helps to create **.env**. This file will contain information for: <br />1. tenant-id <br />2. workspace-id <br />3. cli-token <br />4. store-url <br /> For more information you can use help command: `experro-cli init --help` <br /> ```sh theme={null} experro-cli init --cli-token='XXXXX' --tenant-id=<tenant-id> --workspace-id=<workspace-id> --store-url=<store-hase>.experro.app --api-host=apis.experro.app --channel_ids=<channel_id_1>,<channel_id_2> ``` To obtain the required parameters, you can get it from the CLI token generated in the Experro Admin panel and set them in the `experro-cli init` command. </Info> <Info> #### `environment` *** This command lists the list of environments in the specified workspace. The information is retrieved from the .env file, which has been created using the aforementioned command `experro-cli init <--content-->`. <br /> To list down the environment you can use the command: <br /> `experro-cli environment list` </Info> <Info> #### `server` *** This command is useful to **start the local server**. It will help you fetch the data from Experro's live store. <br /> `experro-cli server start` </Info> <Info> #### `version` *** It allows you to create, delete, list and publish version's of the themes. <br /> To know more you can use this command: <br />` experro-cli version --help` <br /><br /> 1. Create version <br />2. Delete version <br />3. List version <br />4. Publish version <br /><br /> **1. Create a version** : <br />To create a version, simply use the command as shown below. Just assigned values of the `--name` and `--environment-id` with your specific values, then execute this command. Your latest version will be created, and the build with the provided `--name` will be uploaded to the admin panel. <br /> ```sh theme={null} experro-cli version create --name=<theme-name/version-name> --environment-id=<environmnet-id> ``` <img alt="image.png" /> After successfully creating a version, you will see an output similar to the screenshot above. **Note:** <br /> After successfully creating a version, an `id` will be displayed in your terminal (as shown in the screenshot above). Make sure to save this `id` for future reference, as it will be required to publish the uploaded version or perform other actions using Experro-cli. <br /> **2. Delete a version** :<br /> This option will helpful to delete a uploaded version. You just need to provide `--tenant-id` `--wrokspace-id` `--cli-token` and `--version-id`. Version-id will be same as we have seen in above command as below ```sh theme={null} experro-cli version delete --tenant-id=<tenent-id> --workspace-id=<workspace-id> --cli-token=<cli-token> --version-id=<version-id> ``` <br /> **3. List version**:<br /> The `list` option in the `version` command for `experro-cli` will display a list of all the versions that have been uploaded to the workspace. It will also show the status of each version, indicating which version is currently published. ```sh theme={null} experro-cli version list ``` <br /> **4. Publish version**:<br /> Option `publish version` will allow theme-developer to direclty publish the version which is created using command as below ```sh theme={null} experro-cli version publish --tenant-id=<tenent-id> --workspace-id=<workspace-id> --cli-token=<cli-token> --environment-id=<environment-id> --version-id=<version-id> ``` </Info> <Info> #### `build` *** This command is useful for creating an optimized local build. ```sh theme={null} experro-cli build --tenant-id=<tenent-id> --workspace-id=<workspace-id> --cli-token=<cli-token> --version-id=<version-id> ``` </Info> *** If you're facing any difficulties with the CLI, refer to the [Troubleshooting](./troubleshotting) section of the documentation for possible solutions. If you are facing any difficulties about CLI Token, then simply go ahead for [Get CLI Token](./get-cli-token). # Get cli token Source: https://help.experro.com/theme-development/experro-cli/get-cli-token **Step 1** - Login to the Admin Panel using the provided credentials. **Step 2** - Click on the Settings icon in the left menu. This action will open the Settings / Workspace page. <img alt="CLI Token Step 1" /> **Step 3** - Click on 'API & CLI Tokens'. This action should open the Tokens page. On this page, you should see two tabs with name API Tokens and CLI Tokens respectively. Click on a CLI Tokens tab. <img alt="CLI Token Step 2" /> **Step 4** - Click on the 'Create Token' button. This action should open pop-up. In this pop-up, you need to provide a name for the token, Expiration date, and select desired permission. <img alt="CLI Token Step 3" /> <img alt="CLI Token Step 4" /> **Step 5** - After filling in the required information, click on the 'Save' button to create the CLI token. <img alt="CLI Token Step 5" /> The token is generated now. You can either copy the token or click on Download button. Upon clicking the Download button, the `.txt` file with other important details including token will appear. In the downloaded `.txt` file, you should see the information such as Token Name, Site Hash, Tenant ID, Workspace ID, and CLI Token. You will use these details in `.env` file. If you're facing any difficulties with the CLI, you can refer to the [Troubleshooting](./troubleshotting) section of the documentation for possible solutions. # Review environment file Source: https://help.experro.com/theme-development/experro-cli/review-environment-file The .env files are typically used to store environment variables, which configure various aspects of your application. These settings may differ between development and production environments. While developing a theme on your local machine, the .env file allows you to point to different Experro environments and fetch data accordingly. ## Experro's provides three `.env` files: * `.env` * `.env.development.local` * `.env.production` *** ### `.env` Here's how the `.env` file will look after you run [`experro-cli init`](./about-cli/#init) and provide the necessary options: ```js theme={null} CLI_TOKEN=XXXXXXXX STORE_URL=XXX-en-us.experro.app TENANT_ID=02438836-35e0-413b-bb55-0a1a3833b5b1 WORKSPACE_ID=117065b7-b084-421b-a3cb-5c81d76197f2 API_HOST=apis.experro.app CHANNEL_IDS=XXXX-XXXX-XXXXXX-XXXX ``` > #### How to Obtain Channel IDs? > > To get Channel IDs, you can refer to the documentation [Get Channel Information](../other/channel-information#channel-ids). ### `.env.development.local` The `.env.development.local` file contains environment variables that the Experro base theme uses to determine which modules to load or exclude during local theme development. Currently, the `.env.development.local` file must include the following predefined variables: ```js theme={null} REACT_APP_BUILD_TARGET=app REACT_APP_ECOMMERCE_MODULE_ENABLE=true REACT_APP_STORE_URL=http://localhost:8080/ REACT_APP_STORE_TOKEN=http://localhost:8080/ ``` In addition to these required variables, Experro also allows you to add two optional variables: > The additional variables below will be supported only when you are using a BigCommerce store with Experro Admin: ```js theme={null} REACT_APP_MULTI_CURRENCY_ENABLE=false // Enables or disables multi-currency support. REACT_APP_EXTERNAL_CHECKOUT=true // Enables or disables the use of an external checkout versus an embedded one. ``` > ##### REACT\_APP\_BUILD\_TARGET > > The `REACT_APP_BUILD_TARGET` variable accepts two values: the default value `app`, and `app-ui-builder`. Setting it to `app-ui-builder` will launch the **Visual Builder** locally, allowing theme developers to customize component widgets accordingly. ### `.env.production` The `.env.production` file functions similarly to the `.env.development.local` file. While `.env.development.local` is used during local development, the `.env.production` file is utilized when creating or uploading a build using [experro-cli](Theme-Deployment.md). During local development, variables from `.env.development.local` are applied, but when you create a build or upload it, `.env.production` is used to determine the build configuration. # Theme deployment Source: https://help.experro.com/theme-development/experro-cli/theme-deployment Now that you understand Experro's base theme and its functioning, once you've made the necessary changes to align with your requirements, you might consider deploying it to the specific Experro workspace you're working on. Deploying is as simple as running a couple of commands in your terminal. <Warning> #### Watch Out! Before deploying the theme, ensure that your `.env` file contains valid information about your Experro workspace and a valid [Experro CLI](./about-cli) token with theme upload or full access permission. <br /> Here's the representation of how your **.env** file should be formatted: ```sh theme={null} CLI_TOKEN=<your-CLI-token> STORE_URL=<store-hase>.experro.app TENANT_ID=<tenant-id> WORKSPACE_ID=<workspace-id> API_HOST=apis.experro.app CHANNEL_IDS=<channel_id's> ``` The second requirement is to have [Expero CLI](./about-cli) installed on your system. <br /> </Warning> After making changes and customizations, the theme developer simply needs to open the terminal and navigate to the theme's directory. ### Step 1: Get Environment List First, retrieve the environment ID for the intended deployment by utilizing the following command: ```sh theme={null} experro-cli environment list ``` This command will provide an output similar to this: <img alt="environment-list.png" /> You will need to note down the `ID` of the environment you wish to deploy. ### Step 2: Version Create and Theme Upload To create a version and deploy the theme, use the following command: ```sh theme={null} experro-cli version create --name=<version_name> --environment-id=<environment_id> ``` If your CLI token has **full access** permission and you also want to publish the version, add the `--publish-version` option after the above `version create` command. ```sh theme={null} experro-cli version create --name=<version_name> --environment-id=<environment_id> --publish-version ``` And that's all, just hit enter to run this command, and your theme deployment will begin. *** ### When you have only Theme Upload Permission If you have a CLI token with only **upload** permission, then you just need to use the first command mentioned in the previous [Step 2](#step-2-version-create-and-theme-upload). However, after a successful build upload, you will see an object printed in the terminal with `Data` and `id` keys. Make sure to note down the `id` value, as it represents the version id needed for publishing the build with that version. This `id` value will be essential for publishing the theme using the appropriate CLI token access through the command. ```sh theme={null} experro-cli version publish ``` For further details about CLI options, you can refer to the [About CLI](./about-cli#version) document. # Troubleshotting Source: https://help.experro.com/theme-development/experro-cli/troubleshotting <Info> Whenever you encounter unexpected behavior while working with CLI, start troubleshooting by checking the terminal window where you started the CLI. </Info> ## Incompatible Node Version Check the Node version that you are using with the CLI. The CLI expects `14.0.0`. If you're using a Node version other than this, try switching to this specific Node version. ## Experro CLI Command Not Found If you receive the below shown error message, ```sh theme={null} experro-cli: command not found ``` Ensure that you've followed the steps mentioned in [Prerequisite](../getting-started/prerequisites) or attempt to reinstall the CLI. ## Fatal Error Config File If you receive the below shown error message, ```txt theme={null} fatal error config file: %w open .env: no such file or directory ``` Check the current location of the terminal to the base theme folder and then run the command. ## Help If you encounter any other issue related CLI, feel free to reach out for assistance. # Introduction Source: https://help.experro.com/theme-development/getting-started/introduction Experro's base theme is not only the starting point but also the ultimate building block of a quick-to-build theme for your eCommerce store. Whether you are looking forward to build an SPA (Single-page Application) or a full-fledged eCommerce store, this base theme is your one-stop solution. ## About Base Theme by Experro This base theme is a pre-built eCommerce template store design. With the **'base'** of the platform already created, you can simply make edits to your estore without any hassle. It's almost as if you are editing your social media profile. Yes! It is that intuitive! ## Agenda of the Base Theme Document Experro is a platform that minimizes the dependency on developers for setting up the eCommerce platform. However, to add to your ease, this document will **guide you with the A to Z of Experro base theme** for your dream eCommerce solution. ## What Does the Base Theme Include? The base theme incorporates the latest web technologies, design standards, and SEO best practices. All these have been crafted together in order to help users create powerful, visually stunning, and user-friendly web applications to drive and engage customers. ## What is the Difficulty Level of Using Base Theme? Working with the base theme is easy, but you will require to install a couple of software on your computer/system before getting started. Please refer to the [prerequisites](./prerequisites) document for more information on how to install and use these softwares. # Prerequisites Source: https://help.experro.com/theme-development/getting-started/prerequisites You will need the following software on your system. <Info>For easier understanding, versions for each software are mentioned in braces.</Info> * [Git](https://git-scm.com) (`2.25.1`) to clone the base theme. * [Node](https://nodejs.org) (`16.16.0`) to compile and run the base theme. * NPM (`8.11.0`) to manage and install the dependencies of the base theme. * [Experro CLI](https://www.npmjs.com/package/experro-cli) to fetch the data from Admin Panel. ## How to Install All the Above Software? Knowing the list is not enough, the next hurdle is ***how to install all the above software*?** Here is the step-by-step guide: **Step 1** - Git, Node, and NPM are easy to install and the documentation on how you can install these software is widely available on the Internet. Installing Experro CLI is as simple as running the following command in the terminal. ```sh theme={null} npm i -g experro-cli ``` **Step 2** - Once the installation is done, run the following command to confirm the installation of Experro CLI. ```sh theme={null} experro-cli --help Usage: experro-cli [OPTIONS] <command> Help Options: -h, --help Show this help message Available commands: build Build the app environment Environment related commands init Init the project server Start the local server version Version creation ``` **Step 3** - Yay, all set! Now that you have installed all the required software, you can proceed to the [Quickstart](./quickstart) guide for running the base theme locally. # Quickstart Source: https://help.experro.com/theme-development/getting-started/quickstart Now that we have guided you with the prerequisites, let us start with downloading the base theme on your device. ## Download & Configure Base Theme ### Download 1. Login into the Admin Panel using the provided credentials. 2. Click on the **Settings** icon from the left menu. 3. Click on **Workspace Settings**. <img alt="Image highlighting Settings" /> 4. Click on **Channels** from the left menu. <img alt="Settings - Theme" /> 5. Go in to **Default Channel**. <img alt="Settings - Theme" /> 6. Here, you will find environment wise theme options. <img alt="Settings - Theme" /> 7. Click on **Download** button. This will download a `1.0.0.zip` file. Extract it under a folder named `cms`. Inside, you’ll find another folder named `cms-<random>`. That folder contains your base theme. ### Configure Base Theme As you have now downloaded the base-theme, let us configure it to work with your local environment. To run base-theme in your local machine, you need to set-up a `.env` file with required information. You can generate the [CLI Token](../experro-cli/get-cli-token) file and get all the required information from it, where channel id will not be there but you can copy a channel id from Step 6 environment wise above. After setting up the `.env` file it looks like this <Info> #### `.env` ```sh theme={null} CLI_TOKEN=I6InZpa2FzIiwidHlwZSI6IkZVTExfQUNDRVNTIiwidG9rZW5UeXBlIjoiQ0xJIiwiYnlUb2tlbiI6InZpa2FzIiwiYXBwSWQiOiI2NjI3N2MzMy0yODIzLTQ4YTQtYmI0Yi1mMmU0Mjc3NjBmMjMiLCJpYXQiOjE3NDc4MzE3OTN9. STORE_URL=rekfdwer-us-en.experro.app TENANT_ID=925411b2-28f3-43fsdafs-fs4dca88bc WORKSPACE_ID=fsdfasf222-234e-4fcc-bafc-b3ad7fc6e API_HOST=apis.experro.app CHANNEL_IDS=b2276256-35ddfd3-fd0e-8dd6-e7we242b5b99 ``` </Info> Where `API_HOST` key value you need to keep it as it is `apis.experro.app`. Now `.env` is set for as per your requirement. You can proceed to the next step to run the base theme locally. Will need to install a node modules for the base theme to work. Run the following command in the terminal to install the dependencies. ```sh theme={null} npm install ``` Now run command ```sh theme={null} experro-cli server start ``` This command will run a server on :5050 port which is responsible to fetch data from experro to local machine. Now, Open another terminal and run below command to run base-theme locally. ```sh theme={null} npm start ``` That's all to setup a base-theme locally. # Change environment Source: https://help.experro.com/theme-development/other/change-environment # Environments And Channels Experro provides multiple channels within a workspace, meaning you can create several channels in a single workspace. When a new workspace is created, a default channel is automatically set up along with a default language, which is "English-United States" with the language code "en-us." Experro also provides multiple development environments across all channels. By default, Experro provides two environments: 1. Development 2. Production. ### How to change Environment For Local Development > #### Why? > > When developing a theme, it's crucial to avoid working directly on the `production environment`, as it can lead to issues with the live site. Instead, it's best to use a `development environment` for creating and testing new features. This practice ensures that any changes or developments do not affect the live site and helps maintain the stability of the production environment. To change the environment for local development, follow these steps: 1. **Check Your [.env File](../experro-cli/review-environment-file#env):** Locate the `.env` file, which contains a variable named `STORE_URL`. This variable will have a value like `<store-hash>-en-us.experro.app`. 2. **Update the `STORE_URL` Variable:** Modify the value of the `STORE_URL` variable to switch between different environments. Set it to the appropriate environment URL for your needs. 3. **Restart the [`experro-cli server`](../experro-cli/about-cli#server):** After updating the `STORE_URL` variable, restart the Experro CLI server to apply the changes. This will configure your local development environment according to the selected environment. #### STORE URL You can obtain the store URLs from the [Channel Settings](./channel-information#channel-settings). For guidance on how to access this information, refer to the [Channel Information](./channel-information) document. In the `Channel Settings`, you will find the list of languages, as shown in the image below. <img alt="store-ulrs.png" /> In the **Language URLs**, you will see multiple **store URLs** labeled by environment. These labels indicate which URL corresponds to which environment. You can take the URL and set it as the value for the `STORE_URL` variable, removing `https://` from the URL. Here are examples based on the image: When pointing to the `production` environment for local development, the `STORE_URL` would look like this: ```js theme={null} STORE_URL=c7kv7eyu-us-en.experro-dev.app ``` When pointing to the `development` environment, it would be: ```js theme={null} STORE_URL=c7kv7eyu-us-en-dev.experro-dev.app ``` After making this change, restart the [`experro-cli server`](../experro-cli/about-cli#server). This will successfully change the environment for local development. # Channel information Source: https://help.experro.com/theme-development/other/channel-information Experro allows you to create and manage multiple channels within a workspace. To retrieve channel information from Experro, follow these steps: **Step 1:** Log in to the Experro admin panel.\ **Step 2:** Select the tenant and workspace you are working on.\ **Step 3:** Navigate to the **Settings** menu. <img alt="Doc-Test-Experro-Control-Panel.png" /> **Step 4:** Choose **Channels** from the side menu under the **Channel Manager** section. <img alt="Channel_manager.png" /> <img alt="channel-list.png" /> Here, you will be able to view all the channels for the workspace. #### Channel ID's From the list, you can also find all the channel IDs in the **ID** column. These IDs can be used in the `.env` file as needed. ### Channel Details Once you have reviewed the list of channels, click on a specific channel to see its details and settings. <img alt="chnnel-detatail.png" /> ### Channel Settings To view the channel settings, click on the **Channel Settings** button. This section provides detailed information about the channel, including the number of languages added, the channel name, channel code, and more. <img alt="Channel-settings.png" /> # Making http requests Source: https://help.experro.com/theme-development/other/making-http-requests The `expFetch` method is part of the `Http` class in the `experro-storefront` module. It provides an easy way to make HTTP requests with support for SSR (Server-Side Rendering) and customizable headers, request bodies, and methods. ### Method Signature ```typescript theme={null} async expFetch({ key, url, enableSSR, headers, body, method, }: ExpHttpRequest): Promise<any>; ``` ### Parameters The method accepts an object of type `ExpHttpRequest` with the following fields: | **Parameter** | **Type** | **Description** | **Required** | | ------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `key` | `string` | A unique identifier for the request. This is required when enabling SSR (Server-Side Rendering). Ensures correct tracking. | Optional (Required for SSR) | | `url` | `string` | The URL of the endpoint you are making the request to. | Required | | `enableSSR` | `boolean` | A flag to enable SSR. Set this to `true` to enable SSR functionality. | Optional | | `headers` | `object` | The headers to be sent with the request. If not provided, default headers `{ 'content-type': 'application/json' }` will be used. | Optional | | `body` | `object` | The request body, used only for methods like `POST`, `PUT`, `PATCH`, and `DELETE`. Not required for `GET` requests. | Optional | | `method` | `GET`, `POST`, `PUT`, `DELETE`, \`PATCH\`\` | The HTTP method to be used for the request. This is a required field. | Required | ### Default Headers If no headers are provided, the following default headers will be used: ```json theme={null} { "content-type": "application/json" } ``` ### Response The method returns a Promise that resolves to the response data from the HTTP request. ### Usage Examples #### Example 1: Basic GET Request This example demonstrates how to make a simple `GET` request without enabling SSR. ```js theme={null} import { Http } from 'experro-storefront'; const data = await Http.expFetch({ url: 'https://example.com/api/data', method: 'GET', }); console.log(data); ``` #### Example 2: POST Request with Body and SSR Enabled In this example, we make a `POST` request with a request body and enable SSR by setting the enableSSR flag to true. The key must be unique to properly enable SSR. ```js theme={null} import { Http } from 'experro-storefront'; const data = await Http.expFetch({ key: 'unique_key_123', // Unique key for SSR tracking url: 'https://example.com/api/submit', enableSSR: true, // Enable SSR headers: { 'content-type': 'application/json' }, body: { name: 'John', age: 30 }, method: 'POST', }); console.log(data); ``` <Info> #### SSR and key The key is crucial when enabling SSR. It must be unique to ensure that the request is tracked and handled correctly on the server side. You cannot reuse the same key for different requests when SSR is enabled. </Info> <Warning> #### Default Headers If no custom headers are provided, the request will use the default header `{ 'content-type': 'application/json' }` </Warning> <Info> #### Request Body The body parameter is optional and should only be included for methods like POST, PUT, PATCH, or DELETE. </Info> The `expFetch` method is a flexible and efficient way to make HTTP requests, with support for SSR, custom headers, and various HTTP methods. By providing an easy-to-use interface, it simplifies API calls in your application, allowing you to focus on the core logic while handling request details seamlessly. # Manage internationalization Source: https://help.experro.com/theme-development/other/manage-internationalization Internationalization is the process of designing your project to support multiple languages and regions. It will be provided by Experro’s **basetheme**, integrated for the default channel in **English - United States** with the language code **en-us**. you can take a look at the main configoration files, under ```txt theme={null} src └── locale ├── en.json └── index.ts ``` `en.json` Contains, It will have just normal json object like, ```json theme={null} { "translation": { "common": { "model_select_msg": "Please select a record" } // Object keys for internalization, } } ``` `index.ts` > When creating a new config file for another language, remember to add an entry in the `index.ts` file of the `locale` folder. ```js theme={null} import en from './en.json'; // NOTE 1 : Ensure that each key in the following object is formatted according to the specified pattern: "en-US" or 'en-MX'. // The language code before the '-' should be lowercase, while all characters after the '-' should be uppercase. // NOTE 2 : Ensure that the object name 'exp_lang' remains unchanged; otherwise, it may not function as expected. // NOTE 3 : For the default or fallback language, use the key 'en' exclusively, as demonstrated in the following object. const exp_lang: any = { 'en-US': en }; export { exp_lang }; ``` That’s all for setting up internationalization and configuration. Here’s how you can use internationalization during theme development: ```js theme={null} import { useTranslation } from 'react-i18next'; const ExpBanner = () => { const { t } = useTranslation(); return ( <div> Next word is translated: {t('common.model_select_msg')} </div> ); } ``` That’s all—it’s that easy to use! # News letter subscribe Source: https://help.experro.com/theme-development/other/news-letter-subscribe The implementation for the same can be found in the footer section under "footer newsletter." ```txt theme={null} src └── components └── footer └── footer-newsletter ├── footer-newsletter-controller.tsx └── footer-newsletter.tsx ``` Integrating the [subscribeToNewsLetter](./services/ecommerce-service#subscribeToNewsLetter) of BigCommerce is as simple as implementing the /JavaScript form. Just create a simple HTML form with the input field as a text or email type, ensuring proper validations. Upon submission of the form, you will receive the email address from the form data. Now, you just need to import `EcommerceService` from 'experro-storefront'. `EcommerceService` provides an asynchronous method called `subscribeToNewsLetter('sample@experro.com')` which accepts the email address. It will return the response as success. If the provided email address is already registered, you will receive a valid error message in the response's `Error.message`. For detailed implementation, refer to `footer-newsletter.tsx` and `footer-newslatter-controller.tsx`. ## signUp Handler Method ```javascript theme={null} const signUpHandler = async (data: any) => { const formSubmit = await EcommerceService.subscribeToNewsLetter(data?.email); if (formSubmit?.Status === 'success') { toast.success(formSubmit.Data); } else { toast.error(formSubmit.Error.message); } setEmailValue(''); }; ``` # Auth service Source: https://help.experro.com/theme-development/other/services/auth-service The `AuthService` is used to retrieve all user-related data and authenticate the user. You can import the `AuthService` from the `experro-storefront` package. ```js theme={null} import { AuthService } from 'experro-storefront'; ``` Here is a list of functions that the `AuthService` provides. 1. [`isUserLoggedIn`](#isuserloggedin) 2. [`getUserDetails`](#getuserdetails) 3. [`setUserDetails`](#setuserdetails) 4. [`login`](#login) 5. [`logout`](#logout) 6. [`signup`](#signup) 7. [`forgotPassword`](#forgotpassword) *** ## isUserLoggedIn This function returns either `false` or `true` to indicate whether the user is logged in or not. ```js theme={null} const isLoggedIn = AuthService.isUserLoggedIn(); ``` *** ## getUserDetails This function returns the user details including cart, store, and user information. ```js theme={null} const userObj = AuthService.getUserDetails(); ``` *** ## setUserDetails This function is used to update the details of the user. It takes `userDetails` as the parameter. ```js theme={null} const userObj = AuthService.setUserDetails(userDetails); ``` *** ## login This function is used to login to the base theme. The function accepts an object with `username` and `password` as two properties. ```js theme={null} const userObj = AuthService.login({username, password}); ``` *** ## logout This function logs you out from the base theme. ```js theme={null} AuthService.logout(); ``` *** ## signup This function is used to register the user details. This function accepts an object with `firstName`, `lastName`, `email`, `password`, `phone`, `company`, and `customFields` as properties of the object. ```js theme={null} const user = AuthService.signup({ firstName, lastName, email, password, phone, company, customFields, }); ``` *** ## forgotPassword The function is used to reset the password. This function accepts an object with `email` as the property of the object. ```js theme={null} const res = AuthService.forgetPassword({ email }); ``` # Content services Source: https://help.experro.com/theme-development/other/services/content-services The `ContentService` is used to get the data of the base theme configured in Admin Panel. You can import the `ContentService` from the `experro-storefront` package. ```js theme={null} import { ContentService } from 'experro-storefront'; ``` Here is a list of functions that the `ContentService` provides. 1. [`getSingleTypeContent`](#getsingletypecontent) 2. [`getCollectionRecordsByCollectionInternalName`](#getcollectionrecordsbycollectioninternalname) 3. [`getCollectionTypeContentById`](#getcollectiontypecontentbyid) 4. [`getMenuById`](#getmenubyid) 5. [`getContentModelRecordsByFieldKeyValue`](#getcontentmodelrecordsbyfieldkeyvalue) ## getSingleTypeContent This function returns the single type data. This function accepts an object with `modelName` as the property. ```js theme={null} const single_type_data = getSingleTypeContent({modelName : 'globalSettings'}); ``` ## getCollectionRecordsByCollectionInternalName This function returns the record list by `id`, `versionId`, `modelName`, and `componentId`. ```js theme={null} const collectionData = getCollectionRecordsByCollectionInternalName({ modelInternalName: "collection_data_internal_name: }); ``` If you're fetching the "zig zag banner", then will get a response similar to shown below. ```json theme={null} { content_model_id: "a5d01c39-202f-45a9-b9f6-49b3e0a63b8c", content_model_name: "Home Zig zag banner", current_version_id: "197fbd97-faad-44dc-a823-de72b806e4c8-2", current_version_name: "#2", id: "197fbd97-faad-44dc-a823-de72b806e4c8", title: "Headless CMS" } ``` ## getCollectionTypeContentById This function returns the collection type by content id. This function accepts an object with the properies you get from `getCollectionRecordsByCollectionInternalName` function call. ```js theme={null} const collectionDataById = await ContentService.getCollectionTypeContentById({ id: '197fbd97-faad-44dc-a823-de72b806e4c8', versionId: '197fbd97-faad-44dc-a823-de72b806e4c8-2', modelName: 'modal_name', componentId: 'component_id', ssrKey: `${id}-'example-ssr`, enableSSR: true, }); ``` The `id` in `ssrKey` should be any unique value for each API call. If same duplicate id is found, it may behave differently. ## getMenuById This function returns menu or navigation created in Admin Panel. This function accept `menuId`. ```js theme={null} const menuDataResponse = await ContentService.getMenuById(menuId); ``` ## getContentModelRecordsByFieldKeyValue This function returns all the records by the model internal name. If you've created the "zig zag banner", with this method, you'll get all the records for this "zig zag banner" as an array of objects contains data for the "zig zag banner". ```js theme={null} const zig_zag_banner_records = ContentService.getContentModelRecordsByFieldKeyValue({ modelInternalName: 'zig_zag_banner', fieldKey: 'id', fieldValue: '*', fieldsToQuery: '', }); ``` To fetch the specific data, we can mention the name of the fields in `fieldsToQuery` e.g., ```js theme={null} fieldsToQuery: 'title_text_et,banner_description_et,button_layout_com,pop_up_com' ``` Following are the list of other options that you can pass with this method. | Property | Description | Type | | ---------- | ----------------------------------------------------------------- | ------ | | `sortBy` | Field to sort by. | String | | `sortType` | The direction to sort ascending or descending as `ASC` or `DESC`. | String | | `limit` | Number of records you want to fetch. | Number | | `skip` | Number of records you want to skip. | Number | <Info> **Note:** The following properties need to be used together: `sortBy` and `sortType` `limit` and `skip` </Info> # Ecommerce service Source: https://help.experro.com/theme-development/other/services/ecommerce-service The `EcommerceService` is used to get all the data related to the eCommerce operations such as get cart details, search products, add products to the wishlist. You can import the `EcommerceService` from the `experro-storefront` package. ```js theme={null} import { EcommerceService } from 'experro-storefront'; ``` Here is a list of functions that the `EcommerceService` provides. 1. [`getCart`](#getcart) 2. [`createCart`](#createcart) 3. [`updateCustomerId`](#updatecustomerid) 4. [`addToCart`](#addtocart) 5. [`updateCart`](#updatecart) 6. [`deleteItemInCart`](#deleteitemincart) 7. [`search`](#search) 8. [`facetedSearch`](#facetedSearch) 9. [`getFacetByCategoryName`](#getfacetbycategoryname) 10. [`getProductReviewsByProductId`](#getproductreviewsbyproductid) 11. [`addProductReview`](#addproductreview) 12. [`addCouponCode`](#addcouponcode) 13. [`removeCouponCodeById`](#removecouponcodeById) 14. [`createWishlist`](#createwishlist) 15. [`updateWishlist`](#updatewishlist) 16. [`deleteWishlist`](#deletewishlist) 17. [`getAllWishlists`](#getallwishlists) 18. [`getWishlistById`](#getwishlistbyid) 19. [`addItemToWishlist`](#additemtowishlist) 20. [`deleteItemFromWishlistById`](#deleteitemfromwishlistbyid) *** ## getCart The function returns cart details. ```js theme={null} const cartObj = await EcommerceService.getCart(); ``` *** ## createCart The function is used to create a cart. It accepts an object with `customerId` and `line_items` as properties. ```js theme={null} const cart = await EcommerceService.createCart({ customerId, line_items }); ``` If the user is logged in, provide `userId` as a `customerId` and `line_items` is an array of the products object that need to be added in cart. *** ## updateCustomerId The function updates the customer id for the existing cart. It accepts object with `customerId` and `cartId` the properties. ```js theme={null} const cart = await EcommerceService.updateCustomerId({ customerId, cartId }); ``` If the user is logged in, provide `userId` as a `customerId`. *** ## addToCart The function adds a product to the cart. It accepts an object with `line_items` as the property. ```js theme={null} const cart = await EcommerceService.addToCart({ line_items }); ``` The `line_items` is an array of the product object. *** ## updateCart The function updates the item in the cart. It accepts an object with `itemId` and `line_item` as the properties. ```js theme={null} const cart = await EcommerceService.updateCart({ itemId, line_item }); ``` The `itemId` is the id of the product item or `line_item` you want to update in the cart. *** ## deleteItemInCart The function delete the items from the cart. It accepts an object with `itemId` as the property. ```js theme={null} const cart = await EcommerceService.deleteItemInCart({ itemId }); ``` *** ## search The function provide a ways to search the items or products available for the purchase.It accepts object with `searchObj` as property. ```js theme={null} const result = await EcommerceService.search({ searchObj); ``` The `searchObj` can have the following properties. ```js theme={null} searchObj: { body: { search_terms: text, }, skip: 0, limit: 10, fieldsToQuery: 'images_ej, price_efi', sortBy: 'relevance', facet: [] }, ``` | Property | Description | Type | | ------------- | --------------------------------- | ------ | | `search_term` | Search text | String | | `skip` | Skip the result (for pagination) | Number | | `limit` | Limit the result (items per page) | Number | | `sortBy` | Sort the result by | String | | `facets` | Filters applied to the search | Array | *** ## facetedSearch This function returns facets based on search criteria. It accepts an object with `searchObj` property. ```js theme={null} const result = await EcommerceService.facetedSearch({ searchObj }); ``` *** ## getFacetByCategoryName The function returns facets based on searched category. It accepts string. The value of the string can **either** be the name of a category to search **or** `All` for a random search. ```js theme={null} const result = await EcommerceService.getFacetByCategoryName(categoryName); ``` *** ## getProductReviewsByProductId The function returns reviews for the given product. It accepts an object with `productId` as the property. ```js theme={null} const reviews = await EcommerceService.getProductReviewsByProductId({ productId }); ``` *** ## addProductReview The function add a review for the given product. It accepts an object with `productId` and `body` as the properties. ```js theme={null} const review = await EcommerceService.addProductReview({ productId, body }); ``` The `productId` is the `provider_id_esi` of the particular product. `body` is an object with following properties. | Property | Description | Type | | --------------- | --------------------------------- | ------ | | `title` | Title of the review | String | | `date_reviewed` | Date of the submitting the review | Date | | `text` | Review comment | String | | `rating` | Rating between 1 to 5 | Number | | `name` | Name of the user | String | | `email` | Email of the user | String | ```js theme={null} body: { title: 'Title for the review', date_reviewed: '2023/12/03', text: 'Review comment', rating: 4, name: 'Kai Doe', email: 'kai@doe.com', } ``` *** ## addCouponCode This function apply the coupon code for the products in the cart. It accepts an object with `body` as the property. ```js theme={null} const result = await EcommerceService.addCouponCode({ body }); ``` `body` is an object with following property | Property | Description | Type | | ------------- | ----------- | ------ | | `coupon_code` | Coupon code | String | ```js theme={null} body: { coupon_code: 'COUPON_CODE', }, ``` *** ## removeCouponCodeById The function removes the coupon code. It accepts an object with `couponId` as property. ```js theme={null} const couponCode = await EcommerceService.removeCouponCodeById({ couponId }); ``` The `couponId` is an id of the particular coupon that should be removed. *** ## createWishlist This function create a new wishlist. It accepts an object with `body` property. ```js theme={null} const wishlist = await EcommerceService.createWishlist({ body }); ``` `body` is an object with following property. | Property | Description | Type | | ------------- | --------------------------------- | ------- | | `customer_id` | Logged in customer id | Number | | `is_public` | Make this wishlist public or not | Boolean | | `name` | Name of the wishlist | String | | `items` | Product items to add in wishlist. | Object | ```js theme={null} body: { customer_id: 12, is_public: false, name: "School Shopping", items: [ { "product_id": 12, "variant_id": 152, }, ], } ``` *** ## updateWishlist This function update existing wishlist's items, name, and visibility. It accepts an object with `wishlistId` and `body` as the properties. ```js theme={null} const wishlist = await EcommerceService.updateWishlist({ wishlistId, body }); ``` `wishlistId` is an id of an existing wishlist. `body` is an object. *** ## deleteWishlist This function deletes the wishlist. It accepts an object with `wishlistId` property. ```js theme={null} const wishlist = await EcommerceService.deleteWishlist({ wishlistId }); ``` *** ## getAllWishlists This function returns all the wishlist. ```js theme={null} const wishlists = await EcommerceService.getAllWishlists(); ``` *** ## getWishlistById This function returns `wishlist` by given id. It accepts an object with `wishlistId` as property. ```js theme={null} const wishlist = await EcommerceService.getWishlistById({ wishlistId }); ``` *** ## addItemToWishlist This function adds product item into an existing wishlist. The function accepts an object with `wishlistId` and `body` as properties. ```js theme={null} const wishlist = await EcommerceService.addItemToWishlist({ wishlistId, body }); ``` `wishlistId` is an id of the existing wishlist in which item needs to be added. The `items` is an array of the object with `product_id` and `variant_id` properties. ```js theme={null} { items: [ { "product_id": 12, "variant_id": 152, }, ], } ``` *** ## deleteItemFromWishlistById This function deletes a particular item from the wishlist by item id. The function accepts `wishlistId` and `itemId` as properties. ```js theme={null} const wishlist = await EcommerceService.deleteItemFromWishlistById({ wishlistId, itemId }); ``` The `wishlistId` is an id of the existing wishlist and `itemId` is the product item id which is going to be deleted from wishlist. *** ## subscribeToNewsLetter > This method is designed to handle newsletter subscriptions within the context of a BigCommerce store, for now. This function serves as a valuable tool for incorporating newsletter subscription functionality into a BigCommerce store. You only need to provide an `email-id` as an input parameter to enable the integration. ```js theme={null} const formSubmit = await EcommerceService.subscribeToNewsLetter(data?.email); ``` Newsletter subscriptions for the BigCommerce store will be processed through this function. If the provided email ID is not already subscribed, the function will execute the subscription. Otherwise, it will return an appropriate error message. *** # Shopify support Source: https://help.experro.com/theme-development/other/shopify-support Experro Base-theme supports Shopify stores, but for a seamless experience, configure two aspects in the Shopify admin panel: 1. Implement checkout-related changes by adding the provided script to the "Additional Scripts" section within the checkout settings. 2. Customize email templates to maintain a consistent brand experience. ## Checkout Changes To make checkout-related changes, follow the steps provided below. **Step 1:** The initial step is to log in to your Shopify store using the provided credentials. **Step 2:** Next, navigate to the store settings section. <img alt="image.png" /> **Step 3:** Proceed by clicking on the checkout link to make the necessary changes for the checkout process. <img alt="image.png" /> **Step 4:** Within the checkout settings, find the section called "Additional Scripts." <img alt="image.png" /> **Step 5:** You need to add the provided script to the "Additional Scripts" section and Save it. ```js theme={null} <script> try { const redirect = 'https://excore-shopify-demo.experro.com/thank-you/'; const requiredFields = [ 'customer', 'id', 'item_count', 'line_items', 'line_items_subtotal_price', 'name', 'order_id', 'order_name', 'order_number', 'total_price', ]; const modifiedCheckout = {}; for (const field of requiredFields) { const checkoutFieldValue = Shopify.checkout[field]; if (checkoutFieldValue) { modifiedCheckout[field] = checkoutFieldValue; } } window.top.location.href = `${redirect}?c=${JSON.stringify(modifiedCheckout)}`; } catch (e) { console.error(e); } </script> ``` ## Email Template Changes To make Email-tempalte changes, follow the steps provided below. **Step 1:** In the Shopify admin panel, find the "Settings" section, and then click on "Notifications." And add you Business email to Sender email. <img alt="image.png" /> **Step 2:** To allow users to redirect to your Experro store from email templates in your Shopify store, you need to make changes to the email templates. To modify the order confirmation template in your Shopify store, simply click on the "Order confirmation" template listed under the "Orders" tab in your Shopify admin panel. <img alt="image.png" /> Click on **Edit Code** <img alt="image.png" /> To enable redirection in the email template, you need to add the URL for the Experro store domain where the redirection should be pointed. This allows customers to seamlessly navigate to your Experro store from the email template. <img alt="image.png" /> Exactly! Once you've made the necessary changes for one template, you can replicate the same process for other templates in a similar manner. By customizing the URLs to redirect users to your Experro store, you can ensure a cohesive experience across all email templates in your Shopify store. # Style guide Source: https://help.experro.com/theme-development/other/style-guide This guide can be used for any theme development involving the Experro base-theme, as well as for customizing the base-theme through the Experro platform. ## Basic Rules * Ensure each file contains only one component. * Utilize JSX syntax consistently for every component. * Opt for TypeScript over JavaScript, particularly for new code, whenever feasible. ### File Creation * Adhere to `kebab-case` when creating any files. * Always generate component files with the extension `.tsx`. * Create controller files with the extension `.ts` exclusively. ```js theme={null} //bad Exp - hero_banner.tsx; Exp - hero_banner - controller.tsx; //good exp - hero_banner.tsx; exp - hero - banner - controller.ts; ``` ### CMS Component Creation 1. **Component Folder:** * Within the `cms-library` directory, create a new folder named after your theme component. This folder will store all the component's files. 2. **Component Structure:** * Inside the component folder: * Create a file with the same name as your component but with the `.tsx` extension. This file is responsible for returning the component's JSX code. * Create another file with the `.ts` extension. This file will contain all the business logic for your component, separate from the JSX. * Create an `index.ts` file. This file will act as the entry point, potentially exporting the main component and any helper functions from the controller file. 3. **Register the Component (parent `index.ts`):** * In the parent folder of `cms-library` (likely named `components`), locate the `index.ts` file. * Edit this `index.ts` file to include an entry for your newly created component. This typically involves importing the component from its folder location and adding it to an export statement. By following these steps, you'll create a well-organized component with a clear separation of concerns and ensure it's registered for use within the `cms-library`. ### Props * Always use `camelCase` for prop names, or `snake-case` if the prop value is a React component. ```js theme={null} // bad <ExpBanner TitleText="hello" DescriptionText="This is description" /> // good <ExpBanner titleText="hello" description_text="This is description" /> ``` ### Parentheses Wrap JSX tags in parentheses when they span more than one line. eslint: [react/jsx-wrap-multilines](https://github.com/elastic/kibana/blob/main/STYLEGUIDE.mdx) ```js theme={null} //bad return <ExpHeroBanner varriant='layout-1'> <ExpHeroBanner> //good return ( <ExpHeroBanner varriant='layout-1'/> ); ``` ### Method Use Arrow functions to close over local variables. For repetitive tasks or functions with identical logic declared and invoked in multiple components, consider relocating them to the `utils` folder and exporting them from its index. Do not use underscore prefix for internal methods of a React component. ```js theme={null} //bad const _getProductData = () => {...}; //good const getProductData = () => {...}; ``` <Info> #### Don't use underscores for privacy in JavaScript components. While some languages use underscores to mark something as private, JavaScript doesn't have built-in privacy. All properties, even those with underscores, are accessible by anyone using your code. Treat all component properties as public and use other methods (like closures or modules) for true data encapsulation if needed. </Info> ### Import only top-level modules The files inside a module are implementation details of that module. They should never be imported directly. Instead, you must only import the top-level API that's exported by the module itself. On the other hand, a module should be able to import parent and sibling modules. ```js theme={null} // bad import ExpHeroBanner from "./components/hero-banner/exp-hero-banner"; import inSibling from "../components/child"; // good import components from "./components"; import ExpHeroBanner from "./components/hero-banner"; import parent from "../"; import ancestor from "../../../"; import sibling from "../components"; ``` ### Avoid export \* in top level index.ts files The exports in `componetns/index.ts`, `public/index.ts` dictate a plugin's public API. The public API should be carefully controlled, and using `export *` makes it very easy for a developer working on internal changes to export a new public API unintentionally: ```js theme={null} // bad export * from "foo/child"; export * from "../foo/child"; // good export { ExpHeroBanner } from "./component/hero-banner"; export { child } from "./child"; ``` ### Write small functions Keep your functions short. A good function fits on a slide that the people in the last row of a big room can comfortably read. So don't count on them having perfect vision and limit yourself to \~15 lines of code per function. ### Default argument syntax Always use the default argument syntax for optional arguments: ```js theme={null} // bad function validationCheck(fields, isSubmit) { if (typeof fields === 'undefined') { fields = []; } ... } // good function validationCheck(fields = [], isSubmit = false) { ... } ``` ### Prettier and Linting We are gradually moving the Experro theme code base over to Prettier. All TypeScript code and some JavaScript code (check .eslintrc.js) is using Prettier to format code. We recommend you to enable running ESLint via your IDE. Whenever possible we are trying to use Prettier and linting, instead of maintaining a set of written style guide rules. Consider every linting rule and every Prettier rule to be also part of our style guide and disable them only in exceptional cases and ideally leave a comment why they are disabled at that specific place. ### Avoid `any` whenever possible With the advent of TypeScript 3.0 and the introduction of the `unknown` type, there are seldom reasons to employ `any` as a type. Nearly all instances where `any` was previously used can be substituted with either a generic or `unknown` type (in cases where the type is genuinely unknown). It's advisable to consistently utilize these mechanisms over `any`, as they offer stricter typing and are less prone to introducing bugs in the future due to inadequate types. If your plugin does not utilize `any` or if you're initiating a new plugin, it's recommended to enable the `@typescript-eslint/no-explicit-any` linting rule for your plugin via the `.eslintrc.js` configuration. ### Use slashes for comments Use slashes for both single line and multi line comments. Try to write comments that explain higher level mechanisms or clarify difficult segments of your code. Don't use comments to restate trivial things. ```js theme={null} // bad // Execute a regex const matches = item.match(/ID_([^\n]+)=([^\n]+)/)); // Usage: loadUser(5, function() { ... }) function loadUser(id, cb) { // ... } // Check if the session is valid const isSessionValid = (session.expires < Date.now()); // If the session is valid if (isSessionValid) { ... } // good // 'ID_SOMETHING=VALUE' -> ['ID_SOMETHING=VALUE', 'SOMETHING', 'VALUE'] const matches = item.match(/ID_([^\n]+)=([^\n]+)/)); /** * Fetches a user from... * @param {string} id - id of the user * @return {Promise} */ function loadUser(id) { // This function has a nasty side effect where a failure to increment a // redis counter used for statistics will cause an exception. This needs // to be fixed in a later iteration. ... } const isSessionValid = (session.expires < Date.now()); if (isSessionValid) { ... } ``` ### SASS files When writing a new component, create a sibling SASS file of the same name and import directly into the top of the JS/TS component file. Doing so ensures the styles are never separated or lost on import and allows for better modularization (smaller individual plugin asset footprint). It is recommended to create a new file for component or file in that particuler comonents folder. and import it in a `src/assets/scss/app.scss` for global mapping. # Theme utilities Source: https://help.experro.com/theme-development/other/theme-utilities Find below the list of some basic utility files and funcitons: ## ExpComponentDataDispatcher We have learned about creating and using both default and custom components. Both types of components utilize a method called **ExpComponentDataDispatcher**. The `ExpComponentDataDispatcher` is an integrated feature that facilitates the management and proper display of API data. It relies on the foundational use of useReducer in React. To understand this functionality, it is important for the user to have a basic knowledge of [useReducer](https://react.dev/reference/react/useReducer) Here, we have three props: 1. `id` 2. `modelInternalName` 3. `modelKeyForSSR` Moving on to the `useReducer` in `ExpComponentDataDispatcher`, `dataOfComponentDispatcher` stores data, while `componentDataDispatcher` is used to set data. The dispatcher includes three cases along with a default case. 1. **initializingFreeForm:** If the user is creating a component with free form support, in this scenario, the componentData will be cleared, the isLoading flag will be set to false, and the component will return to its initial state. 2. **fetchingData:** If the user is creating a Default Component or a Content-Library-based component, the execution of the `dispatcher` will occur before the API call. In this scenario, the `isLoading` property is set to true, and the `componentData` is cleared or emptied. This ensures that the component reverts to its initial state with a loader. 3. **dataFetched:** This case is also applicable to the Default Component. The purpose of this scenario is to store the fetched API data in the `componentData` variable and then pass it to the Default Component. It will likely be invoked after the second case i.e `fetchingData`. Additionally, the `isLoading` property is set to false as we don't require a loader after obtaining the data. 4. **default:** This case is specifically designed to handle errors that may occur if the user has added any unidentified values. We utilize constants instead of strings to mitigate typographical errors. Therefore, it is considered a best practice for users to employ constants rather than strings. ## getContentLibraryData The function below utilizes the `ContentService` from the `experro-storefront` to send an API request that retrieves data from the admin panel. In order to achieve this, we must provide the following values as parameters: **1. parsedContentModel:** It contains the ID of the content-model and the current\_version\_id associated with that specific content-model. **2. modelInternalName:** It contains the model internal name of that component. For example, the modelInternalName for the Title-Section is 'title\_section'. All the modelInternalNames are passed through a file named `src/utils/constants-model-internal-name.ts`. **3. modelKeyForSSR:** The `modelKeyForSSR` is used to ensure that each components are identical. String is assigend as value in `modelKeyForSSR` **4. id:** Every component has a unique ID (CSS selector) assigned to ensure their identicity. > **Note**: > Both 'modelKeyForSSR' and 'id' are used to ensure that each components are identical. ## linkParser In the `utils/` directory you can find a file `link-parser.tsx`. The `ExpLinkParser` is a component which can be used instead of `<a/>` tag or the react's `<link/>` tag. ```js theme={null} <ExpLinkParser to={'http://example.com'}> Example </ExpLinkParser> ``` The linkParser function detect's that the url you provided is internal or external dynamically and render's basic `<a/>` tag or react's `<link/>` tag accordingly. **Props** | prop | type | description | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | | to | String | URL to be re-directed when user clicks on `linkParser` | | target | String | Give `_blank` as target prop if you want to open the url in new tab, by default the target will be `_self` | | className | String | To define custom class using className prop | | dangerouslySetInnerHTML | html | With `dangerouslySetInnerHTML` you can insert html inside the linkParser tag | | title | String | Title prop to provide a title to the linkParser tag | | onClick | Function | You can also use onClick method with the this prop | | style | linkParserStyle() | You can give style by calling linkParserStyle() function from `src/utils/link-parser-style.tsx` component. | Arguments for **linkParserStyle** are: buttonHoverColor, buttonTextHoverColor, buttonColor, buttonTextColor, linkTextHoverColor, linkLinkColor, linkTextColor, ## modelInternalName Create a constant object that contains the content model name passed in the API, ensuring that it returns the corresponding data from the content library. Whenever a user creates a new model in the admin panel for a new widget, make sure to append the model name in `src/utils/constants-model-internal-name.ts`. For example, if we have created a new model in the admin panel named 'Blog Details', add a new key-value pair as `blog_details: "blog_details"` to the `modelInternalName` object in `src/utils/constants-model-internal-name.ts` <Warning> #### Warning It is necessary to provide the correct value in `modelInternalName` as it is used to retrieve data from the API. The name should be identical, with all capital letters converted to lowercase and all space between words replaced with underscores. ( **\_** ) </Warning> ## getColorDefaultValueObject This functionality is utilized to pass the default color value to the color-picker widget.The component `getColorDefaultValueObject` can be found in `src/utils/color-default-object.ts` file. It requires two parameters. 1. **value:** This parameter is used to specify the default color value to be set in the color-picker. 2. **defaultValue:** This parameter is used to reset the modified color value back to its default in the color-picker. > **Note:** > This function is only utilized in the widget file when the user integrates a color picker within that widget. ## expColorObjectParser The `expColorObjectParser` is a useful component in `src/utils/color-object-parser.ts` when user needs a color picker in their trait. It is utilized in the component file located at `src/components/cms-library/component-folder` (e.g., **title-section**) in the **component.tsx** (e.g. **title-section.tsx**) file. Within this file, user receive a prop that contains the color base data, and the `expColorObjectParser` function returns the specific color name that the user has selected from the color picker. Let me provide an example to illustrate its usage: ```js theme={null} const ExpComponentName = (props: ExpComponentNameProps) => { const { headingColor, descriptionColor } = props; const headingStyle: React.CSSProperties = { color: expColorObjectParser(headingColor), }; const descriptionStyle: React.CSSProperties = { color: expColorObjectParser(descriptionColor), }; return ( <div> <h1 style={headingStyle}>Here Comes Heading</h1> <p style={descriptionStyle}>Here Comes description</p> </div> ); }; ``` Simply pass the prop as a parameter to `expColorObjectParser` and it will return the color that the user can utilize as demonstrated above. ## convertCurrency This component converts the amount to the specified currency. It can be imported from `src/utils/currency-converter` and can take two arguments: 1. The price of the product. 2. The currency rate, which can be obtained through an API. # Base theme introduction Source: https://help.experro.com/theme-development/overview/base-theme-introduction Now that the base theme is up and running locally on your computer, it is time to get an overview of the core concepts. **Learning about these concepts will help you understand the platform better and customize the platform exactly as per your needs.** The base theme is a React application created using `create-react-app` with a few modifications for a better user experience. Next, let's understand the [folder structure](./folder-structure) to get an overview of what is included in the base theme. # Base theme source files Source: https://help.experro.com/theme-development/overview/base-theme-source-files Since you will be spending most of your time in the `src` folder during development, it is important to understand the files and folders it contains by default. In the upcoming sections of the documentation, you'll find more information about these files and folders. For now, here is the table that will guide you with each file's purpose: | Folder | Purpose | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assets` | Contains the icons, images, fonts, and SCSS files that compile at the runtime and are used within code. | | `components` | Contains predefined React components specifically crafted for you. This includes but is not limited to a carousel, accordion, product details, and many more. | | `index.scss` | Global styles. | | `index.tsx` | Entry point. | | `interfaces` | Application-wide interface and types. | | `routes` | Contains additional routes which are not created from the Admin Panel. | | `templates` | Collection of templates or layouts used by all pages in base theme. Refer [Templates](../theme-templates/introduction) documentation for more info. | | `utils` | Contains useful utilities files and functions. | Now that you are familiar with the files in the `src` folder, let's understand how they all work together in terms of [execution flow](./execution-flow). # Components and widgets Source: https://help.experro.com/theme-development/overview/components-and-widgets <Tip>In Experro Visual Builder mode, you can EASILY **drag-and-drop** the component from the side panel to the Draggable area.</Tip> Components & Widgets serve as the backbone of Experro, providing essential elements for crafting captivating web experiences. By understanding their purpose and functionality, you gain the power to create visually stunning and interactive websites. <Info>In the base theme, components are considered as basic building blocks that can represent different UI elements such as banners, carousels, and more. Each component in the base theme has its own dedicated component file to encapsulate its functionality and styling. By organizing components into separate files, it allows for modularity and reusability within the theme development process.</Info> <Info>In the context of the base theme, widgets refer to the icons displayed in the right sidebar when the UI Builder is opened. These widgets are associated with the components created in the `cms-library` directory of the base theme. Each widget represents a specific component and allows users to drag and drop that component onto the page being edited in the UI Builder. The widgets provide a visual representation of the available components and facilitate the process of adding components to the page layout.</Info> ## Unleash Your Creativity with Visual Builder, Stress-Free When you drag-and-drop a component, the placeholder content of that component in the Draggable area shows up. The Panel also displays the properties of that selected dragged component. You can change the properties of the dragged component from this Panel including color, alignment, visibility, etc. Have fun exploring Visual Builder and try your hands on various tools! Be rest assured, the changes you make won't be saved. Feel free to make modifications and simply refresh the page to revert back to the original theme. You can learn more about the Components in [Components](../theme-components/about-components) section. Behind the scenes, when you're using a component from the Panel, you're actually using the widget that is associated with the component. You can learn more about widgets in [Custom Droppable Widgets](../theme-components/custom-droppable-widgets) section. Now that you have a basic idea of Components and Widgets, you can start exploring. # Development environments Source: https://help.experro.com/theme-development/overview/development-environments The workspace within which the setup and configuration of software tools, frameworks, and resources exists that enables the developers to create and test their eCommerce platform. It provides a controlled and optimized environment for the development process, facilitating efficient coding, collaboration, and deployment. Experro's theme supports various development environments to accommodate different preferences and requirements of developers. These environments are designed to streamline the theme customization and extension process, ensuring smooth development workflows and high-quality outcomes. ## What are the Two Development Environments? Experro Storefront offers two default environments to working with the base theme. 1. Application (Default) 2. Experro Visual Builder ### Type 1 - Application (Default) <img alt="Base theme running in application mode" /> The base theme runs in *application* development environment by default. You need a configuration file to change the development environment from one to another. In the base theme folder, you will see a file `.env.development.local` that contains the below configuration. ```txt theme={null} REACT_APP_BUILD_TARGET=app REACT_APP_STORE_URL=http://localhost:8080/ REACT_APP_STORE_TOKEN=http://localhost:8080/ ``` The `REACT_APP_BUILD_TARGET` environment variable can be set to either `app` or `app-ui-builder`. ### Type 2 - Experro Visual Builder Change the value of `REACT_APP_BUILD_TARGET` from `app` to `app-ui-builder` and re-run the base theme. You should see the base theme with Draggable area on left side and Visual Builder Panel on right side to drag-and-drop the possible components. <img alt="Base theme running in Experro Visual Builder mode with Draggable area on left and Visual Builder Panel on right" /> The most important part of the base theme is the Components and Widgets. In the next section, let's take a look at [Components and Widgets](./components-and-widgets). # Execution flow Source: https://help.experro.com/theme-development/overview/execution-flow Now that you have understood the purposes of folder structure and base theme's source files, it's not over yet! Next, we will guide you with how to execute these files. The normal React application created using `create-react-app` renders the app using the `render()` method. But the base theme is different. If you open the `index.tsx` file, you wouldn't find a call to the `render()` method. Instead, you should see a call to the `App()` method. ```tsx theme={null} import { App } from 'experro-storefront'; // ...other imports App({ templates, widgets: WidgetConfig.widgets, components, singleDataModelsToPrefetch: ['header'], routes: Routes, headerComponent: components.Header, footerComponent: components.Footer, }); ``` ## Where is This Method Imported From? This `App()` method is imported from `experro-storefront` package. The `experro-storefront` or Experro Storefront is the engine responsible for rendering the base theme and providing many helpful features. As we go through the documentation, we'll discover more about these features provided by Experro Storefront. However, let's begin with one to get started. Experro Storefront provides two default environments to work with. Let's get you familiar with these development environments in the [next section](./development-environments). # Folder structure Source: https://help.experro.com/theme-development/overview/folder-structure The base theme consists of a bunch of files and folders that form its structure. It includes configuration files and sub-folders commonly found in React applications. The following table will guide you with the purpose of each file/folder: | File/Folder | Purpose | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `public` | Contains image and other asset files to be served as-is when you build the base theme. | | `src` | Source files for the base theme. You will spend most of your time here. | | `.env.example` | Sample environment variables file. | | `.editorconfig` | Configuration for the code editors. For more information, visit [EditorConfig](https://editorconfig.org/) website. | | `.eslintignore` | Specifies the files and folders that ESLint should ignore. | | `.eslintrc.js` | Specifies the rules for [ESLint](https://eslint.org/) to check against. | | `.gitignore` | Specifies the files and folder that Git should ignore. | | `.nvmrc` | Specifies the Node version to use with NVM. | | `.prettierrc` | Configuration file for [Prettier](https://prettier.io/) formatter. | | `package.json` | Configures the npm package dependencies that are available to the base theme. For more information, refer to npm's [package.json](https://docs.npmjs.com/files/package.json) documentation. | | `README.md` | Introductory documentation for the base theme. | | `tsconfig.json` | Contains TypeScript configuration for the base theme. Refer TypeScript's [TSConfig](https://www.typescriptlang.org/tsconfig) documentation for more info. | Next, let's explore what is [inside the `src`](./base-theme-source-files) folder of the base theme. # About components Source: https://help.experro.com/theme-development/theme-components/about-components Components are indeed the fundamental elements of a base theme. ## Role of Theme Components in Base Theme **They serve as the building blocks for creating sections and pages within the theme.** The base theme typically includes default components such as image fields, text fields, forms, and carousels, which can be used out-of-the-box to construct different sections or pages. ## Types of Theme Components 1. Default Components 2. Custom Components By leveraging the default components, you can easily assemble and customize the content of your base theme. However, if the provided components don't meet your specific requirements, you also have the flexibility to create custom components and seamlessly integrate them into the base theme. With base theme, you'll get following set of default components. | Name | Purpose | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | [Common](./Common-Components.md) | Collection of common components such as button, modal, form controls, etc. | | [CMS Library](./CMS-Library-Components.md) | Collection of CMS components that you can drag-n-drop from Visual Builder panel such as accordion, carousel, banner, etc. | | [eCommerce](eCommerce-Components.md) | Collection of eCommerce components such as cart, checkout, product details, etc. | > You are going to see the `index.ts` file in each of the component folders. We use `index.ts` as an entry point to **export** something. In addition to these components, you will also find header and footer components. You can view the complete list of available components in the `src/components/index.ts` file. You are not limited to the set of components provided by the base theme. You can easily create [custom component](./custom-components) to fulfill your specific requirements, and also register these components as draggable within the Panel. Custom components enable you to extend the functionality and appearance of the base theme, allowing you to tailor it to your specific needs. These custom components can be designed and developed to complement the existing default components, offering enhanced flexibility and versatility for creating unique sections and pages within the base theme. Let's take a look at [common components](./common-components) and see what is provided by the base them for you to utilize. # Cms library components Source: https://help.experro.com/theme-development/theme-components/cms-library-components The CMS Library components are a set of components available for drag-and-drop functionality in the Visual Builder. These components can be found in the `src/components/cms-library directory`. Here is a quick overview of the CMS library components. | Component | Purpose | | -------------- | ---------------------------------------------------------------------------------- | | Accordion | Draggable accordion component with header, sub header and button at the bottom. | | CTA banner | Draggable full width banner with background image, header, text, and button. | | Hero Carousel | Draggable component with slider effect on set of images. | | Zig Zag Banner | A draggable component to discribe the product with image, title, text, and button. | ..and many more. Next, let's explore the [eCommerce components](./eCommerce-components). # Common components Source: https://help.experro.com/theme-development/theme-components/common-components The collection of common components for the base theme is located at `/src/components/common-components`. File and folders name are in lowercase letters and kebab-case (a convention that follows lowercase format with words separated by dashes) if the name has more than one word. Following is the quick overview of the common components. | Component | Purpose | | -------------------- | ---------------------------------------------------------------- | | `Button` | A button component with loader. | | `LoadingPlaceholder` | Placeholder for data loading. | | `CustomImage` | An image component. | | `Form` | Collection of form controls such as input, checkbox, radio, etc. | | `Modal` | A modal popup component. | These components are used internally by CMS Library components, and you can also utilize these components when creating your [custom components](./custom-components). Next, let's explore the [CMS Library Components](./cms-library-components). # Components best practices Source: https://help.experro.com/theme-development/theme-components/components-best-practices Experro makes it easy to build components and incorporate them into your theme. However, there are certain practices that theme developers should follow for the best results. These practices will enhance the understandability and ease of debugging for custom components. ## Naming Convention In the base theme, the following naming conventions are used: 1. **Directory & File name** (kebab-case): If you want to create a directory with the name "cms library," you would use kebab case, resulting in "cms-library". Examples: `text-input.tsx`, `common-components`, 2. **Component** (PascalCase): When creating a component, the name should be in PascalCase. For example, if you want to create a component named "exp zig zag banner" it would be written as `ExpZigZagBanner`. ## Key Aspects to Consider When creating a component for `cms-library` or `e-commerce` in the base theme, you can follow the directory structure as explained in the [Folder Structure](../overview/folder-structure) documentation. Let's consider the example of the `zig-zag-banner` component: **Step 1** - Navigate to the `cms-library` directory in the `src` folder. **Step 2** - Create a new folder named `zig-zag-banner` using kebab case. **Step 3** - Inside the `zig-zag-banner` folder, create a component file named `zig-zag-banner.tsx`. This file will contain the JSX code for the component. ```jsx theme={null} import React from "React"; import ExpZigZagBannerController from './zig-zag-banner-controller' const ExpZigZagBanner: React.FC = () => { return <div>...</div>; }; export default ExpZigZagBanner; ``` **Step 4** - Additionally, create a controller file named `zig-zag-banner-controller.tsx` within the `zig-zag-banner` folder. This file will handle the business logic of the component. ```jsx theme={null} import React from "React"; const ExpZigZagBannerController: React.FC = (props) => { const {id} = props; //components business logic return {id}; }; export default ExpZigZagBannerController; ``` **Step 5** - Create an `index.ts` file within the `zig-zag-banner` folder. This file will import the component file and export it. ```js theme={null} import ExpZigZagBanner from './zig-zag-banner'; export { ExpZigZagBanner }; ``` **Step 6** - Finally, make sure to import the `zig-zag-banner` component in the `index.ts` file located in the `components` directory. ```js theme={null} //...other imports import { ExpZigZagBanner } from './cms-library/zig-zag-banner'; const components = { //... other components ExpZigZagBanner, } export default components; ``` By following this structure, you can ensure proper organization of your component files and their respective imports within the base theme. ### Built-in Services and Fields Experro not only offers its users with convenient services but also provides built-in features and input fields that greatly improve performance and enhance code. For instance, there are tools like `ExpCustomImagerendrer`, `ExpLinkParser` specifically designed to assist with image rendering and handling various types of links, regardless of whether they are internal or external. These tools can be seamlessly integrated into your projects, making them easier to manage and ensuring optimal results. ### Use Built-in Constants When working with a CMS, it's better to use predefined constants instead of creating your own text values. You can find all the available predefined constants in the "ExpConstant" section. Using constants is beneficial because users can reuse them easily and it also helps prevent spelling mistakes. ```js theme={null} { type: CHECKBOX, label: 'Image Reverse', name: 'bannerReverse', }, ``` Users can also utilize additional constants in their components and widgets. ## Ensure Your Integration is Up-to-date Experro improves the product consistently and works on new ways for various software to connect with it. The latest version of the software allows other applications to access the most recent information, providing online sellers with more options to create an user experience similar to what they see on their BigCommerce store's control panel. To stay informed about updates, it's a good idea to bookmark the change log. # Custom components Source: https://help.experro.com/theme-development/theme-components/custom-components Experro's Base Theme gives you the freedom to design and integrate your unique custom components seamlessly into the Visual Builder. Unlock endless possibilities and bring your vision to life effortlessly. <Info> #### Tip! Consider looking at the [Component Best Practices](./components-best-practices) for some tips! </Info> To create a custom component, follow these steps to create a basic React component in the `src/components/cms-library` folder: **Step 1:** ```js theme={null} import React from 'react'; const CustomComponent = () => { return ( <div> {/* Add your component's content here */} </div> ); } export default CustomComponent; ``` **Step 2:** Once you have created your custom component, import your custom component in the `src/components/cms-library/index.ts` file and export your component from the same file, as demonstrated in the example below. ```js theme={null} // Import your CustomComponent import CustomComponent from 'path/CustomComponent'; // ...other code export { // ...other exports CustomComponent, }; ``` **Step 3:** After creating your custom component, the next step is to create a widget for it, to make it availabe in Visuals Builder component list. To gain a comprehensive understanding of widgets, please refer to the [Widget](./widgets) documentation. # Custom components with content library Source: https://help.experro.com/theme-development/theme-components/custom-components-with-content-library You can easily integrate data from **Experro's Content Library** into your custom component. To integrate data from the Content Library into your custom component, the first step is to add the below code to the `configObj` in your widget file. ```js theme={null} const configObj = { modelInternalName: 'your_component_model_internal_name', traitConfig: [ { type: 'exp_contentModalPopUp', modelInternalName: 'your_component_model_internal_name', }, ] } ``` You can find the Model internal name of your component in the Experro admin panel when you create a component. Afterwards, you will see a popup on the sidebar where you can select the record for that particular component. When you select a record, you will get the value of that record in the props of your component as **contentModel**. The value will be an object, and you can access it by the following method: ```js theme={null} { PRODUCTION6e3bab01edcd4771ad05203ed79042d69xdt10du_published_version_id: "baaf3cdb-f462-40d8-93f6-41e720b7f8e9-8" content_model_id: "a2285cb8-fa8b-4fcb-83f8-c72c164040bd" content_model_name: "Zigzag Layout" current_version_id: "baaf3cdb-f462-40d8-93f6-41e720b7f8e9-8" current_version_name: "#8" id: "baaf3cdb-f462-40d8-93f6-41e720b7f8e9" published_version_name: "#8" title: "Lorem ipsum" } ``` Once you have received this object, you need to import the **ContentService** from the experro-Storefront npm package. The ContentService provides a function called **getCollectionTypeContentById**, which should be used to retrieve data from Experro's content library. Here's an example of how you can use the **getCollectionTypeContentById** function from the ContentService: ```js theme={null} await ContentService.getCollectionTypeContentById({ id: 'id', versionId: 'current_version_id', modelName: 'model_internal_name', componentId: 'random_keu', ssrKey: `random_id_for_ssr`, enableSSR: true, }); ``` The **id** and **versionId** are obtained from the **contentModel** object, while the **modelName** represents the **model internal name** for the component. <Info> *Note:* The **componentId** and **ssrKey** are random keys that should be unique. </Info> To explore more, you can also use [ExpComponentDataDispatcher](../other/theme-utilities) to integrate the Experro's content library data easily. Or if you want to discover how to use [Droppable Widgets](./droppable-widgets), you can click the link. # Custom components with free form Source: https://help.experro.com/theme-development/theme-components/custom-components-with-free-form To make your component interactive and add options on the sidebar of the Visual Builder for entering data, you need to add the relevant options in the Widget file of that component and make necessary modifications in the Component as well. To add a text box on the side bar of the Visual Builder, you need to include the following code in the Widget file. ```js theme={null} const configObj = { headingText: '', traitConfig: [ { type: 'exp_text', internalName: 'headingText', displayName: 'Heading Text', }, ], }; ``` Up next, you will need to pass this object as an attribute in the widget file, as demonstrated in the following example. ```js theme={null} const configObj = { headingText: '', traitConfig: [ { type: 'exp_text', internalName: 'headingText', displayName: 'Heading Text', }, ] } const CustomComponentWidget = Widget.createWidget({ component: CustomComponent, label:"<div class='gjs-fonts gjs-f-b1 custom-widget'>Custom Component</div>", category: 'Basic Components', content: '<CustomComponent/>', widgetName: 'CustomComponent', widgetProperties: { defaults: { name: 'Custom Component', attributes: { component_content: JSON.stringify(configObj); }, activeOnRender: true, }, }, }); ``` In the above example, you can see that the `configObj` is added to the attributes. This inclusion ensures that the text box will be rendered on the sidebar of the Visual Builder. You can then access the value of the text box in your component as a prop. Here's an example of how you can add multiple options by passing them in the `traitConfig` array. ```js theme={null} const configObj = { headingText: '', subHeadingText: '', traitConfig: [ { type: 'exp_text', internalName: 'headingText', displayName: 'Heading Text', }, { type: 'exp_text', internalName: 'subHeadingText', displayName: 'Sub Heading Text', }, ] } ``` Next, let us guide you with how to add [Custom Components Using Content Library](./custom-components-with-content-library). # Custom droppable widgets Source: https://help.experro.com/theme-development/theme-components/custom-droppable-widgets In the Visual Builder environment, you can effortlessly move components by dragging and dropping them from a Widget. When you drop a Widget into a frame, it displays an initial version of the component that you can manually populate with data. Here, we will explore how to drag and drop Widgets that have a feature called **Free Form**. With this amazing feature, you can manually enter data instead of relying on automatic inputs. ## Steps for How to Drag-and-Drop Custom Components: **Step 1** - Search for the Widget that you want to drag and drop. <img alt="image.png" /> **Step 2** - Once you find the Widget, drag and drop it onto the draggable area. When you drop the widget, it will display the initial form of that particular component. Here, we have dropped a component. So, the initial format for the free-form based component looks as follows. Here, we have selected a component, which contains: 1. Background Image 2. Heading 3. Button <img alt="image.png" /> **Step 3** - Now select the **free-form** from the drop-down menu. Once you select free-from, it shows few input fields. Whatever you write in those fields will reflect in the component. If you want to add image then you can do so manually or you can select it from **Media Manager**. Here we are going to add image manually. <img alt="image.png" /> **Step 4** - You can also style them with the given options. For example, you can change the button color or text styles. <img alt="image.png" /> This was all about Widgets and its types. Next, let us guide you with integrating [Custom Image](./custom-image) in the document. # Custom image Source: https://help.experro.com/theme-development/theme-components/custom-image ## Importance of Custom Image Renderer Don't we all agree that when information is presented in a visual/graphical format, it creates deeper impact on the user! This enhances the UX (User Experience) altogether. <Info> **Improving user experience helps in:** * Increasing user retention * Decreasing bounce rates on your website </Info> To add image support in website, a user can use [`Custom Image Renderer`](#custom-image-renderer). This component helps in handling images from the admin panel. ## Custom Image Renderer `ExpCustomImageRenderer` renders custom images based on different configurations and data sources. It accepts various props such as imageData, dataSource, contentLibraryImageData, and others to customize the image rendering. The component handles two data sources: `CONTENT_LIBRARY` and `FREE_FORM`. If the data source is `CONTENT_LIBRARY`, it uses an image parser utility to parse the contentLibraryImageData and extract relevant image information. If the data source is `FREE_FORM`, it iterates over different view types (desktop, tablet, mobile) and processes the imageData accordingly. The `ExpCustomImageRenderer` component is utilized when components have a `dataSource` as `FREE_FORM`, regardless of whether they also have `CONTENT_LIBRARY`. It is designed to handle both cases seamlessly. The `ExpCustomImageRenderer` component accepts the following props: | Prop | Details | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `imageData` | An object or string representing the image data. All you need is to pass image key or you can pass its zeroth postion that you get from API response. | | `dataSource` | A string indicating the source of the image. It can be either `CONTENT_LIBRARY` or `FREE_FORM`. If set to `CONTENT_LIBRARY`, the component uses the `imageData` object as the source. If set to `FREE_FORM`, the component handles the image data differently. | | `contentLibraryImageData` | A string representing the image data specifically for the `CONTENT_LIBRARY` source. | | `staticWidthArr` | An array containing static width values for the image. | | `height` | The height of the `<img>` element. | | `width` | The width of the `<img>` element. | | `alt` | The alt (alternative) text for the image. | | `title` | The title text for the image. | | `lazyLoad` | The flag to load the image lazyly | Here is an example to show the usage of `ExpCustomImageRenderer`. ```jsx theme={null} // This indicates the width of array based on screen size const staticWidthArr: string[] = ['1232', '980', '1144', '600']; <ExpCustomImageRenderer imageData={imageData} dataSource={dataSource} contentLibraryImageData={mappingObj?.bannerImageLink} staticWidthArr={staticWidthArr} height="790" width="616" alt="Excore" title="Excore" /> ``` These props provide configuration options to control the image rendering, including the image source, dimensions, types, alt text, and title. They allow for customization and flexibility in displaying images within the `ExpCustomImageRenderer` component. Head to the next document to learn more about the [Menu Component](./menu-component) in this base theme. # Droppable widgets Source: https://help.experro.com/theme-development/theme-components/droppable-widgets As the name suggests, this document will help you understand how integrate/implement the draggable and droppabale widgets. Let's see how you can use drag and drop widgets from the **Content-Library**. On the right side of the screen, you'll find the side panel which contains different categories like **Basic Components** and **Theme Components**. Inside these categories, you'll find various widgets such as videos, maps, and more. ## Steps to Drag-and-Drop Component and Selecting Record: **Step 1** - Search for the widget that you want to drag and drop. <img alt="image.png" /> **Step 2** - Once you find the widget, drag and drop it in canvas/frame. Once you drop the widget, it displays the initial form of that particular component. Here we have dropped `Hero Carousel` component which displays "Please Select a Record" that is an initial format for Content-Library. <img alt="image.png" /> **Step 3** - Now select the record from the side panel. These records are the one that user have created in admin panel. <img alt="image.png" /> **Step 4** - Once you have selected the record, it will display in the canvas. You can also edit the content inside the component with the 'Properties' options that are shown in the side panel. For example, we have changed the color of the button **Shop Now**. <img alt="image.png" /> So, this is how you can drag and drop any widget that Content-Library contains to your web page. Now let's learn how to inegrate [Custom Droppable Widgets](./custom-droppable-widgets) in your web page. # eCommerce Components Source: https://help.experro.com/theme-development/theme-components/eCommerce-components eCommerce components are **ready-to-use components** created for common eCommerce functionalities including but not limited to cart, product details, checkout, etc. The components are located at `src/components/e-commerce`. Following is the quick overview of a few eCommerce components. | Component | Purpose | | ---------------- | --------------------------------------------------------------------------- | | Product Detail | Product details component with product image, review, variants, share, etc. | | Checkout | Checkout component. | | Compare Products | A component to compare the two products. | | Product Price | Product price component with actual and discount price. | ...and more. Now that you have understood the use of eCommerce components, let us go forward with learning the use of [Custom components](./custom-components). # Exp image Source: https://help.experro.com/theme-development/theme-components/exp-image The base theme introduces a custom Image component called "ExpImage", designed to deliver optimized images according to your specifications. Additionally, it offers various customization options to tailor the image precisely to your requirements. ## Importance of ExpImage Don't we all agree that when information is presented in a visual/graphical format, it creates deeper impact on the user! This enhances the UX (User Experience) altogether. <Info> **Improving user experience helps in:** * Increasing user retention * Decreasing bounce rates on your website </Info> To add image support in website, a user can use [`ExpImage`](#expimage). This component helps in handling images from the admin panel. ## ExpImage The `ExpImage` component is responsible for rendering customized images based on different configurations. It accepts a variety of props including src, name, height, width, alt, title, style, lazyLoad, retina, preLoad, options, navigationUrl, and navigationTarget. Many of these attributes mirror those typically used in standard HTML image tags. The `ExpImage` component accepts the following props: | Prop | Details | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `src` | Image data you which you are getting from the admin panel or a simple image link will also work same a HTML image tag. | | `name` | The name of the image, if you are using this component for multiple times in same component or page then make sure you pass a unique name | | `height` | The height of the `<img>` tag. | | `width` | The width of the `<img>` | | `height` | The height of the `<img>` element. | | `alt` | Alt text for the image | | `title` | Title for the image | | `style` | To provide a inline style for image | | `lazyLoad` | The flag to load the image lazy by default value for this will be `false`. | | `preload` | The flag to preload image, by default value for this will be `false`. If you want to `prealod` the image then you need to pass `true` for the component | | `className` | Class names which you want to apply to the image tag you can pass it to this prop as a string | | `retina` | This boolean value will be specifying the to add 2x images to srcSet for Retina display | | `options` | This prop will be used to specify the image options for the picture tag and the image optimization. | Here is an example to show the usage of `ExpCustomImageRenderer`. ```jsx theme={null} // This indicates the width of array based on screen size const options: string[] = [ { width: 1920, }, { width: 1024, }, { width: 768, aspect_ratio: "16:10", crop_gravity: "west", }, { width: 568, aspect_ratio: "16:13", crop_gravity: "west", }, { width: 450, aspect_ratio: "16:16", crop_gravity: "west", }, ]; <ExpImage src={imageData} options={options} height="790" width="616" alt="Excore" title="Excore" preload={true} />; ``` ##### The object within the options array can contain multiple values as illustrated below: ```js theme={null} { /* * Parameter: breakPoint Units: Pixels * breakPoint will be useful, when all the options object have a breakPoint for the options array for ExpImage component, * if not found then it will use the default breakPoints, which you can find in ExpImage Component. * */ breakPoint?: number; /* * Parameter: width Units: Pixels Default: auto * Resize the output image to the given width maintaining the current aspect ratio. * */ width?: number; /* * Parameter: height Units: Pixels Default: auto * Resize the output image to the given height maintaining the current aspect ratio. * */ height?: number; /* * Parameter: aspectratio **_Default**: auto * Crop the output image to match the given aspect ratio. The default origin point (gravity) is positioned on the center of the image. * */ aspect_ratio?: string; /* * Parameter: quality Units: Number Range: 0-100 Default: 85 * Determines the compression level of the resulting image with 100 being the lowest level of compression and 0 being the highest. * Higher compression means smaller files, but might visually degrade the image (e.g. JPEG compression under 70 tends to produce visible artefacts. * */ quality?: number; /* * Parameter: sharpen Units: Boolean Default: false * Sharpen the output image. * */ sharpen?: boolean; /* * Parameter: blur Units: Number Range: 0-100 Default: 0 * Blur the output image. * */ blur?: boolean; /* * Parameter: crop Units: Pixels Format 1: width,height Format 2: width,height,x,y * Crop the output image to the given width and height. Two formats are accepted. Format 1 one only includes the width and height of the crop. * Format 2 also includes the X and Y position where the crop should start. Image resizing with the width and height parameters is processed after the crop and the resized measurements apply. * If only width and height are given, the Crop Gravity parameter will be used. * */ crop?: string; /* * Parameter: cropgravity **_Default: center * Values**: center,forget,east,north,south,west,northeast,northwest,southeast,southwest * Set the gravity of the crop operation. This is used with the Format 1 cropping only and snaps the crop to the selected position. * */ crop_gravity?: string; /* * Parameter: flip Units: Boolean Default: false * Flip the output image vertically. * */ flip?: boolean; /* * Parameter: flop Units: Boolean Default: false * Flip the output image horizontally * */ flop?: boolean; /* * Parameter: brightness Units: Number Range: -100-100 Default: 0 * Adjusts the brightness of the output image. This can either brighten or darker the image. * */ brightness?: number; /* * Parameter: saturation Units: Number Range: -100 - 100 Default: 0 * Adjusts the saturation of the output image. Use -100 for grayscale. * */ saturation?: number; /* * Parameter: hue Units: Number Range: 0-100 Default: 0 * Adjusts the hue of the output image by rotating the color wheel. * The default value of 0 is the base color and increasing the value modulates to the next color for each 33 change. * */ hue?: number; /* * Parameter: contrast Units: Number Range: -100 - 100 Default: 0 * Adjusts the contrast of the output image. * */ contrast?: number; /* * Parameter: sepia Units: Integer Values: 0 - 100 Default: 0 * Changes the image color to the sepia color scheme. * */ sepia?: number; } ``` Head to the next document to learn more about the [Menu Component](./menu-component) in this base theme. # Menu component Source: https://help.experro.com/theme-development/theme-components/menu-component The base theme provides a Menu component that allows the creation of a dynamic menu based on the provided `menu-id` obtained from the Admin Panel. In this base theme, you can take a look at `header.tsx` file to view a working example of the same. ```js theme={null} <nav className="header-navigation"> <ExpMenu menuLinkObj={pageData.globalSettings?.header_com} ulClasses="flex align-center primary-navigation" liClasses="nav-item" linkNameClasses="nav-link flex align-center" keyValueForMenu="primary_navigation_menu_id_et" iconForNavChild={ <i className="icon menu-arrow-icon"> <IconArrowDown /> </i> } index={0} /> </nav> ``` Navigation menus are commonly created using an unordered list (`<ul>`) and list items (`<li>`). Each list item represents a menu item or a link in the navigation. This structure provides a semantic and accessible way to represent a navigation menu. | Props | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `menuLinkObj` | An object contains the `id` of the navigation created in Admin Panel. <br /> e.g. In the `Header` component, you can see that we are retrieving data from the `pageData` object, and within that, we access the `globalSettings` property which contains information about the `header`. This is where the navigation menu ID is specified.<br /> | | `ulClasses` | To style the main `<ul>` element of the navigation menu, apply a CSS class using the `className` attribute. | | `liClasses` | It works same way as `ulClasses` but for the list-item (`<li>`). | | `linkNameClasses` | Accepts the name of class(es) to apply on the `<Link />` tag. You can view how `<Link>` works in `base-theme` at [Link Parser](../other/theme-utilities#linkparser). | | `childMenuItem` | The `ExpMenu` component works recursively. Whenever a child menu is created, the `ExpMenu` component is called again, which in turn returns a child `<ul>` element. This recursive behavior allows for the creation of nested menus or submenus within the navigation menu structure. | | `keyValueForMenu` | In the `header` menu, the data is being fetched from `pageData.globalSettings.header_com`. The `header_com` object contains all the information about the header component, including the menu ID. To access the menu ID, you need to provide the corresponding key. Take a look at [Header Menu Object](#headermenuobjectexample), In our case it will be `primary_navigation_id_et`. <br /> | | `iconForNavChild` | You can provide an icon which you want to show in the menu item. | | `index` | In the context of recursion, the `index` parameter refers to the level of recursion being performed. By providing an initial value of zero, it will be incremented by one with each recursive call. This can be useful for tracking the depth or level of the recursion and performing specific actions or applying different styles based on the current recursion level. | ```json theme={null} globalSettings: { header_com :[ { "node_type": "child", "id": "ZW3YF6DRwL7E", "primary_navigation_id_et": "5fd774b8-15ad-4ac2-960f-7406c6e0df31", "created_at": "2023-06-20T08:45:12.325Z", "modified_at": "2023-06-20T08:45:12.325Z", "_version_": "1769210661176344576" } ] } ``` Refer `header.tsx` and `menu.tsx` in the base theme for a detailed understanding of how the `index` parameter is used in the code. # Traits Source: https://help.experro.com/theme-development/theme-components/traits Traits serve as the fundamental elements for customizing the sidebar of the Visual Builder for the selected component. They empower developers to tailor the sidebar of the Visual Builder for a specific component, **unlocking endless possibilities for customization**. ## Categories of Traits Experro-Storefront provides you with two categories of traits: **1. Default traits** **2. Customizable traits** ### Category 1 - Default traits Default traits are the **simplest and most straightforward method** to generate the sidebar of the Visual Builder for a specific component. Experro-Storefront offers a wide range of default traits. As follows: 1. **TEXT** The text trait is utilized **to render a textbox** on the sidebar of the Visual Builder. This trait allows you to access the value entered in the textbox as a prop within your component. You can use this trait by following the example shown below: ```js theme={null} import { Widget } from 'experro-storefront'; import { CustomComponent } from '../../custom-component'; const CustomComponentWidget = Widget.createWidget({ component: CustomComponent, label:"<div class='gjs-fonts gjs-f-b1 custom-widget'>Example Component</div>", category: 'Basic Components', content: '<CustomComponent/>', widgetName: 'CustomComponent', widgetProperties: { defaults: { name: 'Example Component', attributes: { exampleText: '', }, activeOnRender: true, traits: [ { type: 'text', label: 'Example text', name: 'exampleText', } ] }, }, }); export default CustomComponentWidget; ``` As shown in the example above, an array of traits has been added in the [widget](Widget.md) file of the component. Within that array, an object is included. The type property is used to display the trait on the sidebar, the label property represents the label for the corresponding element, and the name property is utilized to access the value inside the component. <Info> To access the value of the trait within the component, it is essential to pass the name attribute in the widget's attributes. Failure to include the name attribute will result in the inability to retrieve the trait's value in the component. </Info> 2. **NUMBER** The number trait is utilized **to render a number input** on the sidebar of the Visual Builder. ```js theme={null} traits: [ { type: 'number', label: 'Example number', name: 'exampleNumber', } ] ``` 3. **CHECKBOX** The checkbox trait is used **to render a checkbox** on the sidebar of the Visual Builder. ```js theme={null} traits: [ { type: 'checkbox', label: 'Example Value', name: 'exampleValue', valueTrue: 'yes', valueFalse: 'no', } ] ``` 4. **SELECT** The checkbox trait is used **to render a drop down** on the sidebar of the Visual Builder. ```js theme={null} traits: [ { type: 'select', label: 'options', name: 'options', options: [ { id: 'opt1', name: 'Option 1'}, { id: 'opt2', name: 'Option 2'}, ] } ] ``` ### Category 2 - Customizable traits Customizable traits share similarities with default traits but provide additional features and functionalities. The implementation process for customizable traits is a bit different. Customizable traits inherit all the types from default traits and **include the following additional types**. 1. **TEXT** The Customizable text trait is the same as the default trait text, but with some additional features. We will disclose those features further in this section. To use a customizable trait, please refer to the example below: ```js theme={null} const configObj = { headingText: '', traitConfig: [ { type: 'exp_text', internalName: 'headingText', displayName: 'Heading Text', }, ] } const CustomComponentWidget = Widget.createWidget({ component: CustomComponent, label:"<div class='gjs-fonts gjs-f-b1 custom-widget'>Custom Component</div>", category: 'Basic Components', content: '<CustomComponent/>', widgetName: 'CustomComponent', widgetProperties: { defaults: { name: 'Custom Component', attributes: { component_content: JSON.stringify(configObj); }, activeOnRender: true, traits: [ { type: 'experro-storefront', name: 'component_content', }, ], }, }, }); ``` As discussed in the documentation for [creating a custom component using free form](./custom-components-with-free-form), it is necessary to include a configObj in the widget file of your custom component. Subsequently, you should pass the stringified version of that object as the component\_content attribute when defining the component's attributes. In addition to that, we need to include a trait array, as shown in the example above. 2. **TEXT AREA** The TEXT AREA trait works the same as the TEXT trait; the only difference is that it **renders a text area**. ```js theme={null} const configObj = { descriptionText: '', traitConfig: [ { type: 'exp_textArea', internalName: 'descriptionText', displayName: 'Description Text', }, ] } ``` 3. **CHECKBOX** The CHECKBOX trait is used **to render a checkbox** on the sidebar of the UI builder. ```js theme={null} const configObj = { check: '', traitConfig: [ { type: 'exp_checkbox', displayName: 'Check', internalName: 'check', }, ] } ``` 3. **COLOR PICKER** The Color picker trait is used **to add a color picker** to the sidebar of the UI builder. ```js theme={null} const configObj = { headingColor: '#191919', traitConfig: [ { type: 'exp_colorPicker', internalName: 'headingColor', displayName: 'Heading Color', defaultValue: '#191919', }, ], } ``` 4. **DROPDOWN** This trait is used **to render a dropdown** on the side bar of the UI builder. ```js theme={null} const configObj = { headingSize: '', traitConfig: [ { type: 'exp_dropDown', displayName: 'Heading size', internalName: 'headingSize', options: [ { name: 'Heading 1', value: 'h1' }, { name: 'Heading 2', value: 'h2' }, { name: 'Heading 3', value: 'h3' }, { name: 'Heading 4', value: 'h4' }, { name: 'Heading 5', value: 'h5' }, { name: 'Heading 6', value: 'h6' }, ], }, ], } ``` 5. **DATA SOURCE DROPDOWN** If you want to integrate data support from both the Content Library and Free form into your component, then you can use the data source dropdown trait. This trait will render a dropdown on the sidebar of the UI builder with two options: 1. Free From 2. Content Library ```js theme={null} const configObj = { dataSource: '', traitConfig: [ { type: 'exp_dataSourceDropDown', }, ] } ``` There will be no `internalName` property for this trait. You can access the value from this trait using the fixed key `dataSource`. 6. **CONTENT MODEL POPUP** If you want to **use or integrate data from the contentLibrary**, the `CONTENT MODAL POPUP` trait is required to display the list of records on the sidebar of the UI builder for that component. ```js theme={null} const configObj = { modelInternalName: 'internal_name_for_component', traitConfig: [ { type: 'exp_contentModalPopUp', modelInternalName: 'internal_name_for_component', } ] } ``` One need to add the `modelInternName` of the component in its config, as shown in the above code snippet. 7. **IMAGE SELECTOR** The IMAGE SELECTOR trait is used **to add an image selector** to the sidebar of the UI builder. ```js theme={null} const configObj = { internalName: 'internal_name_for_component', traitConfig: [ { type: 'exp_imageSelector', internalName: 'imageData', dependent: 'dataSource', subDependency: 'freeForm' } ] } ``` **CONDITIONAL RENDER A TRAIT** You can also render a trait conditionally, which means that you can choose to display a trait only when there is a value in another trait. Just follow the example below. ```js theme={null} const configObj = { descriptionText: '', traitConfig: [ { type: 'exp_textArea', internalName: 'titleText', displayName: 'Title Text', }, { type: 'exp_textArea', internalName: 'descriptionText', displayName: 'Description Text', dependent: 'titleText', } ] } ``` In the above example, there is a property called `dependent` in the traitConfig. In the dependent property, you can see that the internalName of the above object is given. This means that the `description text` trait will only be rendered when there is a value in `title text`. ```js theme={null} const configObj = { descriptionText: '', traitConfig: [ { type: 'exp_textArea', internalName: 'titleText', displayName: 'Title Text', }, { type: 'exp_textArea', internalName: 'descriptionText', displayName: 'Description Text', dependent: 'titleText', subDependency: 'example, } ] } ``` In the above example, you can see one more property called 'subDependency'. This example indicates that the `descriptionText` trait is dependent on `titleText` and will only render when the value of `titleText` is exactly the same as the value specified in the `subDependency` flag. # Widgets Source: https://help.experro.com/theme-development/theme-components/widgets To make your custom component available on the sidebar of the Visual Builder, you will need to use the Widget tool provided by the `experro-storefront` package. This tool facilitates the integration of your component into the Visual Builder's interface. ```js theme={null} import { Widget } from 'experro-storefront'; ``` A widget has a method called **createWidget** which is used to make your component available on the sidebar of the Visual Builder. ## Example of a Widget Let's see a basic example to understand it better. ```js theme={null} import { Widget } from 'experro-storefront'; import { CustomComponent } from '../../custom-component'; const CustomComponentWidget = Widget.createWidget({ component: CustomComponent, label:"<div class='gjs-fonts gjs-f-b1 custom-widget'>Example Component</div>", category: 'Basic Components', content: '<CustomComponent/>', widgetName: 'CustomComponent', widgetProperties: { defaults: { name: 'Example Component', attributes: {}, activeOnRender: true, }, }, }); export default CustomComponentWidget; ``` The component, content, and widgetName values should match the name of the component which is used to create a widget. Ensure that you pass the component name exactly as shown in the example, specifically in the content field. The `label` property determines the appearance of the widget in the side panel of the Visual Builder. It consists of three class names, all of which are required for proper display. Once you have completed these steps, you will be able to see your component in the sidebar of the Visual Builder. For detailed instructions on how to make your component interactive and configure options for your component from the sidebar, please refer to the [Component With Free Form Support](./custom-components-with-free-form). # Blog Source: https://help.experro.com/theme-development/theme-templates/blog The base theme enables you to host and manage a **dedicated blog section**, where you can effortlessly write, publish, and share articles, news, and other informative content. It comes with default support to host the blog for your web application. ## Blog Templates Within templates, the base theme includes two specific templates for the blog: * `blog-page.tsx` * `blog-detail.tsx` ```txt theme={null} src └── templates ├── blog ├── blog-detail.tsx ├── blog-item.tsx ├── blog-listing.tsx └── blog-page.tsx ├── template.ts └── template-list.ts ``` You will get a field called a **relation field** that will enable you to establish relationships between two blog content models created in the Admin Panel. This field enables various types of relations, such as many-to-many, one-to-many, many-to-one and one-to-one. ## Blog Content Model in Experro Admin In the Admin panel, a workspace is already equipped with a pre-defined content model specifically designed for the blog section. This content model includes the necessary fields and configurations to manage and display the blog content effectively. To utilize the Blog page functionality in the base theme, you need to create a record in the **Web-pages** content model with a page-slug of `/blog/`. <Info>This setup should align with the instructions and visual reference provided in the accompanying screenshots below.</Info> <img alt="image.png" /> <img alt="image.png" /> Once you have a clear understanding of the Blog functionality in the base theme, you can make any necessary modifications to suit your specific requirements. #### Content Library > Blog Section <img alt="image.png" /> #### Content Model > Blog Section <img alt="image.png" /> In the pre-defined content model for the blog section in the Admin panel, there are two fields of the relation field type. <br /><br />These fields are: 1. **Author**: This field allows you to associate a blog post with the author or creator of the post. 2. **Categories**: This field allows you to assign one or multiple categories to a blog post, helping organize and classify the content. <img alt="image.png" /> #### Relation field for Categories Content Model <img alt="image.png" /> As shown in the above image, we can arrange the relationship between Category and Post to many-to-many relationship. This indicates that multiple blog posts can be associated with a single category, and a single blog post can be associated with multiple categories. It allows for a flexible and versatile categorization of blog posts based on various topics or themes. <img alt="image.png" /> <img alt="image.png" /> ## BlogPage Component To access the `blog` template in the `base-theme`, you can navigate to the following directory structure. ```txt theme={null} src └── templates ├── blog ├── blog-detail.tsx ├── blog-item.tsx ├── blog-listing.tsx └── blog-page.tsx ├── template.ts └── template-list.ts ``` In the Admin Panel, the `blog-page`(`blog-page.tsx`) template needs to be assigned to all the `categories` and `author` records in order to display the blog content correctly. <img alt="image.png" /> The `blog-page` template in the base theme contains a component that handles the listing of blog posts when the page assigned with the `blog-page`. ```js theme={null} import ExpBlogListing from "./blog-listing"; const BlogPage = ({ pageData, components }) => { return ( <> // ... <DraggableArea style={{ width: "auto" }} cssClass="" id={"blog-page-drop1"} components={components} modelField="" pageData={pageData} /> <ExpBlogListing pageData={pageData} /> </> ); }; ``` #### BlogListing Component The `blog-page` template in the base theme utilizes the `ExpBlogListing` component, which receives the `pageData` as a prop. In the `blog-listing` component, there are two important functions that need to be considered for manipulating how the blog data is fetched and displayed on the `blog-page` template. These functions are responsible for fetching the blog data and c #### Content Library > Blog Section <img alt="image.png" /> #### Content Model > Blog Section <img alt="image.png" /> In the pre-defined content model for the blog section in the Admin panel, there are two fields of the relation field type. <br /><br />These fields are: ontrolling its rendering on the page. By modifying these functions, you can customize the data you get from the Admin Panel. ```js theme={null} const getAPIQueryObject = () => { let queryObject = { fieldKey: "idid", fieldValue: "*", modelInternalName: "posts", fieldsToQuery: "summary_et,page_slug,page_title_esi,thumbnail_image_emd,publish_date_edsi", sortBy: "created_at", sortType: "asc", contentDataSortBy: "created_at", relationField: "categories_exp_rel,author_exp_rel", relationFieldDataToQuery: "page_slug,title", skip: "5", limit: "5", }; return queryObject; }; ``` <br /> ```js theme={null} const getFilterString = () => { let filter = ""; if (pageData.content_model_internal_name === "categories") { filter += `categories_exp_rel:(${pageData?.content_model_data_id})`; } if (pageData.content_model_internal_name === "author") { filter += `author_exp_rel:(${pageData?.content_model_data_id})`; } return filter; }; ``` | **Function** | **Description** | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **getAPIQueryObject** | This function is responsible for preparing an object for the API payload. It retrieves the data for the `Post` content model from the Experro Admin, including all the records related to posts. This function helps organize and structure the data in a format suitable for the API requests and subsequent usage in the application. <br /> <br /> To fetch data from the Experro Admin for the `posts` content model, including the related `category` and `author` information, you need to provide the necessary values in the query object. This allows you to retrieve the desired data from the specified content model, along with its associated `category` and `author` data. <br /> <br /> **realtionField** : <br />This key, when provided with a specific value, instructs the query to fetch the data of the content model along with the related data from other content models that are associated with it. This allows you to retrieve the interconnected data and access the related content model's data within the main content model's data. <br /> **Example,**<br /> In the code snippet above, we are fetching the data of the `posts` content model. Additionally, we want to retrieve the data of the `category` content model and the `author` content model, which are related to the `post` records. This allows us to access and include the related data of the `category` and `author` content models when fetching the "post" data. <br /> `relationField:'categories_exp_rel,author_exp_rel'` <br /><br /><br /> **relationFieldData**: <br /> The `relationFieldData` key allows you to specify the fields of the related content models that you want to retrieve. By providing the desired field names in the `relationFieldData` key, you can fetch the specific data from the related content models that are associated with the `posts` content model. <br /> **Example,** To retrieve the `page_slug` and `title` fields for the related content model associated with the `posts` record, specify those fields in the query's `relationFieldData` key for the related content model (`related_content_model`).<br />`relationFieldDataToQuery: 'page_slug,title'` | | **getFilterString** | The **Blog-page** template is designed to be assigned to records of content models such as **Categories**, **Author**, and the main **Blog Page**. The **Blog-page** record itself is created in the **web-pages** content model with a `page-slug` value of `/blog/`. <br /> <br /> In the `getAPIQueryObject` function, there is a condition that distinguishes whether it is a main **Blog-page** or not. In the case of a other page, we need to fetch and display the posts that belong to the specified **category** or **author**.To specify whether the page is related to the `categories` content model or the `author` content model from `pageData?.content_model_internal_name`, we add an additional key to the `apiData` object called `filter`. <br /><br /> This `filter` key contains information about the content model type and the `content_model_data_id`. It uses the `category_exp_rel` value when it is related to the `categories` content model. You can refer to the `getFilterString` function to understand more about how this filter string is constructed. | > #### Blog-Detail Page For Blog-Detail page, template is already created in the the base theme, you need to use a template named `blog-detail.tsx`. This template should be assigned to the records of the `posts` content model in the Experro Admin panel. This assignment will ensure that the `blog-detail` template is used to render the individual blog post pages. For a better understanding of the implementation details, you can refer to the code in the base theme template directory. The code will provide more insights into how the `Blog` functionality is implemented. # Channel specific templates Source: https://help.experro.com/theme-development/theme-templates/channel-specific-templates As Experro allows the creation of multiple [Channels](../other/channel-information#channel-information) for a workspace, you can create a template for a specific **Channel** and assign it to that **Channel** only. This template will be available exclusively for that particular **Channel** and will not be accessible in other channels. For information on how templates work in Experro, you can refer to [Default-Templates](./default-templates) and [Custom-Templates](./custom-templates). To create channel-specific templates, follow these steps: 1. Create a normal `<template_name>.tsx` file under the `src/templates` folder. 2. Register that **template** in the `src/templates/templates.ts` file. Here, you will see other **templates** being `imported` and `exported`. This is the initial step for creating templates specific to a channel in Experro, just as simple as you've seen for [Custom-Templates](./custom-templates). The next step is crucial for creating a channel-specific template. Open the `template-list.ts` file, which looks like this: ```js theme={null} const getTemplates = (templates: any) => { const experroTemplateMap = { 'default': { // Default channels Templates // ...existing templates 'FAQ Template': { component: templates['FAQPage'], displayName: 'FAQs', }, 'Product Details Default': { component: templates['ProductDetailsExp1'], displayName: 'Product Details Default', } } }; }; ``` Here, we have an object `experroTemplateMap`: ```js theme={null} const experroTemplateMap = { 'default': { // Default channels Templates // ...existing templates 'FAQ Template': { component: templates['FAQPage'], displayName: 'FAQs', }, 'Product Details Default': { component: templates['ProductDetailsExp1'], displayName: 'Product Details Default', } } }; ``` In that object, the first key `default` indicates that all the templates registered under this `default` key will be available by default for the `Default Channel` and all other channels. This will remain the case until we provide any **channel-specific** templates. > To create a **channel-specific** template, you need to have the **channel ID**, which you can get from [Channel Details](../other/channel-information#channel-details). Just copy it and create a new object key for `experroTemplateMap`. For example, if you want to create a specific `Product Details` template for a second channel, different from the default channel, follow these steps: 1. Create a `<template_name>.tsx` file for the new template. 2. Update the `experroTemplateMap` to include a new key for the channel ID. <Warning> Ensure that each **channel-specific** template has a unique display name.</Warning> Here’s how your updated `experroTemplateMap` will look: ```js theme={null} const experroTemplateMap = { 'default': { // Default channel templates // ...existing templates 'Product Details Default': { component: templates['ProductDetailsExp1'], displayName: 'Product Details Default', } }, 'ad7e9f63-6532-4e2a-9adf-fb312a635ffe': { // Channel-specific templates 'Product Details Exp 2': { component: templates['ProductDetailsExp2'], displayName: 'Product Details Exp 2', } } } ``` In this example, the default `Product Details` template is available for the default channel, while the `Product Details Exp 2` template is specific to the channel with ID `ad7e9f63-6532-4e2a-9adf-fb312a635ffe`. So, For the **channel** with **ID** `ad7e9f63-6532-4e2a-9adf-fb312a635ffe`, Experro will load the **Product Details Exp 2** template instead of the **default** Product Details Default template. This allows you to have channel-specific templates while falling back to the default templates for other channels. That's only few steps need to perform to create a Channel specific templates. # Custom templates Source: https://help.experro.com/theme-development/theme-templates/custom-templates If default templates are not enough, base theme support and provide a way to create custom templates. With just a few steps, you can easily create a custom template. Let's follow these steps by creating a custom template for the FAQs page. **Step 1** - Create a new file with name `faq-template.tsx` in `templates` folder. **Step 2** - Add the following code in this newly created file. ```tsx theme={null} const FAQPage = ({ pageData, components }: FAQPageProps) => { return ( <div className="page-body"> <div className="page-content"> {/* ... */} </div> </div> ); }; export default FAQPage; ``` As mentioned in the [default templates](./default-templates), by default all the template accept two props - `pageData` and `components`. If the FAQ template allow to drag-n-drop the component, we need to add the `<DraggableArea />` component from `experro-storefront` package. ```tsx theme={null} import { DraggableArea } from 'experro-storefront'; const FAQPage = ({ pageData, components }: FAQPageProps) => { return ( <div className="page-body"> <div className="page-content"> {/* ... */} <DraggableArea style={{ width: 'auto' }} cssClass={''} id={'faq-page'} components={components} modelField={''} pageData={pageData} /> </div> </div> ); }; export default FAQPage; ``` Make sure that the `<DraggableArea />` component must have the unique `id` value in the template page. > The usage of the `DraggableArea` component in `template` is optional and determined by the theme developers based on whether they want to provide `drag-and-drop` functionality for that specific template or not. **Step 3** - Import the created `FAQTemplate` component in `templates.ts` file. ```jsx theme={null} // ...existing imports import FAQPage from './faq-page'; export default { // ...existing export FAQPage, }; ``` **Step 4** - Finally, in this step, add template in `template-list.ts` file. In this file, you can define the template with custom name that you want to display in the Admin Panel. ```tsx theme={null} const getTemplates = (templates: any) => { const experroTemplateMap = { 'default':{ // Default channels Templates // ...existing templates 'FAQ Template': { component: templates['FAQPage'], displayName: 'FAQs', }, } }, } ``` <img alt="template-list.jpeg" /> Tada! The custom FAQ Template is now ready to use in the base theme as well as in Admin Panel to attach. To learn more about how Routing works in the Base Theme, tap here - [Routing](./routing). # Default templates Source: https://help.experro.com/theme-development/theme-templates/default-templates When you create a new page (or a Record) in the Admin Panel, you'll get an option to use (or attach) the template with the new page. <img alt="MicrosoftTeams-image (16).png" /> Based on this association, the page content and layout will show up. In the base theme, the default templates are located in `src/templates` folder. The template list, you're seeing in the Admin Panel matches with the list of templates mentioned in `src/templates/template-list.ts` file. This file contains the existing list of the default templates. `cms-page.tsx` or CMS Page Template is the default template. When you create a new page in the Admin Panel, the CMS Page Template is by default attached with the new page unless you specify other template. Default template component has the access to `pageData` and `components` props. In template component, you should see the following basic structure: ```tsx theme={null} const HomePage = ({ pageData, components }: HomePageProps) => { return ( <div className="page-body"> <div className="page-content"> {/* ... */} <DraggableArea /* ... */ /> {/* ... */} </div> </div> ); }; export default HomePage; ``` The `pageData` contains the information of the global settings, page title, description, etc. whereas `components` contains the information about the dragged components in the Visual Builder Draggable Area. The dragged components are rendered using by `<DraggableArea />` from `experro-storefront`. Theme developers have the freedom to create [custom templates](./custom-templates) according to their specific needs and requirements, allowing for complete control over template creation. # Introduction Source: https://help.experro.com/theme-development/theme-templates/introduction # About Theme Templates Templates are internally used by all the pages in the base theme. When you visit a page such as `/sale` or `/blog`, the associated template is executed. Template gives you the *layout* of the page. So, that you only have to worry about the content of the page and not the layout or structure of the page. Base theme supports two types of templates: | Type | Description | | ---------------------------------------- | -------------------------------- | | [Default Templates](./default-templates) | Templates comes with base theme. | | [Custom Templates](./custom-templates) | Templates that you create. | To learn in-depth about the Default and Custom Templates, click on the above hyperlinks. # Routing Source: https://help.experro.com/theme-development/theme-templates/routing Routing in React refers to the process of defining and managing the different paths or URLs of a web application and rendering the appropriate components based on the current URL. Base theme support two types of routing. 1. Dynamic Routing 2. Custom Routing ## Type 1 - Dynamic Routing Base theme provides *dynamic routing* based on *page slug* provided in the Experro admin panel. Let's assume that we're interested in creating an *About Us* page in our base theme. Login into the Experro Admin Panel and add a new web page with `Record Name` and `Page Slug` values. <img alt="Creating-page-page-slug.png" /> With this, you now have the `/about-us/` route in Base theme and it is handled *dynamically* by base theme and Experro Storefront. You just need to hit that route with the respective domain name to view that page with page-slug. However, it's important to note that the specific record associated with that route(page-slug) needs to be published in order for it to be accessible. ## Type 2 - Custom Routing With custom routing, you can attach the route to specific template in base theme. Let's understand the custom routing with an example. In `templates` folder we have one file with name `blog-list.tsx` and we want to display the content of this file when user visit the `/blog-list` route. We just need to register the template against route in `route-list.tsx` and Experro Storefront will handle the remaining. The `route-list.tsx` is located at `src/routes` file. ```txt theme={null} src └── routes ├── index.ts └── route-list.tsx ``` If you open this `route-list.tsx` file, you should see an array with name `Routes`. This array is collection of custom routes defined as an object. Add an object for `/blog-list` route in this object using the following code: ```js theme={null} import { Page } from 'experro-storefront'; import components from '../components'; import templates from '../templates'; import BlogList from '../templates/blog-list'; const Routes = [ // ... other routes entry. { path: '/blog-list', key: 'blog-list', element: ( <Page components={components} templates={templates} componentToLoad={BlogList} key={'blog-list'} /> ), }, ] export default Routes; ``` `Page` component from `experro-storefront` is responsible for rendering the template for given custom route. TRoutinghe `Page` component accepts a `component`, `templates`, `componentToLoad` (template that we're interested to render), and unique `key` props.