> Synerise Documentation — AI Hub > > This file contains the complete "AI Hub" section of the Synerise documentation. Each article begins with a top-level "# " heading. The manifest listing all sections is at https://hub.synerise.com/llms-full.txt # Introduction and requirements Recommendations allow users to present unique AI-powered item recommendations through several channels in order to promote items and encourage customers to make a purchase. We use the AI engine to acquire information from your website and analyze large portions of data which is mainly customers' activity (visits to a website, purchases, historical data, and information included in the product feed). This way the Synerise application can produce relevant recommendations that match preferences of customers and circumstances of displaying the recommendation frame. In Synerise, a user can show recommendations within the following channels: - on the website (through [dynamic content](/docs/campaign/dynamiccontent)) - [emails](/docs/campaign/e-mail) - [web push notification](/docs/campaign/Webpush) - [mobile push notifications](/docs/campaign/Mobile) - mobile applications built based on [Documents](/docs/assets/documents) ## Business applications --- 1. Monetize customers' data and interactions to personalize experience across multiple touchpoints in different communication channels including web, mobile application, email, and many others. 2. Boost conversion at any step of customer journey from home page, category or item page, to cart, to post-purchase activities. 3. Generate top quality real-time recommendations for both recognized, unrecognized, and first-time customers based on various types of interaction. 4. Configure, launch, and deploy models to run and monitor performance of recommendations with only a few clicks with a simple user interface. 5. Tailor recommendation results to your business needs with recommendation configuration settings, including A/B testing, advanced filtering, boosting, and sorting options. 6. Benefit from state-of-the-art machine learning models powered by Synerise proprietary AI engine - Cleora. No need to manually process data ingestion and cleansing processes, models parameters tuning or retraining as framework does it for you. ## Requirements ---
To access AI Recommendations and manage recommendations campaign, you must have the following [permissions](/docs/settings/identity-access-management/permissions#permissions): - Permissions from the **Communications > Recommendations** set (at least **Read** to see the campaigns). - All permissions from the **Assets > Catalogs** set.
- [Prepare an item feed](/docs/ai-hub/recommendations-v2/item-feed-requirements) - Use consistent item identifiers in feed and events; events must include the item identifier - [Configure the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations) - Meet the minimum data requirements of interactions and events. For users of multiple workspaces, we provide the option to train models for a workspace using data from other workspaces in situations where a data shortage in the target workspace prevents model training. This option is available for training the following recommendation models: [Personalized](/docs/ai-hub/recommendations-v2/recommendation-types#personalized), [Section page recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#section-page), [Attribute recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#attribute), [Cross-sell and Cart recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#cross-sell-and-cart-recommendations), [Next interaction](/docs/ai-hub/recommendations-v2/recommendation-types#next-interaction).
The minimum requirements are approximate and allow model training. Meeting the minimum requirements does not ensure optimal operation. The quality of AI models increases with input data volume.
Recommendation type Minimum requirements Recommended requirements
- Personalized
- Section
- Attribute
- Next interaction 		- At least 1,000 unique profiles who visited a product page more than once.
- At least 10,000 of one of the following: - Optionally, you can additionally select custom events for model training.		 - 50,000 unique profiles who visited a product page more than once (at least two different items).
- 1,000,000 in total of page.visit events from item pages, product.view events from item views in a mobile application, and transaction.charge events
- The title and category item attributes must be selected as training attributes in the configuration of the AI engine (Synerise > Settings > AI Engine Configuration).
- To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint .
- Similar items1
- Item comparison		 At least one item attribute must be selected in the training attributes section in the AI engine configuration (Synerise > Settings > AI Engine Configuration). The title and category item attributes must be selected as training attributes in the configuration of the AI engine (Synerise > Settings > AI Engine Configuration).
- To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint
Visual similarity - Packshot images defined in the item catalog
- Image resolution of at least 640x480px		 - Packshot images defined in the item catalog
- Image resolution of at least 640x480px
- To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint
- Cross-sell
- Cart recommendations		 At least 1,000 transactions with basket size > 1 - At least 25,000 transactions with basket size > 1
- To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint
- Last seen
- Recent interactions		 No requirements To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint
Top items At least 10,000 page.visit events or transaction.charge events with at least 10 unique products To collect recommendation statistics, you must generate a recommendation.click event, which is triggered when a request is sent to the "Item clicked in recommendation" endpoint
1Similar item recommendations can be created with only the item feed, but events are recommended to build a more effective model. ## Limits Item feed limits: - For [visual similarity](/docs/ai-hub/recommendations-v2/recommendation-types#visual-similarity) recommendation model, the item feed can contain up to 1,000,000 items, regardless of the item feed type. The following are the default limits: - Maximum number of active recommendation campaigns: 1,000 - Maximum number of active and draft recommendation campaigns: 10,000 - Maximum number of AI recommendation models: 25 - Maximum number of items in recommendation: 100 - Maximum length of a filter (IQL string): 10,000 characters The following are the permanent limits (cannot be changed) per a recommendation. The limits apply both for filtering and boosting options: - Maximum number of unique segmentations: 1 - Maximum number of unique aggregates/expressions: 2 - Maximum number of unique customer attributes: 20
Multiple occurrences of the same analysis (a segmentation, expression, aggregate) or attribute count as one towards the limit.
## You may want to read --- - [Recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types) - [How to create recommendation](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign) - [How to use filters in recommendations](/docs/ai-hub/recommendations-v2/recommendation-filters) - [Recommendation statistics](/docs/ai-hub/recommendations-v2/recommendation-statistics) # Implementing promotions This article provides information regarding implementing the Promotions feature: - [Promotion statuses](#promotion-statuses) to show you the possible promotion statuses and explain the circumstances in which a promotion is assigned with a specific status. - [Implementation variants](#promotion-implementation-variants) to show you the possibilities of implementing the promotion calculation logic, features, requirements, and implementation guide for each implementation variant - [Displaying promotion](#displaying-promotions) to show you the methods of displaying and distributing promotions in the channels of your choice ### Promotion scopes When creating a promotion, you can select the group of customers (audience) who are eligible. The promotion's scope can be: - for [selected items](/docs/ai-hub/promotions/creating-promotions) - You can create a promotion for selected items or group of selected items. - for [entire basket](/docs/ai-hub/promotions/creating-promotions-for-entire-basket) - You can create a promotion applied to total value of transaction. ## Promotion statuses --- When you create and publish a promotion, it can get the following statuses in a Synerise database:
Promotion statuses in Synerise database
Promotion statuses in Synerise database
### Assigned A promotion with this status can be [displayed in the distribution channels of your choice](/docs/ai-hub/promotions/introduction-to-promotions#displaying-promotions). When a promotion receives this status in the database, it means that one of the scenarios occurred: - the system found the recipients for the promotion who meet the requirements defined in the [Audience section](/docs/ai-hub/promotions/creating-promotions-for-entire-basket#audience) of a promotion right after [publishing the promotion](/docs/ai-hub/promotions/creating-promotions-for-entire-basket#saving-a-draft-or-publishing). This occurs automatically and in real time as a customer meets the conditions of the promotion. Such a promotion is ready to be activated. - an active promotion has been deactivated and it returned to the assigned status. If the promotion involved redeeming loyalty points, deactivation gives back the number of spent loyalty points to the customer. The following methods deactivate a promotion: | Method | API consumer | Description | Events generated | |---------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-------------------------------------------------------------------------|----------------------------| | [Deactivate a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/DeactivateAPromotion)
`/v4/promotions/promotion/deactivate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you deactivate only one promotion at a time. | [client.deactivatePromotion](/docs/assets/events/event-reference/loyalty#clientdeactivatepromotion) | | [Batch deactivate promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchDeactivate)
`/v4/promotions/promotion/batch-deactivate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you deactivate a number of promotions at a time. | [client.deactivatePromotion](/docs/assets/events/event-reference/loyalty#clientdeactivatepromotion) | | [Deactivate a promotion as a Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/DeactivateAPromotionProfile)
`/v4/promotions/promotion/deactivate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you deactivate only one promotion at a time. | [client.deactivatePromotion](/docs/assets/events/event-reference/loyalty#clientdeactivatepromotion) | | [Batch deactivate promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchDeactivateAsProfile)
`/v4/promotions/promotion/batch-deactivate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you deactivate a number of promotions at a time. | [client.deactivatePromotion](/docs/assets/events/event-reference/loyalty#clientdeactivatepromotion) | ### Active When a promotion receives this status it means the promotion is ready to be applied (for example, for deducting the discount amount from the transaction value, purchasing an item with loyalty points, receiving one item for free, and so on). The promotion can receive this status as a result of the following methods: | Method | API consumer | Description | Events generated | |-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------|--------------------------| | [Activate a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/ActivateAPromotion)
`/v4/promotions/promotion/activate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you activate only one promotion at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion's global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | | [Batch activate promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivate)
`/v4/promotions/promotion/batch-activate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion's global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | | [Activate a promotion as a Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/ActivateAPromotionAsProfile)
`/v4/promotions/promotion/activate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you activate only one promotion at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | | [Batch activate promotion as Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivateAsProfile)
`/v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | ### Redeemed When a promotion receives this status it means that the promotion has been used as many times as the limit allowed and cannot be used again by a customer. A promotion can be redeemed only when it's in [active](#active) status. Redemption of the promotion is optional and it can be done by the methods presented in the table below. Usually, the redemption request is sent from an e-commerce/point of sales. To prevent fraud, execution of the methods is recommended right after the transaction has been made. Optionally, when decide to send a transaction to the Synerise database, you can include an object with the value of the `code` parameter of the promotion in a request body and then Synerise will redeem a promotion automatically (details available in point 4 of the [Full variant process outline](/docs/ai-hub/promotions/introduction-to-promotions#process-outline)). | Method |API consumer |Description | Events generated | |------------------------------------------------------------------------------------------------------------------------------------------|-|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------| | [Redeem a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/RedeemAPromotion)
`/v4/promotions/promotion/redeem` |Workspace (formerly business profile), Synerise User |This method lets you redeem only one promotion at a time. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | | [Batch redeem promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchRedeemPromotions)
`/v4/promotions/promotion/batch-redeem` |Workspace (formerly business profile), Synerise User |This method lets you redeem a number of promotions at once. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | ## Promotion implementation variants --- Before implementing promotions, you must decide on the promotion implementation variant. The distinction between these variants is the location of the promotion calculation logic, either in your backend (point of sale, e-commerce or m-commerce) - partial or within the Synerise platform - full. The specified component is then responsible for recalculating the final transaction value after applying any discounts. #### Features When [creating a promotion](/docs/ai-hub/promotions), you can use the following functionalities for both promotion scopes (selected items and entire basket): | Full variant | Partial variant | |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | supported discount types:
- for entire basket promotions: percentage, amount (for example, -20%, - $20 discounts), and cashback discounts (end user decides how many loyalty points to redeem for a discount when completing a transaction);
- for selected products promotions: setting an exact price, percentage and amount discounts (for example, -20%, - $20 discounts) | supported discount types:
- for entire basket promotions: percentage, amount (for example, -20%, - $20 discounts), and cashback discounts (end user decides how many loyalty points to redeem for a discount when completing a transaction) ;
- for selected products promotions: setting an exact price, percentage and amount discounts (for example, -20%, - $20 discounts) | | limits per users and activations; the following variants are supported:
- promotion available only for a specific number of customers - first come, first served
- promotion available for all customers; which can be used a specific number of times per transaction
- promotion with limits on activations per transaction (for example, a customer can use loyalty points to purchase an item for free, and you can limit the number of items purchased at once) | limits per users and activations; the limits are defined in the promotions in Synerise, but your systems must handle applying the limits | | fixed discounts (the same discount amount for each purchase) or step discounts (each purchase triggers higher discount) | fixed discounts (the same discount amount for each purchase) or step discounts (each purchase triggers higher discount) | | selecting products to be included/excluded from the promotion | selecting products to be included/excluded from the promotion | | selecting points of sales where the promotion is applicable | selecting points of sales where the promotion is applicable | | assigning priority to each promotion (if you use a default logic of not [combining promotions](#combining-promotions)) | assigning priority to each promotion (if you use a default logic of not [combining promotions](#combining-promotions)) | | specific basket value as a promotion trigger (for example, a promotion is applicable for a customer whose transaction value ranges between $20 to $75) | specific basket value as a promotion trigger (for example, a promotion is applicable for a customer whose transaction value ranges between $20 to $75) | | **Only "For selected items" promotion scope:** buy one, get one (BOGO) logic (promotion which enables acquiring specific number of items for free or with a specific discount if a condition is met, for example, a customer purchased X specific items) | **Only "For selected items" promotion scope:** buy one, get one (BOGO) logic (promotion which enables acquiring specific number of items for free or with a specific discount if a condition is met, for example, a customer purchased X specific items) |
Both variants are presented as a baseline and process outlines can be customized to your business needs.
### Full variant Synerise acts as promotion engine where your backend sends the basket items to Synerise, Synerise calculates the final value of the basket (applying the promotions according to the logic, which is unavailable for your backend) and sends back recalculated values. #### Prerequisites - Have customers in your database. - [Implement a tracking code](/developers/web/installation-and-configuration) in the website. This will let you track the activity of your customers except for offline points of sales and mobile applications. - [Implement collecting transaction events in real-time](/first-steps/integration/events#implementing-transactions) - recommended if the redemption of promotions relies on data sent within the transaction event, real-time processing is essential to prevent fraud. - To display promotions through [documents](/docs/assets/documents) and [screen views](/docs/campaign/screen-views) with promotions in a mobile application, implement [mobile SDK](/developers/mobile-sdk/installation-and-configuration). - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise, so you can select items included in a promotion. - Optionally, import a list of stores to [Catalogs](/docs/assets/catalogs), so you can select the stores where the promotion is active. #### Process outline
Full variant implementation
Full variant implementation
1. In Synerise, [create](/docs/ai-hub/promotions) or [import promotions](/docs/ai-hub/promotions/importing-promotions). 2. [Display a promotion](#displaying-promotions) in the communication channel of your choice and if you want to limit the number of redemptions (which is obligatory when a promotion involves spending loyalty points), you need to implement in your communication channel (such as a mobile app, a website and so on) a solution that lets your customers activate a promotion before they use it. Use one of the following methods for implementing this solution: | Method | API consumer | Description | Events generated | |-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------|--------------------------| | [Batch activate promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivate)
`/v4/promotions/promotion/batch-activate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | | [Batch activate promotions as Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivateAsProfile)
`/v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion);
if the promotion global limit has been reached, [client.promotionActivationLimitReached](/docs/assets/events/event-reference/loyalty#clientpromotionactivationlimitreached) is generated instead | 3. During the checkout process: 1. Send a request to Synerise to apply promotions using one of the following methods: | Method | API consumer | Description | Events generated | |-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| | [Process basket](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processSale_POST)
`/v4/promotions/v2/sale/process-sale/{identifierType}/{identifierValue}` | Workspace (formerly Business Profile), Synerise User | This method lets you apply promotions to which a recognized customer is entitled and send back the final transaction value to the shop after discounts. | n/a | | [Process anonymous Profile's basket](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processAnonymousSale_POST)
`/v4/promotions/v2/sale/process-anonymous-sale` | Workspace (formerly Business Profile), Synerise User | This method lets you apply promotions to which an anonymous customer is entitled and send back the final transaction value to the shop after discounts. | n/a | 2. Synerise responds with the final transaction value and transaction details after applying the promotions. 4. After a customer makes a purchase: 1. Record the transaction(s) to Synerise database using one of the methods in the table below. If you skip including the promotion in the transaction, proceed to the next step. If you will send promotion data in the transaction, **contact the Synerise support to enable it for your workspace** and include an object with the value of the `code` parameter of the promotion in the request body, so Synerise can redeem it automatically. For example: 
{
                 "client": {
                   "customId": "string",
                   ...
                 },
                 "metadata": {},
                 "orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
                 "paymentInfo": {
                   "method": "CASH"
                 },
                 "products": [
                   {
                     "cancel": false,
                     "finalUnitPrice": {
                       "amount": 3.25,
                       "currency": "USD"
                     },
                     ...
                   }
                 ],
               "promotionDetails": [
                     {
                       "promotionCode": "b1e794ff-f3b7-4530-aa80-44931eb81f35",
                       "quantityToRedeem": 3
                     },
                     {
                       "promotionCode": "d93a01c3-4c4e-4190-ace0-b4c3a8984f25",
                       "quantityToRedeem": 10
                     }
                   ]
               }
| Method | API consumer | Description | Events generated | |-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | [Create a transaction](https://hub.synerise.com/api-reference/data-management#operation/CreateATransaction)
`/v4/transactions` | Workspace (formerly Business Profile) | This method lets you add a new transaction to Synerise database. | [transaction.charge](/docs/assets/events/event-reference/items#transactioncharge) | | [Batch add or update transactions](https://hub.synerise.com/api-reference/data-management#operation/BatchAddOrUpdateTransactions)
`/v4/transactions/batch` | Workspace (formerly Business Profile) | This method lets you add batch of new transactions or update existing transactions in the Synerise database. | [transaction.charge](/docs/assets/events/event-reference/items#transactioncharge) | 2. Send a request to Synerise to redeem promotion/loyalty points by using the following method. To prevent fraud, this request should be sent as soon as possible. If you included a promotion information in the request that adds a transaction to Synerise, this step can be skipped. | Method | API consumer | Description | Events generated | |---------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|-------------------------------------------------------------|------------------| | [Redeem a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/RedeemAPromotion)
`/v4/promotions/promotion/redeem` | Workspace (formerly Business Profile), Synerise User | This method lets you redeem a promotion and loyalty points. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | | [Batch redeem promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchRedeemPromotions)
`/v4/promotions/promotion/batch-redeem` | Workspace (formerly Business Profile), Synerise User | This method lets you redeem up to 100 promotions and loyalty points at a time. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | #### Rounding prices While executing the [Process basket](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processSale_POST) and [Process anonymous Profile's basket ](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processCheckout_POST) methods, the prices of items after deductions are rounded according to [Bankers Rounding](https://wiki.c2.com/?BankersRounding). #### Combining promotions When a customer is entitled to more than one promotion which are mutually exclusive, you can define the exact behavior depending on the promotion scope. - **For entire basket** - If don't want to combine promotions, select one of the modes: - **Default, no configuration required**: A customer is assigned a promotion with the highest priority (priority is defined in the process of creating a promotion in Synerise). - The engine selects the most beneficial (highest) discount - To apply this strategy, contact Synerise support. - If you want to combine promotions, enable combining the amount of basket discounts assigned to a customer using the [Update settings for current Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/endpointSettingsUpdateSettingsPUT) method, or configure it in the Synerise interface — see [Loyalty](/docs/settings/configuration/loyalty). In the request, include the `saleSettings` object with the parameters that let you enable combining basket discounts and define the settings: - `combineBasketDiscounts` - this parameter lets you enable combining basket discounts, by default this option is disabled (`false`) - `priceValueBaseStrategy` - this object lets you define the base price for subsequent discounts (from the original price or from the price after the first discount) - `discountOrder` - this object lets you define the order of applying discounts for the purposes of the strategy selected in `priceValueBaseStrategy` - **For selected items** If there is more than one promotion applicable for a customer, the system: 1. Calculates the discount from combining the percentage and amount discounts on a given item. If only one of the types exists, the other one is ignored in the calculation. 2. Checks the discount from applying an exact price promotion. 3. Applies one of the above options to maximize the resulting discount for the customer. For example, a customer is entitled to 3 promotions for various items simultaneously (Promotion A, Promotion B, and Promotion C): | | Discount type | Discount value | Item value before | Item value after discount | |-------------|---------------|----------------|--------------------|---------------------------| | Promotion A | Amount | -$5 | $15 | $10 | | Promotion B | Percentage | -10% | $25 | $22,5 | | Promotion C | Exact price | n/a | $14,99 | $11,99 | This means that the system will apply Promotion A and Promotion B, because the combination of percentage and amount discounts gives a customer a $7 discount, whereas the exact price discounts gives only a $3 discount. ### Partial variant Synerise sends the ID of the promotion to your backend and your backend calculates the amount to be deducted from the prices according to the logic defined in the promotion. The promotion must be also created in your backend. #### Prerequisites - Have customers in your database. - [Implement a tracking code](/developers/web/installation-and-configuration) in the website. This will let you track the activity of your customers except for offline points of sales and mobile applications. - [Implement collecting transaction events in real-time](/first-steps/integration/events#implementing-transactions) - recommended if the redemption of promotions relies on data sent within the transaction event, real-time processing is essential to prevent fraud. - To display promotions through [documents](/docs/assets/documents) and [screen views](/docs/campaign/screen-views) with promotions in a mobile application, implement [mobile SDK](/developers/mobile-sdk/installation-and-configuration). - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise, so you can select items included in a promotion. - Optionally, import a list of stores to [Catalogs](/docs/assets/catalogs), so you can select the stores where the promotion is active. - Create a promotion with the same ID as promotion in Synerise in your point of sale. #### Process outline
Partial variant implementation
Partial variant implementation
1. Create a promotion in your shop (for example, cash register). 2. In Synerise, [import promotions to Synerise](/docs/ai-hub/promotions/importing-promotions). 2. [Display a promotion](#displaying-promotions) in the communication channel of your choice and if you want to limit the number of redemptions (which is obligatory when a promotion involves spending loyalty points), you need to implement in your communication channel (such as a mobile app, a website and so on) a solution that lets your customers activate a promotion before they use it. Use one of the following methods for implementing this solution: | Method | API consumer | Description | Events generated | |-------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------------|--------------------------| | [Batch activate promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivate)
`/v4/promotions/promotion/batch-activate` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion) | | [Batch activate promotions as Workspace](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchActivateAsProfile)
`/v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}` | Workspace (formerly business profile), Synerise User | This method lets you activate a number of promotions at a time. | [client.activatePromotion](/docs/assets/events/event-reference/loyalty#clientactivatepromotion) | 4. During the checkout process: 1. Send a request for the list of promotions available to the customer by using the following method: | Method | API consumer | Description | Events generated | |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| | [Get Profile promotions by a custom filter](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/GetClientPromotionsByACustomFilter)
`/v4/promotions/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue}` | Workspace (formerly Business Profile), Synerise User | This method lets you retrieve the list of promotions available to the customer. It is recommended to execute this method during the checkout process. | [client.promotionRequest](/docs/assets/events/event-reference/loyalty#clientpromotionrequest) | 2. Synerise responds with a list of promotions to which a customer is entitled. 4. After a customer makes a purchase: 1. Record the transaction(s) to Synerise database using one of the methods in the table below. If you skip including the promotion in the transaction, proceed to the next step. If you will send promotion data in the transaction, **contact the Synerise support to enable it for your workspace** and include an object with the value of the `code` parameter of the promotion in the request body, so Synerise can redeem it automatically. For example: 
{
               "client": {
                 "customId": "string",
                 ...
               },
               "metadata": {},
               "orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
               "paymentInfo": {
                 "method": "CASH"
               },
               "products": [
                 {
                   "cancel": false,
                   "finalUnitPrice": {
                     "amount": 3.25,
                     "currency": "USD"
                   },
                   ...
                 }
               ],
             "promotionDetails": [
                   {
                     "promotionCode": "b1e794ff-f3b7-4530-aa80-44931eb81f35",
                     "quantityToRedeem": 3
                   },
                   {
                     "promotionCode": "d93a01c3-4c4e-4190-ace0-b4c3a8984f25",
                     "quantityToRedeem": 10
                   }
                 ]
             }
| Method | API consumer | Description | Events generated | |-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | [Create a transaction](https://hub.synerise.com/api-reference/data-management#operation/CreateATransaction)
`/v4/transactions` | Workspace (formerly Business Profile) | This method lets you add a new transaction to Synerise database. | [transaction.charge](/docs/assets/events/event-reference/items#transactioncharge) | | [Batch add or update transactions](https://hub.synerise.com/api-reference/data-management#operation/BatchAddOrUpdateTransactions)
`/v4/transactions/batch` | Workspace (formerly Business Profile) | This method lets you add batch of new transactions or update existing transactions in the Synerise database. | [transaction.charge](/docs/assets/events/event-reference/items#transactioncharge) | 2. Send a request to Synerise to redeem promotion/loyalty points. This request should be sent as soon as possible to prevent fraud. If you included a promotion information in the request that adds a transaction to Synerise, this step can be skipped. | Method | API consumer | Description | Events generated | |---------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|-------------------------------------------------------------|------------------| | [Redeem a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/RedeemAPromotion)
`/v4/promotions/promotion/redeem` | Workspace (formerly Business Profile), Synerise User | This method lets you redeem a promotion and loyalty points. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | | [Batch redeem promotions](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/BatchRedeemPromotions)
`/v4/promotions/promotion/batch-redeem` | Workspace (formerly Business Profile), Synerise User | This method lets you redeem up to 100 promotions and loyalty points at a time. | [client.removePoints](/docs/assets/events/event-reference/loyalty#clientremovepoints) | ## Displaying promotions --- You can display promotions on your website, in a mobile application, or on other devices (for example, digital signage). You can do it in the following ways: - Using the API: | Method | API consumer | Description | Events generated | |-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------------| | [Get a Profile's promotion as Profile](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/GetAClientsPromotions)
`/v4/promotions/promotion/get-for-client` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you retrieve, sort, and filter all promotions available to a profile. To filter by the channel in which you want to display the promotion, use `tagNames` (you must add tags to the promotions when creating them).| n/a | - [Create a document](/docs/assets/documents/creating-documents) that contains a promotion insert in its body and display the document in a mobile application using the following methods: - [Android](/developers/mobile-sdk/method-reference/android/content#generate-document) - [Flutter](/developers/mobile-sdk/method-reference/react-native/content#generate-document) - [iOS](/developers/mobile-sdk/method-reference/ios/content#generate-document) - [React Native](/developers/mobile-sdk/method-reference/flutter/content#generate-document) Example promotion insert: 
{% promotion %} 58b68c6f-b22a-4860-8869-28fe3d529f94 {% endpromotion %}
Where `58b68c6f-b22a-4860-8869-28fe3d529f94` is a UUID of a promotion. ## Define global promotion settings --- You can configure workspace-level settings that apply to all promotions. These include the promotion code format, cashback conversion multipliers and spending limits, basket pricing rules (such as combining promotions and discount order), and security options (such as blocking profiles and promotion request locks). For instructions, see [Loyalty](/docs/settings/configuration/loyalty). # About item feeds in Synerise This article presents item feed requirements for AI features. Before you import item feed to Synerise, become familiar with the feed types, requirements, limits, how you can import the feed and where it will be kept. ## Important to note - Grouping item attributes can be performed on the interface of the Synerise platform during the process of configuring AI engine for: - [AI recommendations](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations) - [AI Search](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search) - [AI predictions](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity) - If you want to use [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) (recommending items from multiple workspaces), your item feed must meet the [requirements of the multibrand workspaces feature](/docs/settings/workspace/multibrand-workspaces/about#general-requirements). ## Feed types AI recommendations make use of the following item feed types: | Feed type | Business application | Method of upload | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Item feed | Used as a source of items for **ALL** [recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types)/search methodologies/prediction models which require item feed
**OR**
used as a source of all common item attributes (such as category, item description, brand, dimensions, product name, photos); when used together with the [supplemental catalog](/docs/ai-hub/item-feed/supplemental-catalog), this catalog enables you to maintain product prices and availability per store/channel. | - [through an API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync) to a catalog (Data Modeling Hub icon **Data Modeling Hub > Catalogs**)
- [through a workflow](/use-cases/import-product-feed-to-catalog) (` CSV ` , ` XML feed ` , ` JSONL ` , ` JSON ` files) to a catalog (Data Modeling Hub icon **Data Modeling Hub > Catalogs**)
- Pulling from an URL as the item feed when [Configuring AI engine for AI recommendations](/docs/ai-hub/recommendations-v2/configure-item-feed-ai-recommendations) ( `Google Merchant Center XML` file) to an AI feed.
This method creates an AI feed that contains your item feed in the **Settings > AI Engine Configuration**. Additionally, it will create an `AI feed` prefixed catalog with the item feed in **Data Modeling Hub > Catalogs** (unavailable for editing). | | [Metadata catalog](/docs/ai-hub/item-feed/metadata-catalog) | Used as a supplementary source of items alongside the item feed for the following recommendation types:
- [section page](/docs/ai-hub/recommendations-v2/recommendation-types#section-page)
- [attribute recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#attribute) | - through a [simple import](/docs/assets/imports/importing-data-to-catalogs) to a catalog,
- [through a workflow](/use-cases/import-product-feed-to-catalog) to a catalog,
- [through an API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync) to a catalog | | [Supplemental catalog](/docs/ai-hub/item-feed/supplemental-catalog) | Used as an additional feed with specialized item attributes: `price` and `availability` for each store/channel | - through a [simple import](/docs/assets/imports/importing-data-to-catalogs) to a catalog,
- [through a workflow](/use-cases/import-product-feed-to-catalog) to a catalog,
- [through an API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync) to a catalog | # Introduction ## What are Predictions? --- Predictions are a codeless AI-powered tool built on the top of Synerise analytics to predict any type of event or action in a customer’s journey. ## Required user permissions --- See [AI Hub permissions](/docs/settings/identity-access-management/permissions/ai-hub-permissions). ## What can you predict? --- ### Regression and Classification predictions --- You can use the Regression and Classification prediction type to predict any type of event or customer’s action that can be calculated in an [expression](/docs/crm/expressions) and produce a numerical or 1/0 (true/false) value. Here are a few examples of what you can predict: - Churn likelihood - Conversion - Open rate (OR) - Click-through rate (CTR) - Click-to-Open rate (CTOR) - Who will visit - Purchases from abandoned basket ### Lookalikes predictions --- You can use Lookalikes for discovering new segments of customers, extending reach, picking the most promising new comers with regard to their similarity to your best customers. The list contains a few examples of what you can discover: - Segment of customers likely to convert to your yearly repeating marketing campaign - The best offline, fresh customers - Best customers in a specific location - And many more ### Propensity predictions --- Propensity predictions let you evaluate how likely customers are to buy products with specific features, such as: - Brand - Category - Color - And many more ### Best Fit predictions --- Best Fit predictions let you determine the most suitable item or value of an item attribute for each customer. ## Key characteristics --- - **Codeless** - Neither ML expertise nor coding are necessary. - **Based on analyses** - You can can base your predictions on already created segmentations or expressions. - **Based on already stored events** - There is no need of additional data ingestion - **Universality** - Predictions are industry-independent - you can use it regardless of industry (telco, banking, retail, ecommerce, and so on) your business belongs to. - **Readiness for multi-level analytics** - You can analyze predictions outcomes both on individual (customer) level and aggregated (segments) level. - **Easily adjustable to your needs** - You can schedule recalculation of predictions. - Predictions can take into account both standard events such as `page.visit` or `transaction.charge` and custom events. ## Reasons to use predictions --- There are many reasons to use Predictions, however, the following seems to be of the highest importance: - Lowering overall communication costs, keeping within the budget (for example, sending a newsletter only to the customers with the highest propensity to perform a certain type of action) - Directing communication precisely (avoiding sending communication to already lost clients) - Unveiling new potential among your existing and new customer base - Improving UX by personalizing communication (you can adjust the content of your messages to the preferences of the recipients) - You can view the change history for this item from its configuration - see [Audit Log](/docs/settings/workspace/audit-log). ## Basic requirements --- ### Regression and classification
Previously referred to as Custom predictions, regression and classification predictions are the current names for the same concept.
Minimum requirements: - `transaction.charge` events from the last 3 months (10.000 events per month), - A segmentation that contains 50.000 profiles, - 500 positive samples (for example, if you want to use this prediction type to predict the likelihood of churn, you will need the historical data of 500 customers who have left) Recommended requirements: - All minimum requirements - Over 1.000.000 `page.visits` - Over 10.000 positive samples (for example, if you want to use this prediction type to predict the likelihood of churn, you will need the historical data of 10.000 customers who have left) - At least 200.000 customers in a segmentation - Other custom events related to the phenomena to be predicted ### Lookalikes Minimum requirements: - A segmentation that contains at least 200 "model" profiles (this will be your [source segmentation](/docs/ai-hub/predictions/lookalikes#select-source-and-target)), - At least one event selected in the Lookalikes settings (part of the [Enabling Lookalikes procedure](/docs/ai-hub/predictions/enabling-predictions#enabling-lookalikes)) - Create an item feed in **Settings > AI Engine configuration** - `product.buy` events from at least one month (more than 10 000 events per month), - The item IDs in the `product.buy` events must be consistent with the item IDs in the item feed Recommended requirements: - All minimum requirements - A segmentation that contains at least 1.000 "model" profiles (this will be your [source segmentation](/docs/ai-hub/predictions/lookalikes#select-source-and-target)), - All events selected in the Lookalikes settings (part of the [Enabling Lookalikes procedure](/docs/ai-hub/predictions/enabling-predictions#enabling-lookalikes)) ### Propensity and Best Fit Minimum requirements: - `product.buy` and `transaction.charge` events from 2 months (more than 10.000 events per month), - Over 100 purchases of items that meet condition of the filters you would like to apply (for example, if you want to narrow down the filters in the settings of the prediction to purses, you will need at least 100 `product.buy` events for purchasing a purse) - [Create an item feed in Synerise and enable the Propensity model for this feed](/docs/ai-hub/predictions/enabling-predictions#enabling-propensity-and-best-fit-predictions) - the item IDs in the `product.buy` events must be consistent with the item IDs in the item feed Recommended requirements: - All minimum requirements - More than 100.000 `page.visit` events - Over 500 purchases of items that meet the conditions of the filters you would like to apply (for example, if you want to narrow down the filters in the settings of the prediction to purses, you will need at least 500 `product.buy` events for purchasing a purse) The more interactions per customer, the better. ## How can I get started? --- 1. [Enable Prediction](/docs/ai-hub/predictions/enabling-predictions). Decide which of the predictions types you would like to enable: - [Lookalikes](/docs/ai-hub/predictions/lookalikes) - [Regression and classification predictions](/docs/ai-hub/predictions/custom) - [Propensity predictions](/docs/ai-hub/predictions/propensity) - [Best fit predictions](/docs/ai-hub/predictions/bestfit) Further steps depend on whether your workspace contains the minimum required data. 3. Once the set-up is ready, it usually takes a few hours to initialize predictions on your workspace. Once the initialization is done, you can make your first prediction.
The best way to learn how to make your first prediction is to head over to this [article](/docs/ai-hub/predictions) and try it out.
# Introduction to AI Search The Synerise AI Search Engine is a powerful tool that can boost the search results relevancy on your website to the next level. There are numerous ways to improve your customers’ experience as well as shorten the path to conversion, from the basic search configuration, through synonyms, ending on query rules. The search engine can also detect typos and perform a search for the corrected query. By using our award-winning algorithms, personalization reranks search results to highlight products that interest your customers the most. Semantic search is better than traditional methods, because it analyzes complete queries to comprehend search intent and meaning. In Hybrid mode, which merges typical keyword approaches with semantic search, it improves overall metrics. ## Benefits --- - Higher conversion - Increased revenue - Strengthened relationship with your customers - Shortened customers' path to conversion - Enhanced searching experience - Gather more information about your customers' behavior - No-code optimization - Personalized search results - Ability to monetize product boosting - You can view the change history for this item from its configuration - see [Audit Log](/docs/settings/workspace/audit-log). ## About search engine --- The search engine is based on indices to speed up the search process. Indices are built from the provided item feeds or [catalogs](/docs/assets/catalogs). When creating an index, you can choose from three [search methods](#searching-methods): keyword searching, semantic searching, or a combination of both. This is what happens after a user sends a search request: 1. Applying **predictive filtering** - if this option is enabled, it provides the most relevant categories based on the past `item.search.click` events. 1. Textual ranking, this includes: - analyzing keyword frequency, semantic analysis, and natural language processing to determine the ordering of search results (depending on the selected [search method](/docs/ai-hub/ai-search/define-search-method-and-ranking)). - indexing - the process of locating relevant documents or data that match the search terms. - low match enhancement - if this option is enabled in the index settings, it adds more items to the search results if there are fewer than 5 items returned. You can find more information how to enable and use this option in ["Matching words" section](/docs/ai-hub/ai-search/define-search-method-and-ranking#matching-words). 2. Item [ranking](/docs/ai-hub/ai-search/define-item-ranking) based on item visits and transactions. 3. The following operations happen at the same time: - Executing [rules](/docs/ai-hub/ai-search/query-rules) condition: Boosting by attribute - Personalization - Applying **dynamic re-ranker** - if this option is enabled, it prioritizes displaying the most popular results for the search query according to the ranking from the last 12 hours. 4. Executing [rules](/docs/ai-hub/ai-search/query-rules) condition: Filter query rules. 5. Executing [rules](/docs/ai-hub/ai-search/query-rules) condition: Promoting and/or hiding items. 6. Applying [query suggestions](/docs/ai-hub/ai-search/query-suggestions). ## Requirements --- ### User permissions See [AI Hub permissions](/docs/settings/identity-access-management/permissions/ai-hub-permissions). ### Minimum requirements - [Upload an item feed to Synerise](/use-cases/import-product-feed-to-catalog) - [Configure AI engine for the item feed](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search) ### Requirements for additional features - To personalize search results, you must: - provide 5 0,000 unique profiles who visited a product page more than once (at least two different items), - provide 1,000,000 in total of `page.visit` events from item pages, `product.view` events from item views in a mobile application, and `transaction.charge` events, - make sure the `title` and `category` item attributes are selected as training attributes in the configuration of the AI engine (**Synerise > Settings > AI Engine Configuration**). - To collect statistics for AI Search performance and A/B/X tests, you must generate an `item.search.click` event, which is triggered when a request is sent to the ["Item clicked in search" endpoint](https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatBatchUsingPOST). - To enable [predictive filtering](/docs/ai-hub/ai-search/predictive-filtering) for the [index](/docs/ai-hub/ai-search/create-index) on the basis of which search will work, see [Predictive filter requirements](/docs/ai-hub/ai-search/predictive-filtering#requirements). - To enable [dynamic reranker](/docs/ai-hub/ai-search/dynamic-reranker) for the [index](/docs/ai-hub/ai-search/create-index) on the basis of which search will work, see [Dynamic reranker requirements](/docs/ai-hub/ai-search/dynamic-reranker#requirements). - To enable [query suggestions](/docs/ai-hub/ai-search/query-suggestions), see [Query suggestion requirements](/docs/ai-hub/ai-search/query-suggestions#requirements) - To use semantic or hybrid search methodology, become familiar with [best practices](/docs/ai-hub/ai-search/introduction-to-ai-search#best-practices-for-semantic-search-implementation). ## Search methodology --- Searching involves different stages and elements, they can be divided in the following way: 1. Creating an index and choosing the [searching method](#searching-methods). 3. Making a [search request](#types-of-search-requests). 4. Presenting the results. Use the data from the search response to show the results on your website or in an application. ### Searching methods When [creating a search index](/docs/ai-hub/ai-search/create-index), you can choose the search methods: - **Keyword** - searching for information using specific words or phrases that are relevant to the desired topic or subject. To take full advantage of it, request full access. - **Semantic** - connects words and phrases to interpret digital content similarly to human comprehension, offering personalized, accurate results. Governed by search intent and semantic meaning, it aims to decode content contextually for precision. By taking a holistic approach, it assesses word meanings and relationships, similar to human language interpretation. The goal is to eliminate irrelevant results for an enhanced user experience. To take full advantage of it, request full access. - **Hybrid** - combines the two approaches, with a weighting ratio of 70% for keyword-based and 30% for semantic search. In practice, this involves the weighted average of two normalized scores. We highly recommend opting for the Hybrid search method as semantic search proves invaluable in situations where keyword-based searches fail to yield satisfactory results. To take full advantage of it, request full access.
These methods are available in the public preview mode.
### Types of search requests - **Full-text search** - The search request is made when the user enters the entire phrase and confirms it. - **Auto-complete search** - A new search request can be made after each keystroke, to offer suggestions while the user is typing. - **Listing** - A search request without a query phrase. The results can be personalized, filtered, and so on, like with the other search types. This can be used, for example, to create a personalized page with items from a particular brand. - **Visual search** - A user can search by providing an image. [Find out more about visual search](/docs/ai-hub/ai-search/visual-search)
Check the details in: - [AI Search configuration](/docs/ai-hub/ai-search/introduction-to-ai-search#prerequisites). - The [API Reference](https://hub.synerise.com/api-reference/ai-search#tag/Search) for search methods.
## Best practices for semantic search implementation - Ensure every product in your item feed has a comprehensive and detailed description. Usually, a few sentences. - Include relevant attributes such as size, color, material, product designation, and unique features. - Use natural language to describe products, avoiding jargon and overly technical terms where possible. - Use the hybrid search mode to combine the strengths of keyword and semantic search. Example: A hybrid search for "summer dresses for beach vacation" returns results both for specific keywords, such as "summer dresses", and for semantically related items, like "lightweight sundresses." - Conduct A/B tests on different search index configurations (for example, keyword vs. hybrid) to determine the best-performing setup. Use the integrated preview and comparison tools to analyze the results in a single view. Example: Test the effectiveness of semantic search on queries like "laptops for graphic design" versus traditional keyword search and compare user engagement metrics. - Regularly monitor the performance of your semantic search implementation. Use Decision Hub to track search success rates and user satisfaction. Example: Track metrics such as click-through rates, conversion rates, and search abandonment rates to gauge the effectiveness of semantic search. ## Configuring AI Search This article describes the process of enabling the AI search engine on a website. First, the feature is configured, then the configuration is implemented so it can become operational. Learn more about capabilities of the feature [here](/docs/ai-hub/ai-search/introduction-to-ai-search).
AI Search Engine will work after delivering the item catalog, however, providing transactional data will improve the personalization of results.
### Terminology explained --- - **Index** - A data structure created from a catalog of items. The index is used by the search engine to look for results that match a query. - **Score** - It is a value that indicates how relevant a search result is for a given query. - **Facets** - Used in search to let customers narrow down search results to items that have common features. ### Prerequisites --- 2. [Import an item feed to **Data Modeling Hub > Catalogs** in the application](/use-cases/import-product-feed-to-catalog).
The value of an item attribute in the item feed or a catalog cannot be longer than 1000 characters. It applies both for creating a new index and updating it.
3. [Configure the AI engine for your catalog](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search). ### Implementation The AI search can be implemented by using these endpoints: - **Autocomplete** - When listening to the input, you can use the autocomplete endpoint in our API to send each keystroke of the customer to the search engine and receive autocomplete results as the customer types. The results need to be rendered in real time in the search box. - **Full-text search** - The search is only performed once, when the customer initiates it by clicking the search button or pressing `ENTER`. The results are usually displayed on a dedicated page. - **Listing** - The search is made without any query. The results can still be personalized, filtered, boosted, and so on.
These search endpoints are available as both GET and POST requests. For details, see the [API Reference](https://hub.synerise.com/api-reference/ai-search#tag/Search).
The requests can be authorized with the same tracker key as used in the tracking code.
It is possible to inject the search by using [Dynamic Content](/docs/campaign/dynamiccontent/introduction-to-dynamic-content).
Example of a search request: 
var xhttp = new XMLHttpRequest();
  xhttp.onreadystatechange = function () {
    if (this.readyState == 4 && this.status == 200) {
        var result = JSON.parse(this.responseText);
        Console.log(result);
    }
  };
  xhttp.open("GET", "https://api.synerise.com/search/v2/indices/{indexId}/query?query={SEARCH_QUERY}&clientUUID={USER_UUID}&token={TRACKING_KEY}", true);
You must send an `item.search.click` event. This enables monitoring the search statistics and preparing search analytics.
You can find the documentation [here](https://hub.synerise.com/api-reference/data-management#operation/publishAiCompatBatchUsingPOST). 
{
     "clientUUID": String,
     "searchType": String,
     "correlationId": String,
     "position": Number,
     "item": String
  }
where: - `clientUUID` is the customer's UUID, - `correlationId` must be have the same value as the `searchId` parameter value. You can source this value from the search response. Thanks to this, you can link a search result with information about which item from that result was clicked. - `position`is the position of the clicked item. **IMPORTANT**: the first position is 1, not 0, - `item` is the ID of the clicked item, - `searchType` is the type of search conducted: full-text search or autocomplete search. ### Limits The following are the default limits per workspace, you can contact Customer Support to request changing them: - Maximum number of search indices: 10 - Maximum number of searchable attributes per index: 40 - Maximum number of facetable attributes per index: 40 - Maximum number of filterable attributes per index: 40 - Maximum number of sortable attributes per index: 20 - Maximum number of rules per index: 1000 - Maximum number of synonyms per index: 1000 - Maximum number of suggestion indices: 10 - Maximum number of segmentations used in rules: 10 You can use up to 10 various segmentations in all rules in one index. Multiple occurrences of the same segmentation count as one towards the limit. - Maximum number of dynamic analyses (aggregates and expressions) to be used in filters: 2 You can use two various aggregates or expressions, or one expression and one aggregate. Multiple occurrences of the same analysis count as one towards the limit. # Implementing Personalized Promotions The Personalized Promotions feature uses the power of our advanced AI engine to generate a unique set of [promotions](/docs/ai-hub/promotions) tailored to the specific preferences of individual customers. To use this feature, create and publish a minimum of 50 promotions for best results, and then create personalized promotions through which our proprietary AI engine selects the most optimal offers for each customer. This AI engine is trained using transaction history data, so the longer transaction history a customer has in Synerise, the accuracy and relevance of the promotions proposed to them increasingly improve. Such promotions are called *personalized promotions*. You may also encounter an older term - _handbill_ - in developer documentation and documentation that refers to technical elements such as APIs and SDKs. Personalized promotions can be distributed: - while customers check in any kind of sales point, for example, scan their loyalty card at the entrance to a store. After such identification, the personalized promotion set can be displayed on digital signage or shown in the customer's mobile app. - while customers check out - in this scenario both recognized and anonymous customers can receive a set of personalized promotions. - **recognized customers** - customers identify themselves with a loyalty card before a transaction, and after payment the cash register prints out the receipt that contains promotions based on customers' transaction history and/or the promotions are available in the mobile application. These promotions can be used during the future purchase. - **anonymous customers** - after customers pay for the purchase, the cash register prints out the receipt that contains promotions based on their transaction to be used during their future purchase. - in a mobile application/website - you can display AI sets of promotions in your mobile application at any time or on your website. ## Prerequisites --- - Create [promotions](/docs/ai-hub/promotions/creating-promotions), for best results, we recommend creating and publishing at least 50 promotions. - Have customers in the database. - [Implement a tracking code](/developers/web/installation-and-configuration) in the website. This will let you track the activity of your customers except for mobile application and offline stores. - To track customer's activity in a mobile channel and distribute promotions there, implement [mobile SDK](/developers/mobile-sdk). - [Implement collecting transaction events in real-time](/first-steps/integration/events#implementing-transactions) - recommended if the redemption of promotions relies on data sent within the transaction event, real-time processing is essential to prevent fraud. - [Import transaction data history](/docs/assets/imports/importing-transactional-data), so the engine can learn. Your transaction data history must be at least three months long. - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise. ## Features When [creating a personalized promotion](/docs/ai-hub/personalized-promotions/creating-ai-promotions), you can use the following functionalities: - AI-engine based promotion or randomized option - You can select whether the promotions displayed within the personalized set are selected at random or by the AI engine. Usually, randomization is used for A/B testing. - A/B testing - You can prepare several variants of the personalized sets of promotions to see which variant is most successful. - Filters for promotions - This option gives you flexibility in tailoring the personalized selection of promotions by using filters to display only promotions with certain parameters. - Basket limits for promotions - You can define the minimum transaction value or number of items from which a customer is entitled to a promotion (available only for checkout). - Excluding items from promotions (available only for checkout). - [Adjusting the AI engine settings](/docs/ai-hub/personalized-promotions/creating-ai-promotions#ai-engine-boosting-settings) (diversity of products in promotions, frequency of delivering the same promotion, boosting promotions with popular items). - Scheduling promotion activity. ## Distributing promotions --- ### On check in To distribute promotions at the entrance, execute the following method right after a customer is identified at the entrance of the shop: | Method | API consumer | Description | Events generated | |----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|--------------------------------------------------------------------------------|------------------| | [Generate handbill for Profile](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/getHandbillForClient_GET)
`/v4/promotions/promotion/get-for-client/handbill/{handbillUuid}` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you retrieve a personalized list of promotions for a customer | [handbill.assign](/docs/assets/events/event-reference/loyalty#handbillassign) | ### On check out To print out a promotion on a receipt right after a transaction is completed, execute one of the following methods: | Method | API consumer | Description | Events generated | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------| | [Process checkout on POS](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processCheckout_POST)
`/v4/promotions/sale/process-checkout/{identifierType}/{identifierValue}` | Workspace (formerly Business Profile), Synerise User | This method lets you print out a set of personalized promotions on a receipt for a recognized customer. The set is generated on the basis of the current purchase and the whole transaction history of a customer. These promotions can be used in the future transaction. | n/a | | [Process anonymous Profile's checkout on POS](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/processAnonymousCheckout_POST)
`/v4/promotions/sale/process-anonymous-checkout` | Workspace (formerly Business Profile), Synerise User | This method lets you print out a set of personalized promotions on a receipt for an anonymous customer. The set is generated on the basis of the purchased items and can be used in the future transaction. | n/a | ### In mobile application To distribute a set of personalized promotions in your mobile application, execute the following method: | Method | API consumer | Description | Events generated | |----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|--------------------------------------------------------------------------------|------------------| | [Generate handbill for Profile](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/getHandbillForClient_GET)
`/v4/promotions/promotion/get-for-client/handbill/{handbillUuid}` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you retrieve a list of personalized promotions for a customer. | [handbill.assign](/docs/assets/events/event-reference/loyalty#handbillassign) | ## Applying promotion logic --- Once the personalized promotions are distributed, customers can use them in the future transactions. Since the personalized promotions are sets of promotions, implement them as described in [Promotion implementation variants](/docs/ai-hub/promotions/introduction-to-promotions#promotion-implementation-variants). ## Displaying promotions --- You can display personalized promotions on your website, in a mobile application, or on other devices (for example, digital signage). You can do it in the following ways: - Using the API: | Method | API consumer | Description | Events generated | |-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------------| | [Generate handbill for Profile](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/getHandbillForClient_GET)
`/v4/promotions/promotion/get-for-client/handbill/{handbillUuid}` | Profile (formerly client), Anonymous profile (formerly client) | This method lets you retrieve personalized set of promotions available to a profile. To filter by the channel in which you want to display the promotion, use tags (you must add tags to the promotions when creating them). | [handbill.assign](/docs/assets/events/event-reference/loyalty#handbillassign) | - [Create a document](/docs/assets/documents/creating-documents) that contains a personalized promotion reference in its body and display the document in a mobile application using those methods: - [Android](/developers/mobile-sdk/method-reference/android/content#generate-document) - [Flutter](/developers/mobile-sdk/method-reference/react-native/content#generate-document) - [iOS](/developers/mobile-sdk/method-reference/ios/content#generate-document) - [React Native](/developers/mobile-sdk/method-reference/flutter/content#generate-document) Example document body request with a reference to a personalized promotion: 
{
      "card": "handbill",
      "promotions": {
        "childSchema": "promotion",
        "uri": "https://api.synerise.com/v4/promotions/promotion/get-for-client/handbill/{personalizedPromotionUuid}"
      }
    }
Where `{personalizedPromotionUuid}` must be replaced with a UUID of a personalized promotion. # Predictions glossary See the ["AI Hub" section in the Synerise Glossary](/glossary?module=ai-hub). # Item feed requirements This article has been moved to [About item feeds in Synerise](/docs/ai-hub/item-feed/about). # Create an index In order to configure AI Search, you need a catalog that contains feed, so the search returns items after a customer types in a query. ## Requirements --- The list of requirements is available [here](/docs/ai-hub/ai-search/introduction-to-ai-search#prerequisites). ## Create an index --- 1. Go to AI Hub icon **AI Hub > Indexes**. 2. Click **Add index**. **Result**: The index creation wizard opens. 3. From the **Choose feed** dropdown list, select an [item feed](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search#adding-item-feed) based on which you would like to create an index. The list includes only [feeds with the search engine option enabled](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search#enabling-ai-search-for-the-feed).
Remember that the value of an item attribute in the item catalog cannot be longer than 1000 characters. It applies both for creating a new index and updating it.
4. From the **Choose search language** dropdown list, select the language of the search. 5. Click **Next step**. 6. Select one of the search methods: - **Keyword** - searching for information using specific words or phrases that are relevant to the desired topic or subject. To take full advantage of it, request full access. - **Semantic** - connects words and phrases to interpret digital content similarly to human comprehension, offering personalized, accurate results. Governed by search intent and semantic meaning, it aims to decode content contextually for precision. By taking a holistic approach, it assesses word meanings and relationships, similar to human language interpretation. The goal is to eliminate irrelevant results for an enhanced user experience. To take full advantage of it, request full access. - **Hybrid** - combines the two approaches, with a weighting ratio of 70% for keyword-based and 30% for semantic search. In practice, this involves the weighted average of two normalized scores. We highly recommend opting for the Hybrid search method as semantic search proves invaluable in situations where keyword-based searches fail to yield satisfactory results. To take full advantage of it, request full access.
These methods are available in the public preview mode.
7. Regardless of the search method type, select the searchable attributes and assign importance to each of them (assigning importance is available only for attributes for keyword method). **Searchable attributes** are used by the search engine to calculate the item's relevance to the query phrase provided by the customer. Attributes can be assigned to three importance levels: high, medium and low. When a word from the phrase matches an attribute, the score amount is assigned depending on importance assigned to the attribute.
It is important to select as searchable attribute those which contain the most descriptive information about the item. Usually these are the `title` or `description` attributes from the item feed. We recommend that on average, the combined length of the selected attribute values to be longer than 50 words.
8. If you want to display unavailable items in the search results, enable the **Include out of stock items** toggle. 8. Click **Next step**. 9. Optionally, you can select item attributes which will be used as response, filterable, facetable, and sortable attributes. - **Filterable attributes** - Attributes for use in item filters for including or excluding results. Including an attribute value narrows down the search results to items with that attribute value. Excluding values of an attribute displays results with items that have different values of these attributes. - **Facetable attributes** - Attributes that can be use as facets. Facets allow customers to sort search results by attributes and their values. For example, you can use the `color` attribute as facetable to let the customers select which colors they're interested in.
To let AI automatically select the most relevant facets per query from this pool, see [Automatic Facets](/docs/ai-hub/ai-search/automatic-facets).
- **Response attributes** - Attributes which will be included in the search response. For each item returned, only attributes defined in this section will be available in the search response such as price, item description, color, size, so you can show them to the customers. We recommend choosing only those attributes that are strictly necessary for intended purposes. - **Sorting attributes** - You can enable sorting the results by the chosen attributes. You can add both range and text attributes. Sorting by range attributes allows you to arrange the returned items from the highest to the lowest value of the specified attribute. Sorting by text attributes allows you to order the results in an alphabetic order, ascending or descending. - **Disabled prefix search** - You can disable the prefix search for specific attributes. This will prevent the search engine from trying to auto-complete the phrase for these attributes. Keep in mind that if the search engine will not find any items for the phrase it will still try to check for typos. 10. In the **Item ranking** section, define the criteria for sorting items in search results. This can be managed using the following three options: - **AI Personalization** - Use the slider to boost search results based on user preferences. - **Page Views** - Use the slider to boost items which were frequently viewed by customers. - **Item Purchase** - Use the slider to boost items which were frequently purchased. 11. Click **Finish**. **Result**: The index has been created. You can additionally configure the [additional index settings](/docs/ai-hub/ai-search) and [access settings](/docs/ai-hub/ai-search/change-index-access-settings). # Configuring item feed for recommendations The article has been removed to [Configure AI engine for Recommendations](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations). # Enabling predictions To be able to create predictions, you must enable them first. ## Enabling Lookalikes --- The [Lookalikes](/glossary/#lookalikes) model allows you to compare two groups (*source* and *target*) and search the target group for customers whose behavior is predicted to be similar to those from the source group. **Prerequisites:** - [Configure AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity) - Transaction events must exist in the system. To enable this prediction model: 1. Go to **Settings > AI Engine Configuration**. 2. Click the **Predictions** tab. 3. In the **Lookalikes** section, click **Define**. 4. Switch the toggle to **Enabled**. 5. In the **Events** section, select at least one event which the model will use for the training and for scoring the customers.
Configuration of the Lookalikes model in the item feed
Configuration of the Lookalikes model in the item feed
6. Confirm the settings by clicking **Apply**. After enabling the Lookalikes module, you must wait 2-3 hours for the model to become ready. After that, you can create the first [lookalike prediction](/docs/ai-hub/predictions/lookalikes).
You can get inspired by uses cases with the Lookalikes model: - [Find customers for a new offline shop branch](/use-cases/discover-customers-for-new-shop-branch) - [Find best matching customers for an annual campaign](/use-cases/find-matching-customers-for-campaign)
## Enabling Regression and Classification Predictions ---
Previously referred to as Custom predictions, regression and classification predictions are the current names for the same concept.
The Custom model allows you to create two types of predictions, which differ in terms of the result types. - You can create a prediction that [produces a numerical value](/glossary/#regression), it works best with forecasting customer LTV or the number of purchased products. - The other type [produces true/false values](/glossary/#classification), which is best used to answer yes/no questions, such as "will this customer leave next month?" To enable this prediction model: 1. Go to **Settings > AI Engine Configuration**. 2. Click the **Predictions** tab. 3. In the **Custom** section, click **Define**. 4. Switch the toggle to **Enabled**. 5. In the **Time shift** section, define three time ranges for later selection in the [settings](/docs/ai-hub/predictions/custom#schedule-recalculation-and-result-settings) of a single prediction as the **How many days in advance do you want to make a prediction?** option.
Editing time ranges will be impossible after you click **Apply**.
6. Optionally, in the **Custom events** section, you can add custom events which will be analyzed by the model while calculating the results of a prediction. 7. Confirm the settings by clicking **Apply**.
Configuration of the Custom model in the item feed
Configuration of the Custom model in the item feed
After enabling the Custom model, you must wait 2-3 hours for the model to become ready. After that, you can create the first [custom prediction](/docs/ai-hub/predictions/custom).
You can get inspired by uses cases with the custom model: - [Lifetime value prediction](/use-cases/ltv-prediction) - [Predict churn](/use-cases/churn-prediction) - [Evaluate results of churn predictions](/use-cases/predictions-dashboard)
## Enabling Propensity and Best fit predictions --- Propensity and Best Fit models can't be enabled separately. To enable them, see [the instructions](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity). After enabling the Propensity and Best Fit module, you must wait 2-3 hours for the model to become ready. After that, you can create the first [propensity](/docs/ai-hub/predictions/propensity) and [best fit](/docs/ai-hub/predictions/bestfit) predictions.
You can get inspired by uses cases with the propensity model: - [Predict propensity to buy items with an attribute](/use-cases/propensity-attribute) - [Predict propensity to buy an item](/use-cases/propensity-product) - [Predict propensity to buy items from specific brands](/use-cases/propensity-brand)
# Recommendation types
For users of multiple workspaces, we provide the option to train models for a workspace using data from other workspaces in situations where a data shortage in the target workspace prevents model training. This option is available for training the following recommendation models: [Personalized](/docs/ai-hub/recommendations-v2/recommendation-types#personalized), [Section page recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#section-page), [Attribute recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#attribute), [Cross-sell and Cart recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#cross-sell-and-cart-recommendations), [Next interaction](/docs/ai-hub/recommendations-v2/recommendation-types#next-interaction).
## Similar items This type of recommendation suggests items similar to the one that is currently viewed. The purpose is to offer customers a wider selection of items with similar features (for example, the same category). The recommendation model can be trained by using only the item feed, but once events (for example page visits) become available, the model starts using the all available data from the event history to find items that are similar based on visitor interactions. The AI model for this type is trained weekly by default, this can be changed. ## Cross-sell and cart recommendations The AI model analyzes the transaction history of the workspace to find which items are frequently bought together. Using this information, you can: - use cross-sell recommendations to suggest other items that are likely to be bought with the item that is currently being viewed by the customer. - use cart recommendations to suggest items that are likely to be bought with the item or items that are in the customer's cart. If an item has not yet been purchased with other items, the model predicts what would be recommended with items similar to the item or items which are the context of the recommendation. The AI model for these types is trained weekly. ## Personalized This type of recommendation lets you suggest the items on the basis of a visitor's buying preferences and their behavioral profile. In other words, items are recommended on the basis of what that visitor browsed or bought. As a result, the customer doesn't get lost in item overload. In order to prepare the recommendations, the system analyzes page visits, transactional data, and item feeds (for example, the system can propose a category of items, such as computers, TVs, and books, because the customer purchased or viewed similar items in the past). If a customer's history has no item page visit events or transactions, a recommendation is generated on the basis of the first items clicked by in the last 90 days by other first-time vistors. The AI model for this type is trained weekly.
The Personalized type is the only recommendation type that supports co-brand personalization. For more information, see [AI recommendations with co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations).
## Visual similarity The purpose of this recommendation type is to help customers make purchase decisions faster by showing visually similar items (shape, color, style, etc.). To prepare recommendations, the AI model analyzes the images added to items in the feed. On this basis, it prepares offers of similar items. The AI model for this type is trained weekly. The item feed limit for this recommendation model is 1,000,000 items, regardless of the item feed type.
If you want to show visual similarity recommendations for out-of-stock items, contact the Synerise support.
## Last seen This type of recommendation is used to display the items which have been viewed recently by a particular user. To prepare recommendations, the system analyzes page.visit and product.view events and in response it displays the items which have been viewed by a particular customer. ## Top items The purpose of this type of recommendation is to display top items according to a metric you select, such as bestsellers of the last 30 days, items which have been viewed the most during the last 30 days, etc. The metrics are re-calculated daily. ## Item comparison This type of recommendation is an extension of the similar items recommendation - apart from displaying items similar to the context item (currently viewed item), it shows the attributes of similar and viewed items in a table which makes them easy to compare with the current item. The AI model for this type is trained weekly by default, this can be changed. ## Recent interactions This type of recommendation uses data from an aggregate to promote items towards which the customers performed a specific action which you select. Apart from these most common, such as a visit to the item page, adding the item to the cart, marking the item as favorite, or purchase, you can select any measurable event related to the items you offer. ## Section page This type of recommendation allows you to display a personalized section with items that share attributes such as the category, brand, style, collection, and so on. The motif (item feature/attribute) of the section is personalized as well as the items selected for the section. This way you can personalize the whole page. The model uses the customer's behavioral profile (page visits and transactions) to generate the recommendation. This type of recommendation requires a meta-catalog which store data about the attributes. The AI model for this type is trained weekly. ## Attribute This type of recommendation allows you to promote the features of the items, such as brand, styles, categories or any kind of attributes which are selected for each customer individually. Unlike the section recommendation, this type recommends only attributes, without suggesting any particular items. The model uses the customer's behavioral profile (page visits and transactions) to generate the recommendation. The AI model for this type is trained weekly. ## Next interaction This recommendation model lets you improve performance on product pages and provide your customers with a behavior-driven recommendation option. Unlike Similar Items, which is based on product attribute similarity, or visual recommendations relying on image features, the Next Interaction model predicts the specific product that a customer is most likely to interact with next. Using a personalized approach that incorporates the current product (context item) as input, this model analyzes user behavior patterns to deliver highly relevant recommendations. The output is the item with the highest predicted likelihood of being the customer’s next interaction, enabling a more targeted and effective recommendation experience on product pages. ## External This model lets you declare item IDs recommended by an external model and generate an event same as if the recommendation was calculated by Synerise. These items must exist in the item feed. You can use this to perform A/B/X tests which include recommendations from the external model, and to use the resulting events in analytics. Because the recommended items are explicitly provided in the request, the context has no influence on them. The customer context is only needed to assign an event to a profile. ## Recommendation model summary The table that explains how recommendations of each type are generated (the source and context needed): | Scenario | AI engine | Metric-based | Customer context | Item context | Multiple item context | No context | | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | Personalized | Green checkmark | | Green checkmark | | | | | Similar items | Green checkmark | | | Green checkmark | | | | Visual similarity | Green checkmark | | | Green checkmark | | | | Cross-sell | Green checkmark | | | Green checkmark | | | | Cart recommendations | Green checkmark | | | | Green checkmark | | | Last seen | | Green checkmark | Green checkmark | | | | | Top items | | Green checkmark | | | | Green checkmark | | Item comparison | Green checkmark | | | Green checkmark | | | | Recent interactions | | Green checkmark | Green checkmark | | | | | Section | Green checkmark | | Green checkmark | | | | | Attributes | Green checkmark | | Green checkmark | | | | | Next interaction | Green checkmark | | Green checkmark | Green checkmark | | | | External | | | Green checkmark1 | | | | 1Only needed for saving the event in a profile ## Application of recommendations --- The table below presents the application of recommendation types in business scenarios: | Scenario | Home page | Category/brand page | Item page | Add to cart | Checkout | Zero search results | Post-purchase | | -------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | Personalized | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Similar items1 | | | Green checkmark | | | | | | Visual similarity1 | | | Green checkmark | | | | | | Cross-sell1 | | | Green checkmark | Green checkmark | | | | | Cart recommendations1 | | | | | Green checkmark | | Green checkmark | | Last seen | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Top items | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Item comparison1 | | | Green checkmark | | | | | | Recent interactions | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Section | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Attributes | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | | Next interaction1 | Green checkmark | Green checkmark | Green checkmark | | | | | | External | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | Green checkmark | 1Recommendations with an item context can be displayed in messages and pages other than the item page. To do so, you need to use an aggregate to retrieve the context ([for example, the last bought item](/use-cases/recommending-complementary-products)). ## You may want to read --- - [How to configure an item catalog for recommendations](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations) - [How to create a recommendation](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign) # Creating best fit predictions Best fit predictions offer the capability to determine the most suitable item or value of an item attribute for each customer. By configuring the prediction, you can specify the attribute value you are interested in, such as brand, ID, color, or any other item attribute available in your item feed. The prediction result will then provide you with the attribute value that is most likely to be relevant to the customer. You can create a best fit prediction from scratch or by using one of the predefined scenarios: - Find best fit from brand, category or other attribute for a given customer - Find the overall best item for a given customer Predefined scenarios are configured using a user-friendly wizard that allows you to adjust scenario settings according to your preferences. This is done through a step-by-step configuration form, which provides hints on the interface to guide you. You will be able to select the predefined scenario at the beginning of creating the prediction ([Select the model type](#select-the-model-type)). ## Prerequisites - [Configure AI Engine for Propensity and Best Fit](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity). It usually takes several hours to initialize the model and perform necessary calculations. - The attributes that you want to use for best fit predictions must be added to [filterable attributes](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity#selecting-filters). ## Configure a prediction ### Select the model type 1. Go to AI Hub icon **AI Hub > (AI Predictions) Models**. 2. Click **New prediction**. 1. On the pop-up, select one of the following options: - **Use predefined prediction** - This option allows you to use the ready-made prediction scenarios and adjust their settings to your preferences in a user-friendly, step-by-step configuration form by following hints shown on the interface. If you select this option, you can skip reading the rest of the article. - **Create from scratch** - This option allows you to create your own configuration of a propensity prediction to achieve your custom business objective. If you use this option, select **Best Fit**. ### Select customers to be analyzed Select the audience for whom you want to prepare a prediction.
Selecting an audience to be analyzed
Selecting a group of customers
1. In the **Audience** section, click **Define**. 2. Click **Choose segmentation** and perform one of the following actions: - From the list, select an existing segmentation. You can use the search field. - To define a new group segmentation, at the bottom of the dropdown list, click the **Create new** button. 1. In the **Segmentation name** field, enter the name of the group of customers and click **Next step**. 2. Build the segmentation. See [this article](/docs/analytics/segmentations/creating-segmentations) for instructions. 3. Click **Create segmentation**. 3. Confirm by clicking **Apply**. ### Select items 1. In the **Item selection** section, click **Define**. 2. Click **Choose item feed**. 3. From the list of available catalogs, select the item feed you want to analyze. This can be the same catalog as the one you use for recommendations. **Result**: The **Item attribute** and **Item filter** sub-sections appear. 4. From the **Choose item attribute** dropdown list, select the item attribute you want to analyze. 5. From the **Define item filter** dropdown list, define the filters to include the item or items that you want to calculate the prediction for. - The filters are created using the same [visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder) as recommendations filters, but some operators are not available for Predictions. - You can use [the `created` attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#the-created-attribute) which lets you filter the items based on the date of adding an item to the feed. - Only attributes [selected as filterable when configuring the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity#selecting-filters) are available for use. 3. Click **Apply**. ### Define calculation frequency and start date By default, the calculation is performed once and it is launched immediately. 1. If you want to leave the settings as default, the prediction is ready to calculate. Click **Save & Calculate**. 2. If you want to change the settings, in the **Settings** section, click **Change**. 3. To schedule a recurring calculation: 1. Select the **Recurring calculation** checkbox. 2. In the input field, enter the number of days between calculations. 4. To change the start date of the prediction, in the **Settings** section, click **Change**. 1. Select the **Scheduled** checkbox. 2. In the **Select start date and time** field, specify the date and time for launching the calculation of the prediction. 5. Click **Apply**. 6. Click **Save & Calculate**. ## Results The maximum calculation time is 24 hours. ### Understanding propensity prediction results | Attribute name | Description | |-------------|-------------------------------------------------------------------------------------------------| | action | An event type for the prediction - `snr.bestfit.score` | | added by | An entity that generated this event. In the case of prediction events, it is always Synerise. | | modelId | A unique identifier of the prediction | | modelName | The name of the prediction | | attribute | The name of an item attribute which was selected in the configuration of prediction. The value of this attribute is the prediction result | | topValue | The human-readable result of the prediction, it is the value of the item attribute | | topScore | The result of the prediction | | clientId | Customer's identifier | | time | Time when a prediction was generated, as a Unix timestamp | | configurationVersion | Allows to verify whether two consecutive calculations ran with the settings (*only for debug*) | | modelVersion | Model version allows to verify whether two consecutive calculations ran on the same model parameters (*only for debug*) | # Creating classification and regression predictions In this article, you will get know how to set up your first prediction based on regression and/or classification model. - **Regression** model is suited for creating predictions that return numerical results. It's best used in cases such as: - Predicting the amount of money spent by particular group of customers in a defined time range. - Predicting the amount of items purchased in the defined time range. - **Classification** model is suited for performing the analyses that return the true/false (or 1/0) values. It's best used when you want to find answers to the questions such as: - Will a customer belong to a particular group of customers? - Will a customer leave in the next 30 days? You can create a prediction from scratch or by using predefined scenarios: - Find customers who are likely to leave - Find customers who are likely to unsubscribe - Find customers who are likely to generate the most value or take significant actions - Find customers who belong to a class - Find customers who will buy through a specific communication channel Predefined scenarios are configured using a user-friendly wizard that allows you to adjust scenario settings according to your preferences. This is done through a step-by-step configuration form, which provides hints on the interface to guide you. The option of creating a prediction based on a predefined scenario is available in the initial part of creating the prediction ([Select the model type](#select-the-model-type)). ## Prerequisites --- - [Enable the Custom predictions](/docs/ai-hub/predictions/enabling-predictions#enabling-regression-and-classification-predictions). It usually takes several hours to initialize Predictions and perform necessary calculations. - You should know how to create segmentations or have a segment of customers ready for use as the prediction target. - Create an expression based on which the prediction will be made. For example, if you use an expression that calculates Email Open Rate in last 30 days, you will get a prediction for Email Open Rate for the next 30 days. ## Configure a prediction --- ### Select the model type 1. Go to AI Hub icon **AI Hub > (AI Predictions) Models**. 2. Click **New prediction**. 1. On the pop-up select one of the following options: - **Use predefined prediction** - This option allows you to use the ready-made prediction scenarios and adjust its settings to your preferences in a user-friendly, step-by-step configuration form by following hints shown on the interface. If you select this option, you can skip reading the rest of the article. - **Create from scratch** - This option allows you to create your own configuration of the prediction to achieve your custom business objective. If you use this option, select one of the following models: - **Regression** - to create a prediction that returns a numerical value - **Classification** - to create a prediction that returns a `true`/`false` value ### Select customers to be analyzed --- Select the audience for whom you want to prepare a prediction.
Selecting an audience to be analyzed
Selecting a group of customers
1. In the **Audience** section, click **Define**. 2. Click **Choose segmentation** and perform one of the following actions: - From the list, select an existing segmentation. You can use the search field. - To define a new group segmentation, at the bottom of the dropdown list, click the **Create new** button. 1. In the **Segmentation name** field, enter the name of the group of customers and click **Next step**. 2. Build the segmentation. See [this article](/docs/analytics/segmentations/creating-segmentations) for instructions. 3. Click **Create segmentation**. 3. Confirm by clicking **Apply**. ### Choose the prediction target --- Select the expression based on which the prediction will be made. For example, if you select an expression that calculates Email Open Rate in last 30 days, you will get prediction for Email Open Rate for the next 30 days.
Selecting an expression to define the scope of prediction
Selecting an expression to define the scope of prediction
1. From the dropdown list, select the expression you prepared previously. 2. Confirm by clicking **Apply**. ### Select events --- [Events](/docs/assets/events/introduction-to-events) are customer activities on the website (visits to a website, adding a product to a shopping cart, and so on) and also your activities towards customers (such as sending messages to them). Select the events that the system will use as input to make a prediction. By default, the list already contains the events recommended for the prediction you are creating. The contents of the list is defined while enabling [Custom predictions](/docs/ai-hub/predictions/enabling-predictions#enabling-regression-and-classification-predictions).
Selection of features to support predicting model
Selection of features to support predicting model
1. To select events, disable the **Auto-select events** option. 2. Click **Add events**. 3. On the pop-up, select the events. 4. Confirm your choice by clicking **Add**. 3. Confirm the settings in this section by clicking **Apply**. ### Schedule recalculation and result settings --- In this section, define the frequency of recalculating the prediction and settings of the event that is generated for customers for whom the prediction is made.
The Settings section
The Settings section
1. In the **Model configuration** section, select the number of days after which the prediction is recalculated. 2. From the **How far in advance do you want to make a prediction?** dropdown, select the number of days for which you want to make a prediction (calculated from the current date). 3. To switch on repeatable calculation of the prediction, select the **Set up recurring prediction calculation** checkbox. By default, the calculation is performed once. 4. In the **How would you like to display results?** section, select the scale of prediction results - two- or five-point scale. The scale is represented as a `score_label` parameter of the `snr.prediction.score` event. 5. Use the slider to define the number of features displayed in the parameters of the event generated for a customer for whom the prediction was made.
One of the features is a `prediction` parameter, it is included in the `snr.prediction.score` event and it can be used while selecting customers for your campaigns.
6. In the **Name** field, enter the value of the `scoreName` parameter of the event generated (`snr.prediction.score`) when a prediction is made.
You can use the following characters: - a-z - only lower case - 0-9 - special characters: `.` and `_`
1. Click **Apply**. ### Save the prediction To save the prediction: - as a draft, click **Save**. - and calculate, click **Save & Calculate**.
You can check the logs of the activated prediction. [Learn more](/docs/ai-hub/predictions/predictions-functionalities#previewing-logs).
**Result**: The output of the prediction is an event generated on the profile card. ## Understanding prediction events --- The outcomes of predictions based on the regression and classification models are saved as `snr.prediction.score` events in the Synerise platform. Thanks to that, the predictions events are available in Decision, Experience or Automation Hubs. The schema of a prediction event is standardized. The attributes are explained in the table below the figure.
snr.prediction.score event
snr.prediction.score event
| Attribute name | Description | |-------------|-------------------------------------------------------------------------------------------------| | action | An event type for the prediction - `snr.prediction.score` | | added by | An entity that generated this event. In the case of prediction events, it is always Synerise. | | modelId | A unique identifier of the prediction | | modelName | The name of the prediction | | score_label | Prediction output: two- or five-point scale label. You can select the scale in the [settings of the prediction](#schedule-recalculation-and-result-settings). | | scoreName (deprecated) | The name of the prediction assigned while [creating a prediction](#schedule-recalculation-and-result-settings) | | score | The result of the prediction (based on the expression which was selected as a target while preparing a prediction). | | percentile | [Prediction percentile](/glossary/#percentiles) | | classes | Available classes: `true`, `false` (only for the [Classification](#select-the-model-type) type of model)| | prediction | Predicted class (only for [Classification](#select-the-model-type) type of model) | | feature_influence | [Local feature importance](/glossary/#feature-importance) | | clientId | Customer's identifier | | time | Time when a prediction was generated, as a Unix timestamp | | configurationVersion | Allows to verify whether two consecutive calculations ran with the settings (*only for debug*) | | modelVersion | Model version allows to verify whether two consecutive calculations ran on the same model parameters (*only for debug*) | # Google Merchant Feed
When you select this feed type to [configure AI engine](/docs/settings/configuration/ai-engine-configuration), you can set grouping feed attributes on the interface.
An item feed is necessary to show items in search results, recommendations, to make propensity predictions, and so on. One of the options of uploading an item feed is to use a Google Merchant Center XML file (RSS or Atom specification). Such a file can be: - [uploaded to Catalogs](/use-cases/import-product-feed-to-catalog) with [Automation Hub](/docs/automation). In this case, Data Transformation can be used to modify the content to meet the requirements. The catalog can then be used as an item feed (for example, for event enrichment or when [Configuring the AI engine](/docs/settings/configuration/ai-engine-configuration)). See example Use Case: [Transform and import product data to a catalog](/use-cases/import-xml-file). - pulled from an URL as the item feed when [Configuring the AI engine](/docs/settings/configuration/ai-engine-configuration). In this case, the file must already meet the requirements when Synerise pulls it from the URL you provide. This article describes the requirements that the XML must meet, some good practices, and how to add custom attributes.
For a complete documentation of the Google Merchant Center XML format, see: - [Google's guide on creating feed files](https://support.google.com/merchants/topic/2473799) - [Google's list of item attributes](https://support.google.com/merchants/answer/6324469)
## Requirements - The file must be written according to RSS or Atom specification. - The file must meet the requirements listed in Google's documentation. - The maximum file size is 5 GB (5 000 000 000 bytes). - The encoding must be UTF-8. - These two namespaces must be included in the XML prolog: ``` xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0" ``` - Item attributes from the Google Merchant Center XML standard must have a `g:` prefix. **Exceptions**: `title`, `link`, `description`, `name` - The following attributes (tags) are required in every item: - `` - `` - `<g:availability>` - `<g:product_type>` The value of the attribute is saved in Synerise as the item category and can be used, for example, in recommendations. - `<g:price>` - `<link>` - `<g:image_link>` - `product:type` must be the same as the category on your website (in [OG tags](/developers/web/og-tags)). - The item ID (`g:id` in the XML) must be consistent in every integration and piece of data you store in Synerise (transactions, page view events, item feed, and so on) - The item feed limit for [visual similarity](/docs/ai-hub/recommendations-v2/recommendation-types#visual-similarity) recommendation model is 1,000,000 items, regardless of the item feed type. If your XML is not built exactly according to Google's documentation (for example, `c:cost` is used instead of `g:price` and `g:price` is not included at all), you need to create an [workflow](/docs/automation/creating-automation) with data transformation while importing the data. ## Attribute name transfer into Synerise Synerise automatically maps attributes (including custom attributes) from the XML to attributes in the Synerise database. The prefix is removed and `snake_case` is converted into `camelCase`. For example, `g:image_link` is saved as `imageLink`. Some attributes are transferred differently: - `g:product_type` attribute is transformed into `category` - `g:price`; `g:cost_of_goods_sold`; `g:sale_price` and custom attributes of `price` type are split into value and currency, and their names are converted into camelCase. For example: - `g:price = 12 USD` is saved as `price.value = 12` and `price.currency = USD` - `g:sale_price` is saved as `salePrice.value` and `salePrice.currency` - `g:availability` is converted into boolean (true/false) values. - Custom attributes are saved in the `attributes` object. For example, `c:myAttribute` is saved as `attributes.myAttribute`. When using [Inserts in a recommendation frame](/developers/inserts/recommendations-v2), if the item info is stored in the `item` object, you need to access the custom attribute in the following way: `{{item.attributes.myAttribute}}` - Multiple instances of the same parameter will be saved as an array, for example: <pre><code class="language-LANG"><c:purpose>Regeneration</c:purpose>  <c:purpose>Dry hair</c:purpose>  <c:purpose>Colored hair</c:purpose></code></pre> are saved as: ``` "attributes": { "purpose": ["Regeneration","Dry hair","Colored hair"] } ``` ## Attributes created automatically If `g:price` is defined, the following attributes may be created automatically while the XML is imported: - `effectivePrice` If `g:salePrice` is defined, it's saved as `effectivePrice`. If not, the value of `g:price` is used as `effectivePrice` - `discountAmount` This is `price.value` minus `salePrice.value` - `discount` This is `discountAmount` divided by `price.value` ## Attribute format The attributes can be saved in two formats: - By using the `CDATA` tag, for example: ``` <g:product_type><![CDATA[ Man > all > clothes > shirts ]]></g:product_type> ``` This format lets you include special characters (`<, >, &`) in the attribute's value. This is the recommended format. - As a string, for example: ``` <g:product_type>Man > all > clothes > shirts</g:product_type> ``` In this format, special characters (`<, >, &`) can't be used. ### Category separators In both formats, there must be a space before and after the category separator (`>` or `>`). Otherwise, the character is treated as part of the category name instead of a separator. <strong style="color:green">Correct:</strong> `clothes > shirts` <strong style="color:red">Wrong:</strong> `clothes>shirts` ## Custom item attributes Custom parameters are prefixed with a `c:`: <pre><code class="language-xml">... <c:custom_tagName1>...</c:custom_tagName1> <c:custom_tagName2>...</c:custom_tagName2> ...</code></pre> ### Additional categories If you want to add additional categories that are recognized by Synerise, use the `<g:additional_product_type>` attribute, for example: <pre><code class="language-xml"><g:additional_product_type><![CDATA[X > Y > Z]]></g:additional_product_type> <g:additional_product_type><![CDATA[A > B > C]]></g:additional_product_type> <g:additional_product_type><![CDATA[1 > 2 > 3]]></g:additional_product_type></code></pre> ## Good practices Tips to help you make your work easier and your files more efficient: - Avoid including too large images. They may slow down loading dynamic content in campaigns where data from the feed is used. - Use the `<[!CDATA]>` tag in case you add items with special characters (`<, >, &`) in the attribute in the future, even if the attributes don't include those characters now. - Include only the attributes that you plan to use. - Include the [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) header to enable detection of whether the product feed import is necessary, this will help you reduce data transmission costs. ## Troubleshooting 1. Ensure that all the [requirements](#requirements) are met. 2. For the most common problems, see the "Item feed" section of the [Integration checklist](/first-steps/integration/integration-review#item-feed). ## RSS example <pre><code class="language-xml"><?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0"> <channel> <title>Your Website</title> <link>http://www.example.com</link> <description>About your website</description> <item> <!-- The following attributes are always required --> <g:id>CLO-29473856-2</g:id> <title><![CDATA[Roma Cotton Rich Bootcut Jeans - Size 8 Tall]]></title> <g:availability><![CDATA[in stock]]></g:availability> <g:product_type><![CDATA[Women's Clothing ? Jeans > Bootcut Jeans]]></g:product_type> <g:price>59.50 USD</g:price> <link><![CDATA[http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856]]></link> <g:image_link><![CDATA[http://images.example.com/CLO-29473856-front.jpg]]></g:image_link> <!-- The following demonstrates the use of the 'sale price' attribute --> <g:sale_price>29.20 USD</g:sale_price> <!-- The following attributes are not required for this item --> <g:item_group_id>CLO-29473856</g:item_group_id> <name><![CDATA[Roma Cotton Rich Bootcut Jeans]]></name> <g:online_only>yes</g:online_only> <description><![CDATA[A smart pair of bootcut jeans in stretch cotton.]]></description> <g:condition>new</g:condition> <g:size>30</g:size> <g:quantity>10</g:quantity> <g:color><![CDATA[Navy]]></g:color> <g:shipping_weight>1 kg</g:shipping_weight> <g:manufacturer><![CDATA[Wonderful Jean]]></g:manufacturer> <g:brand><![CDATA[MS]]></g:brand> <g:mpn>B003J5F5EY</g:mpn> <g:gtin>5060155240282</g:gtin> <g:google_product_category>Women's Clothing > Jeans > Bootcut Jeans</g:google_product_category> <g:gender>Female</g:gender> <g:material><![CDATA[Jeans]]></g:material> <!-- The following demonstrates the use of the custom attributes --> <c:age_group><![CDATA[Adult]]></c:age_group> </item> <item>...</item> <item>...</item> </channel> </rss></code></pre> ## Atom example <pre><code class="language-xml"><?xml version="1.0" encoding="utf-8"?> <feed xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0"> <title>Your Website</title> <link rel="self" href="http://www.example.com" /> <updated>2018-01-01CET10:10:30</updated> <entry> <!-- The following attributes are always required --> <g:id>CLO-29473856-2</g:id> <title><![CDATA[Roma Cotton Rich Bootcut Jeans - Size 8 Tall]]></title> <g:availability><![CDATA[out of stock]]></g:availability> <g:product_type><![CDATA[Women's Clothing ? Jeans > Bootcut Jeans]]></g:product_type> <g:price>59.50 USD</g:price> <link><![CDATA[http://www.example.com/clothing/women/Roma-Cotton-Bootcut-Jeans/?extid=CLO-29473856]]></link> <g:image_link><![CDATA[http://images.example.com/CLO-29473856-front.jpg]]></g:image_link> <!-- The following demonstrates the use of the 'sale price' attribute --> <g:sale_price>29.20 USD</g:sale_price> <!-- The following attributes are not required for this item --> <g:item_group_id>CLO-29473856</g:item_group_id> <name><![CDATA[Roma Cotton Rich Bootcut Jeans]]></name> <g:online_only>yes</g:online_only> <description><![CDATA[A smart pair of bootcut jeans in stretch cotton.]]></description> <g:condition>new</g:condition> <g:size>30</g:size> <g:quantity>10</g:quantity> <g:color><![CDATA[Navy]]></g:color> <g:shipping_weight>1 kg</g:shipping_weight> <g:manufacturer><![CDATA[Wonderful Jean]]></g:manufacturer> <g:brand><![CDATA[MS]]></g:brand> <g:mpn>B003J5F5EY</g:mpn> <g:gtin>5060155240282</g:gtin> <g:google_product_category>Women's Clothing &gt; Jeans &gt; Bootcut Jeans</g:google_product_category> <g:gender>Female</g:gender> <g:material><![CDATA[Jeans]]></g:material> <g:additional_image_link>http://images.example.com/CLO-29473856-side.jpg</g:additional_image_link> <g:additional_image_link>http://images.example.com/CLO-29473856-back.jpg</g:additional_image_link> <g:shipping> <g:country>US</g:country> <g:service>Standard Free Shipping</g:service> <g:price>0 USD</g:price> </g:shipping> <!-- The following demonstrates the use of the custom attributes --> <c:age_group><![CDATA[Adult]]></c:age_group> </entry> <entry>...</entry> <entry>...</entry> </feed></code></pre> # Creating recommendations Once the model training is completed, you can create a recommendation. The recommendations you create and activate will not be visible until you indicate how and where the recommendations are to be displayed. Because each recommendation is different for every customer, you can't indicate exactly the items to be shown in the recommendations. However, you can [preview the recommendation](/docs/ai-hub/recommendations-v2/previewing-recommendations) for any customer. ## Distributing recommendations --- You can use the ID of the recommendation and [inject it with a snippet](/docs/assets/snippets) in other types of communication, such as: - [dynamic content](/docs/campaign/dynamiccontent) - this way you can show the recommendations on your website. - [email](/docs/campaign/e-mail) - this way you can send out recommended items through emails. - mobile application - you can use [documents](/docs/assets/documents) to build your own mobile app and show the recommended items. - [mobile push](/docs/campaign/Mobile) - you can send recommendations through notifications in your mobile application. - [web push](/docs/campaign/Webpush) - this way you can send notifications to your customers through a web browser. - [SMS](/docs/campaign/SMS) - this way you can reach your customers with recommendations on their mobile. ## You may want to read --- - [Recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types) - [How to build a filter in a recommendation](/docs/ai-hub/recommendations-v2/recommendation-filters) - [Filters - examples of use](/docs/ai-hub/recommendations-v2/recommendation-filters-examples) - [Previewing recommendations](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign) - [Recommendation statistics](/docs/ai-hub/recommendations-v2/recommendation-statistics) ## Prerequisites --- - You must [configure an item catalog for recommendations](/docs/ai-hub/recommendations-v2/configure-item-feed-ai-recommendations). - You must have [permissions](/docs/settings/identity-access-management/permissions#permissions) from the following sets: - Communications > Recommendations Without these permissions, you can't see **Recommendations** in the menu. - Assets > Catalogs Without these permissions, **Recommendations** may not load. - If you want to create a visual similarity recommendation, select an item feed which contains less than 1,000,000 items. - If you want to create the **Recent interactions** recommendation, create an aggregate that gathers a group of items towards which a specific event has occurred <details class="accordion"><summary>Click here to see example aggregate</summary><div class="accordion-content"><figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/aggregate-recent-recommendations.png" alt="Type & Source section" class="full"> <figcaption> The Type & Source section </figcaption> </figure> <p><strong>Required</strong> in the configuration:</p> <ul> <li><p>Aggregate type set as <strong>Last Multi</strong></p> </li> <li><p>Event</p> </li> <li><p>Event parameter connected to an item </p> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> <p>You can read more about aggregates <a href="/docs/crm/aggregates/creating-profile-aggregates">here</a>.</p> </div></div></div></li> </ul></div></details> ## Creating recommendation --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Recommendations) Models > Add recommendation**. 2. Enter the name of the recommendation (it is only visible on the list of recommendation). ## Select feed and recommendation type --- Start with selecting the feed from which items will be sourced to recommendations and the type of recommendations to be displayed. 1. In the **Type & Items feed** section, click **Define**. 2. From the **Items feed** dropdown list, select an item feed. 3. Under **Recommendation type**, click **Select model**. 4. On the pop-up that opens, select a recommendation type. If a recommendation type is disabled, it means the AI engine is not trained yet or that a recommendation type is not available for this item feed. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recommendation-types.png" class="large" alt="Selecting a recommendation model"><figcaption>Selecting a recommendation model</figcaption></figure> <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Learn more about: - [recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types) - [recommendation statuses](/docs/settings/configuration/ai-engine-configuration/model-status) </div></div></div> 4. Confirm the selection by clicking **Apply**. 5. **Recent interactions model only**: Under **Aggregate**, click **Select** and select the aggregate which defines the interactions that you want to take into account. 5. Save the settings in the **Type & Items feed** section by clicking **Apply**. ## Select an aggregate (only recent interactions model) --- <details class="accordion"><summary>Only for Recent interactions</summary><div class="accordion-content"><div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> <p>This section is available only for the <strong>Recent interactions</strong> recommendation type.</p> </div></div></div> <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/selected-aggregate-general.png" alt="Selecting an aggregate for the recent interactions recommendation type" class="full"> <figcaption> Selecting an aggregate for the recent interactions recommendation type </figcaption> </figure> <ol> <li><p>Select the aggregate you created within the scope of <a href="/docs/ai-hub/recommendations-v2/creating-recommendation-campaign/#prerequisites">Prerequisites</a></p> </li> <li><p>Confirm the selection by clicking <strong>Apply</strong>.</p> </li> <li><p>Proceed to <a href="/docs/ai-hub/recommendations-v2/creating-recommendation-campaign/#configure-comparison-attributes-only-item-comparison-model">Configuring comparison attributes</a>.</p> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> <p>You can read more about aggregates <a href="/docs/crm/aggregates/creating-profile-aggregates">here</a>.</p> </div></div></div></li> </ol></div></details> ## Configure comparison attributes (only item comparison model) --- <details class="accordion"><summary>Only for Item comparison</summary><div class="accordion-content"><div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> <p>This section is available only for the <strong>Item comparison</strong> recommendation type.</p> </div></div></div> <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/compare-attributes.png" alt="A blank form for configuring recommendation campaigns" class="full"> <figcaption> A blank form for configuring a recommendation </figcaption> </figure> <p>You can select the attributes of the items to be included in the comparison. The attributes in the <strong>Predefined attributes</strong> section are sourced from the <strong>Response attributes</strong> which can be edited in <strong>Settings > AI Engine Configuration</strong>. </p> <ol> <li>To add more attributes apart from the predefined ones to the comparison, in the <strong>Additional attributes</strong>, click <strong>Select attributes</strong>.</li> <li>On the pop-up, select the attributes.</li> <li>Confirm by clicking <strong>Apply</strong>.<br><strong>Result</strong>: Example item comparison on a website (the context item is included in one of the columns): <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/example-item-comparison.png" alt="Example item comparison frame" class="large"> <figcaption> Example item comparison frame </figcaption> </figure></li> </ol></div></details> ## Configure item slots --- You can use slots to assign space in your recommendation frame to specific items. Each slot may include a different number of items and have its own filtering rules. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/items-recov2.png" alt="A blank form for configuring recommendation campaigns" class="large"> <figcaption> A blank form for configuring a recommendation </figcaption> </figure> For example, you can use three slots to display: - Items of specific brand - This allows you to use space in your recommendation slots by items of your partners and suppliers. - Items of specific category, - Items of specific color A recommendation must include at least one slot. ### Adding slots 1. In the **Items** section, click **Define**. 3. Click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/analytics/_gfx/plus-button.png" alt="Plus icon" class="icon"> button. 4. If you want to name the slot, hover over the **Unnamed slot** tab and double click it. 2. When adding multiple slots, you can define their order by dragging and dropping the tabs into the desired sequence. The slot represented by the leftmost tab is considered the first slot. For more slot order options, refer to the [Define slot and item ordering](#define-slot-and-item-ordering) section. 5. To proceed to the slot settings, click the tab with the slot. 6. In the **Number of items** subsection, enter the minimum and maximum number of items to include in the slot. 7. <span id="select-conditions-of-displaying-items"></span>Add the filters for this slot. - [Elastic filters](#elastic-filters) - [Static filters](#static-filters) - [Distinct filter](#distinct-filter) 4. Confirm the settings by clicking **Apply**. #### Elastic filters This type of filter allows you to select the items to be included in the slot and supplement the slot if it’s not entirely filled up with the items. For example, if you select to display up to 10 items, and you have only 5 items that meet the conditions of elastic filter to be included in the slot, then the slot will be filled with additional items which do not match the elastic filter (based on scoring). 1. Click **Define filter**. 2. Select one of the filter creators: - [visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder) - [IQL query wizard](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query) #### Static filters This type of filter allows you to show a fixed number of items that match the conditions of the filter. - If the applied filter conditions (that don't include any customer context) are too strict and there are not enough items to fill in the recommendation slot, the slot is not generated at all. - If the filter conditions include customer context from one of the following sources: [aggregate](/docs/ai-hub/recommendations-v2/recommendation-filters#aggregate), [expression](/docs/ai-hub/recommendations-v2/recommendation-filters#expression), or a [profile attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#customer-context-value), and the context cannot be retrieved for any reason: - By default, the filter is ignored and the slot will be generated without applying the filters. - If **Fail slot when the context is missing** is selected from the **Ignore filter** dropdown list, the slot is not generated at all. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/static-filters-ignore-limits.png" class="full" alt="The Ignore filter option in static filters in AI Recommendations"><figcaption>The Ignore filter option in static filters in AI Recommendations</figcaption></figure> 1. If you want to [apply global item filter](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-recommendation-types-and-default-filters) defined for the recommendation model based on which you're creating the campaign, enable **Apply Items Global Filters**. Enabling this toggle applies the global item filters and they work in combination with other filters in the slot. 2. If you want to apply custom static filters for the slot, click **Define filter**. Select one of the filter creators: - [visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder) - [IQL query wizard](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query) <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> When the global item filters and the filters defined in the recommendation are mutually exclusive, recommendation filters take precedence. </div></div></div> #### Distinct filter This type of filter allows you to increase the variety of items included in the slot. You can define the allowed number of items that share the same attribute value to be shown, for example, a number of items that have the same brand, color, shape, category, and so on. - For all recommendation types except for **Last seen**, the engine considers up to 1000 items with the highest score that match the recommendation type. For example, if you selected the **Cross-sell** type, the engine analyzes up to 1000 items that match the cross-sell recommendation type, and then selects the number of items you chose to include in the slot. - For the **Last seen** recommendation type, the engine considers the last 100 page visit events. Based on the data from these events, the engine selects the number of items you chose to include in the slot. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This filter can only use attributes defined when [configuring the recommendation engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-attributes-to-increase-item-variety). </div></div></div> 1. If you want to [apply global distinct filter](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-recommendation-types-and-default-filters) defined for the recommendation model based on which you're creating the campaign, enable **Apply Global Distinct Filters**. Enabling this toggle applies global distinct filters to the slot and it overrides the settings of slot distinct filter. 2. If you want to apply custom distinct filters for the slot, click **Define filter**. 1. In the **Show only** field, enter the number of items whose attribute values can be the same. 2. From the **Choose attribute** dropdown list, select the attribute. You can use each attribute only once. This means that if you add multiple filters, any attribute that has already been used will no longer be available for selection. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can read how to build conditions in the distinct filters for the `category` attribute [here](/docs/ai-hub/recommendations-v2/recommendation-filters#the-category-attribute). </div></div></div> 3. To add more conditions, click **Add another** and repeat the steps. 4. If you want the distinct filter to supplement the slot with non-matching items when not enough matching items are found, enable the **Mark filter as elastic** option. 5. Confirm by clicking **Apply**. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> When the global item filters and the filters defined in the recommendation are mutually exclusive, recommendation filters take precedence. </div></div></div> ## Define slot and item ordering --- In this section, you can define the order of slots and the order of recommended items in the slot. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/slot-and-item-ordering.png" alt="A form for configuring slot order and item order within slots" class="large"> <figcaption> A form for configuring slot order and item order within slots </figcaption> </figure> 1. In the **Slots and items ordering** section, click **Define**. 2. To define the order of slots and order of items within the slots, in the **Slots and items ordering** subsection, select one of the following options: - **Arrange items in slot order**: - the slots will be presented in the order defined in the **Items** section. - the order of items within the slot is defined by the scoring method selected in **Items sorting method within slots**. By default, the items are arranged based on the results of the recommendation model. - **Arrange items in personalized slot order**: - the order of slots is arranged based on the results from the Personalized recommendation model. The higher the score, the higher position the slot takes. - the order of items within the slot is defined by the scoring method selected in **Items sorting method within slots**. By default, the items are arranged based on the results of the recommendation model. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is available only for **Personalized** recommendations. </div></div></div> - **Arrange items ignoring slots and its order**: the slots will be ignored and the order of items will be arranged according to the score method selected in **Items sorting method within slots**. By default, the items are arranged based on the results of the recommendation model. 3. To define the method of sorting the items within slots, in the **Items sorting method** subsection, select one of the methods. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This section is unavailable for Attribute and Section recommendations, however, the items in these recommendation types are arranged in the order defined by the Personalized recommendation model. </div></div></div> You can select the following sorting methods: - **Sort by personalized score** - The items are arranged in the order in which they were returned by the Personalized recommendation model (this sorting method is available only for the Personalized recommendation type). - **Sort by score** - It's a default method, the items are arranged in the order in which they were returned by the recommendation model (for example, if you create a Cart recommendation, then the items are organized based on the results of the Cart recommendation model). - **Sold items count in the last 30 days** - The items returned by the model will be arranged from the most sold to the least sold in the last 30 days. - **Sold items value in the last 30 days** - The items returned by the model will be sorted based on their price, with the most expensive ones sold in the last 30 days listed first. - **Page visit count in the last 30 days** - The items returned by the model will be sorted based on the visits to the item page, with the most visited ones in last 30 days listed first. - **Conversion percent in the last 30 days** - The items returned by the model will be sorted based on the conversion rate of the product (ratio of purchases to the number of users visiting product page) in the last 30 days, with those with the highest rate listed first. - **Conversion percent after clicking on the recommendations in the last 30 days** - The items returned by the model will be sorted based on purchases after clicking the item in any communication channel in the last 30 days, with those with the highest rate listed first. - **Sold items count in the last day** - The items returned by the model will be arranged from the most sold to the least sold in the last day. - **Sold items count from the same weekday last week** - The items will be sorted in descending order based on their quantity sold on the same weekday as last week (for example, if today is Wednesday, items will be arranged according to their sales quantity from last Wednesday). - **Page visit count in the last 7 days** - The items returned by the model will be sorted based on the visits to the item page, with the most visited ones in last 7 days listed first. - **Sold items count in the last 7 days** - The items returned by the model will be arranged from the most sold to the least sold in the last 7 days. 4. Confirm the settings by clicking **Apply**. ## Define the boosting factors --- You can increase probability of appearing in the recommendation frame. You can boost the items in three ways (both can be used at the same time): - **Metric** boosting uses pre-defined item popularity metrics to influence item scoring. Metric boosting is available only for the Similar, Cart, Visual similarity recommendation types. - **Attribute** boosting influences item scoring depending on rules applied to the item's attributes. This is done by applying a filter to items and adjusting the score of those items that match the filter. For example, you can increase the scoring of a particular brand without excluding other brands entirely. - **Personalization** boosting uses the personalization model to influence the items' scoring according to the preferences of each customer - items that fit their preferences have a higher probability of appearing in the recommendation frame. You can manage the influence of personalization model on boosting by using the Impact scrollbar. Personalization boosting is available for all recommendation types, except for Personalized, Section, and Attribute. This element has a significant impact on the model's outcome. For instance, if we set the personalization impact to 80% in the recommendation model based on **Top items**, the suggested items will be influenced mostly by the personalization model (making up 80% of the impact). Meanwhile, the **Top items** model will only contribute 20% to the recommendations (along with other factors like boosting attributes). <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recov2-boosting.png" class="large" alt="An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting"><figcaption>An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting</figcaption></figure> 1. In the **Boosting** section, click **Define**. 2. **Metric boosting**: 1. Click **Select** and select a metric to use for adjusting the score. 2. Choose the **Promote** (default) or **Demote** option. 3. Use the slider to determine how much you want the metric to influence the score of the items. 3. **Attribute boosting**: 1. Click **Add rule**. 2. Click the created rule to open its settings. 3. In the **Items scope** section, click **Define filter**. Items that meet the filter will have their scores adjusted. To learn how to build filters, see [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters). 4. Choose the **Promote** (default) or **Demote** option. 5. Use the slider to determine how much you want the metric to influence the score of the items. 4. **Personalization**: 1. Enable the **Personalization** toggle. 2. From the Impact scrollbar, select how much you want the personalization model to influence the arrangement of items in the recommendation. 4. Confirm the settings by clicking **Apply**. ## Additional settings --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-additional-settings.png" class="full" alt="The Additional settings section in the configuration form"><figcaption>The Additional settings section in the configuration form</figcaption></figure> 1. In the **Additional settings** section, click **Define**. 2. If you want to exclude items that the customer already purchased, enable the **Exclude already bought products** option. This option will exclude up to 100 items that were purchased within a specific number of days, as defined in the **Since** field, which appears after enabling the option. Optionally, you can also set this option as elastic, which will work as an [elastic filter](/docs/ai-hub/recommendations-v2/recommendation-filters#elastic-filter). 5. If you want to source the item context from an aggregate or expression results instead of the website, enable the **Item context from analytics** toggle. Then from the dropdown list, select the analysis whose result will be treated as the item context. On the basis of the item context, the engine selects the items to display in the recommendation. By default, the recommendation sources the item context from the product page where it is implemented. This option lets you override this setting, so the item context will be taken from the result of the aggregate or expression that returns for example, a recently viewed item, favorite items, recently purchased items or items purchased the most frequently. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is available for all recommendation types except for Recent interactions and Last seen. </div></div></div> 6. Optionally, you can assign a slug to the recommendation. In such a case, enable the **Recommendation slug** toggle. This option lets you assign a user-friendly, unique identifier of the recommendation which you can use to fetch recommendation campaign instead of its ID. The slug can be edited at any time. In the **Enter unique slug name** field, enter the name containing 3 to 25 characters. You can only use: - lowercase Latin alphabet letters (a-z) - digits (0-9) - `-` but it can't be the first and/or last character 7. If you want to use [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) to recommend items from across all your grouped workspaces, enable the toggle in the **Co-Brand Personalization** section. This toggle is available if your workspace uses [co-brand decisioning layer feature](/docs/settings/workspace/multibrand-workspaces). To enable it, contact the Synerise support. The badge next to the option name indicates the mode configured for your workspace group by the Synerise support team. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/co-brand-personalization.png" class="medium" alt="The Co-Brand Personalization section in the configuration of the AI Recommendation campaign"><figcaption>The Co-Brand Personalization section in the configuration of the AI Recommendation campaign</figcaption></figure> 8. To confirm the settings in the **Additional settings** section, click **Apply**. ## Saving the recommendation --- To save the recommendation: - as a draft, click **Finish later**. - and activate the recommendation, click **Save**. Once you activate the recommendation, you can use it as described in the [Distributing recommendations](#distributing-recommendations) section. You can view the change history for this item from its configuration - see [Audit Log](/docs/settings/workspace/audit-log). # Create rules ## About --- Rules are an extension of the features available in the AI Search Engine. The rules provide IF - THEN logic that lets you influence the search results. This way you can manage the behavior of the search engine by telling it to promote specific products, replace the query or a word in the query or remove a word from it in specific circumstances. Despite the many possibilities of altering the search performance, no code is required to set up the rules. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can create up to 1000 rules in one index. </div></div></div> ## Structure --- The process of configuring rules consists of three steps: 1. Defining the target audience of the rule. 2. Defining the conditions. The rule is only applied when **all** conditions are met. <details class="accordion"><summary>Click for video tutorial</summary><div class="accordion-content"><div class="youtube-embed youtube-facade not-prose" data-youtube-id="yqlygU2VXPM" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to set up Search Rules Conditions?"><img src="https://img.youtube.com/vi/yqlygU2VXPM/hq720.jpg" alt="Synerise Academy - AI Search - How to set up Search Rules Conditions?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> 1. Rules that respond to customers' queries - Rules can modify your customer's queries and apply consequences if the query matches the condition of the rule. You can select among 4 query conditions: - **is** - The phrase in the condition and the search phrase entered by customer must be identical. - **contains** - The search phrase must include the phrase in the condition, but can also contain other phrases. - **starts with** - The search phrase must start with the phrase in the condition. - **ends with** - The search phrase must end with the phrase in the condition. 2. Rules that respond to a context - If a condition of the rule has only a context defined, then the search results will be modified according to the defined consequences. It happens only if the context exactly matches a value in the `context` parameter of a customer’s search. <details class="accordion"><summary>More information about context</summary><div class="accordion-content"><ul> <li>The context can be any string. For example, you can use it to differentiate searches made on a mobile device from those made on desktop.</li> <li>Context is sent as a parameter with the <a href="https://hub.synerise.com/api-reference/ai-search#tag/Search">search query</a>.</li> <li>Example of use: To make search results on mobile devices more accurate, you can promote results for smartphone chargers and cases instead of displaying chargers and cases for laptops on the top of search results.</li> <li>To configure a context-based rule, you must:<ol> <li>Assign `context` search parameter to customer searches.</li> <li>Create the rule in the application or through the API.</li> </ol> </li> </ul></div></details> 3. Rules that apply only when the customer applies particular filters to the search (text filters or a range of numbers). <span id="filterlogic"/> <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This condition can only be set if filterable or facetable search attributes are defined. </div></div></div> <details class="accordion"><summary>More information about filter-dependent rules</summary><div class="accordion-content"><ul> <li><strong>Exact</strong>: the customer's search filters must be exactly the same as this condition filter.</li> <li><strong>Contains Profile's Filters</strong>: this condition filter must contain all the customer's search filters (but can also contain other filters).</li> <li><strong>In Profile's Filters</strong>: the customer's search filter must contain all of this condition filter (but can also contain other filters)</li> <li><strong>Any</strong>: at least one of the customer's search filters must match a value from this condition filter.</li> </ul> <p> <strong>Example:</strong> </p> <ul> <li>The customer's filters are `color = green OR red OR white`</li> <li>The condition filter value is `color = green, red`.</li> </ul> <p> The result is:</p> <ul> <li><strong>Exact</strong>: does not match, the sets are different. The rule is not applied.</li> <li><strong>Contains Customer's Filters</strong>: does not match, some customer filters are not included in the condition filters. The rule is not applied.</li> <li><strong>In Customer's Filters</strong>: matches, `green` and `"red"` are included in `green OR red OR white`. The rule is applied.</li> <li><strong>Any</strong>: matches, there is at least one common element. The rule is applied.</li> </ul></div></details> 1. Rules that apply for all queries. For example, filter the results of every query to those that have the value of the `online` attribute set to true. 1. Defining the consequences. The search engine adapts its behavior according to the consequences associated with a condition. You can select from the following consequences: <details class="accordion"><summary>Click for video tutorial</summary><div class="accordion-content"><div class="youtube-embed youtube-facade not-prose" data-youtube-id="3BDiLJDSq_w" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to define the Consequences?"><img src="https://img.youtube.com/vi/3BDiLJDSq_w/hq720.jpg" alt="Synerise Academy - AI Search - How to define the Consequences?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> ## Requirements --- AI Search engine must be implemented and configured. ## Creating rules --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/query-rules.png" alt="Blank query rules settings" class="full"> <figcaption> Blank Query Rules settings </figcaption> </figure> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. Select an index from the list. 3. Go to the **Rules** section. 4. On the right side of the screen, click **Add new**. **Result**: A new window opens. 4. Optional: To name the rule, next to **Unnamed rule**, click the pencil icon and enter a name. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> In [private preview](/docs/log-in-and-navigate-synerise-platform#private-preview), if the rule name contains the word `global`, when you save the rule, it is also saved to every other index in the same workspace. </div></div></div> 4. To define the profiles for whom you want to apply the rule, in the **Audience** section, click **Define**. 1. Select one of the following options: - **Everyone** - The rule will apply to all profiles in your database. - **Segments** - The rule will apply to profiles in the selected segmentations. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can use up to 10 various segmentations in all query rules in one index. When you use the same segmentation in several rules, it counts as 1 towards this limit. </div></div></div> 2. Follow the instructions depending on the option you selected: <div class="content-tabs" data-tab-group="tabgrp-1243"> <div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1243-0" data-tab-group="tabgrp-1243" data-tab-active="true">Everyone</button><button class="tab-button" data-tab-id="tabgrp-1243-1" data-tab-group="tabgrp-1243">Segments</button></div> <div class="tab-panel" data-tab-id="tabgrp-1243-0" data-tab-group="tabgrp-1243" data-tab-active="true"> No further configuration in this section is needed. Confirm your choice by clicking **Apply**. </div> <div class="tab-panel" data-tab-id="tabgrp-1243-1" data-tab-group="tabgrp-1243"> 1. Click **Add segments**. 2. On the pop-up, select one or more segmentations. 3. On the pop-up, confirm your choice by clicking **Apply**. 4. Confirm the settings of the **Audience** section by clicking **Apply**. </div> </div> 5. To adjust the query conditions, in the **Conditions** section, click **Define**. 1. In the **Query** tab, to define the method of checking the query, choose one condition. 2. Click **Add phrase**. 3. Enter a phrase. You can do it in two ways: - In text field, type a word (or a phrase) in a singular form. - Next to the text field, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/facet-in-query-rules.png" alt="Facet icon in Query rules" class="icon" > button. From the dropdown list select a facet (a product attribute) and its value (it can be a phrase). It is different from defining an exact query; you can define which attribute in general the query rule should look out for. For example, if you choose _brand_ as the facet, the query rule will apply its consequence whenever any brand name is detected in the query. 4. If you want to add more phrases, repeat steps **b** and **c**. 5. In the **Context** tab, to define only the environment of the search (without query phrases), in the **Define query context** enter the context. 6. In the **Filters** tab, define the filters that must be used by the customer in order for the rule to activate: 1. Click **Add filter**. 2. From the **Attribute** drop-down list, select the attribute. 3. From the **Filter match** drop-down list, select the [matching logic](#filterlogic). 4. Select the values that must match the logic: 1. If the attribute is text-type, select the value or values from the dropdown list. 2. If the attribute is a number, enter a value or range. 5. To add more filters, click **Add filter** again. If you add multiple filters, they must all be met. 7. Confirm the settings by clicking the **Apply** button. 6. To define how the search engine reacts to the defined conditions, in the **Consequences** section, click **Define**. Full list of consequences and instructions in the ["Consequences"](#consequences) section. 1. Click **Add consequence**. 2. From the dropdown list, select a consequence. 3. Fill in the settings of the selected consequence. 4. To add more consequences, click **Add consequence** and repeat steps **b** and **c**. If you add multiple consequences, they are all applied. For example: - if the first consequence is "promote item A" and the other is "replace word", the result is "promote item A AND replace word". - if one of the consequences is "Show no results", the search will show no results regardless of any other consequences added before or after "Show no results". 5. Confirm by clicking **Apply**. 7. To define when the query rule applies, in the **Schedule** section, click **Define**. 1. To launch query rules immediately, click **Active immediately**. 2. To schedule the rules at specific time, click **Scheduled**. 1. Enter the start date. 2. Enter the end date. 3. Select the time zone. 3. Confirm by clicking **Apply**. 8. To complete working on the query rule, you can either: - Save it as a draft by clicking **Finish later**. - To save and activate it, click **Publish**. ### Consequences #### Replace query The entire query typed by a user will be replaced with the query you provide. In the **New query** field, enter the query for which the results will be displayed, which will replace the original query. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/replace-query.png" class="medium" alt="Configuration of the Replace query consequence"><figcaption>Configuration of the Replace query consequence</figcaption></figure> #### Replace word A selected word from the query, if it occurs, is replaced with the word you indicate. 1. In the **Word from query** field, enter the word from the query you want to replace. 2. In the **New word** field, enter the word with which the original word from the query will be replaced. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/replace-word.png" class="medium" alt="Configuration of the Replace word consequence"><figcaption>Configuration of the Replace word consequence</figcaption></figure> #### Remove word A selected word from the query, if it occurs, is removed. In the **Word from query** field, enter the word you want to delete from the query. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/remove-word.png" class="medium" alt="Configuration of the Remove word consequence"><figcaption>Configuration of the Remove word consequence</figcaption></figure> #### Pin items A selected item or items will be placed higher in the search results. This consequence lets you pin items which were not returned in search results. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/pin-item.png" class="medium" alt="Configuration of the Pin items consequence"><figcaption>Configuration of the Pin items consequence</figcaption></figure> 1. In the **Item** field, from the dropdown list, select the item you want to promote. 2. To: - add a next item, click **Add item** and repeat step 1. - add multiple items, click **Add many**. **Result**: A pop-up appears. 1. In the **Add items** field, provide item IDs separated by `;` 2. Confirm your choice by clicking **Add**. 3. Confirm by clicking **Apply**. 2. If you want to change the method of positioning to other than manual, click **Change**. By default, the **Manual** method is selected, which means you define the position of each item one by one. - if you want to define several positions per each item, select **Custom**. **Result**: A pop-up appears. 1. In the **Position** field, provide the position numbers (at any order, but you can use only positions between 1 to 50). The first position number you provide is assigned to the first item on the list as presented below: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/custom-positions-rules.png" class="large" alt="On the right side, you assign positions to items selected on the left side of the screen"><figcaption>On the right side, you assign positions to items selected on the left side of the screen</figcaption></figure> - if you want to define the item positions in ascending order, select **Ascending**. **Result**: A pop-up appears. 1. In the **Starting position** field, enter the position which will be assigned to the first item on the list. 2. In the **Gap** field, enter the number which will define the position gap between each item you selected. For example: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ascending-positions-rules.png" class="large" alt="On the right side, you define starting position (values marked with a yellow rectangles on both screens) and the gap between positions (marked with a red rectangle and red arrows)"><figcaption>On the right side, you define starting position (values marked with a yellow rectangles on both screens) and the gap between positions (marked with a red rectangle and red arrows)</figcaption></figure> 3. Confirm by clicking **Apply**. #### Pin items by attribute Selected items returned in the search results will be placed at the top based on the chosen attribute, or at specific positions if you configure them. You can specify the number of items to pin. - If more items than the specified number qualify for pinning, the overall item ranking will determine which items are pinned. - If fewer items than specified qualify, only those eligible will be pinned. - If no items meet the conditions, the search results are returned unchanged. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/pin-items-by-attribute.png" class="medium" alt="Configuration of the Pin items consequence"><figcaption>Configuration of the Pin items by attribute consequence</figcaption></figure> 1. From the **Attributes** dropdown list, select the item attribute to use to pin the items. 2. From the middle dropdown list, select the logical operator. 3. As the value, you can provide a static value, an [aggregate](/docs/crm/aggregates), or an [expression](/docs/crm/expressions). 4. To add more filters, click **Add filter** and repeat all steps. 5. In the **Show maximum...** input, provide the number of items which will be pinned. 6. Optional: In the **Pin at positions** field, provide the position numbers where the pinned items will be placed, separated by `;`. If left empty, the pinned items are placed at the top of the search results. #### Hide item A selected item or items will be excluded from the search results. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/hide-item.png" class="medium" alt="Configuration of the Hide item consequence"><figcaption>Configuration of the Hide item consequence</figcaption></figure> - To add batch of items, click **Add many**. **Result**: A pop-up appears. 1. On the pop-up, in the **Add items** field, enter the IDs of the excluded items, separated by `;` 2. Confirm your choice by clicking **Add**. 3. Confirm by clicking **Apply**. - To add a single item, in the **Item** field, search for the item you want to hide, by providing its name or other identifier. **Result**: A dropdown list appears. 1. From the dropdown list, select the item. #### Filters Filter consequence types: - Elastic filter - Filters the search results to move items that meet the filter conditions higher in the results. If no items meet the filter conditions, the search results are returned unchanged. - Static filter - Filters the search results to display only the items from the search response that meet the conditions you provide. If no item from search results meet the conditions, then the list of results will be empty. <div class="content-tabs" data-tab-group="tabgrp-1244"> <div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1244-0" data-tab-group="tabgrp-1244" data-tab-active="true">Elastic</button><button class="tab-button" data-tab-id="tabgrp-1244-1" data-tab-group="tabgrp-1244">Static</button></div> <div class="tab-panel" data-tab-id="tabgrp-1244-0" data-tab-group="tabgrp-1244" data-tab-active="true"> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/rules-elastic-filter.png" class="medium" alt="Configuration of the Elastic filter consequence"><figcaption>Configuration of the Elastic filter consequence</figcaption></figure> </div> <div class="tab-panel" data-tab-id="tabgrp-1244-1" data-tab-group="tabgrp-1244"> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/rules-static-filter.png" class="medium" alt="Configuration of the Static filter consequence"><figcaption>Configuration of the Static filter consequence</figcaption></figure> </div> </div> #### Additional information - Attribute values can be strings, numbers, date ([the `created` attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#the-created-attribute) which lets you filter items based on the date of adding the item to the feed), or dynamic values: expression results or aggregate results. - You can apply a maximum of **two dynamic conditions** (a condition is dynamic when it contains an aggregate or expression) in total across all consequences of a query rule, meaning if two are used in one consequence, none can be added in others. - If two or more rules match a given phrase and use dynamic values, up to two dynamic values from the winning rule are applied according to [precedence logic](#query-rule-conflicts). - The scope of attributes for filtering is defined in the [Filterable](/docs/ai-hub/ai-search/define-attributes#filterable-attributes) and [Facetable](/docs/ai-hub/ai-search/define-attributes#facetable-attributes) attributes section in the index settings. If you want to use an attribute to a filter in query rules, remember to add it to both. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> When setting up a filter in a Query Rule, 500 distinct attribute values are returned. If there are more distinct values for an attribute and the desired value does not appear in the dropdown menu, you can input the value manually. </div></div></div> #### Instructions 1. From the **Attribute** dropdown list, select item attribute which you want to use for filtering. 2. From the dropdown list, define the logical operator (for example, **In**, **Not in**. Depending on the value type of the attribute, the range of logical operators differs). 3. By clicking the icon, select the value type of the attribute (string, number, date/relative date, aggregate, expression). 4. In the field, provide the value. 5. To add more filters, click **Add filter** and repeat all steps. #### Boost by attribute When a customer uses a particular word or phrase in a search query, this consequence lets you: - boost the importance of an item attribute (such as brand), so the items with these attributes are more likely to occur in the search results. - demote the importance of an item attribute (such category), so the items with that attribute are less likely to occur in the search results. 1. Select one of the following tabs: - to display items higher in results, select **Promote**. - to display items lower in results, select **Demote**. 1. From the **Attribute** dropdown list, select the item attribute which you want to use for filtering. You can use [the `created` attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#the-created-attribute) which lets you boost the items based on the date of adding an item to the feed. 2. From the dropdown list, define the logical operator (for example, **In**, **Not in**. Depending on the value type of the attribute, the range of logical operators differs). 3. By clicking the icon, select the value type of the attribute (string, number, date/relative date, aggregate, expression). 4. In the field, provide the value. 5. To add more filters, click **Add filter** and repeat all steps. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/boost-by-attribute.png" class="medium" alt="Configuration of the Boost by attribute consequence"><figcaption>Configuration of the Boost by attribute consequence</figcaption></figure> #### Override scoring factors This consequence lets you override the index's [scoring factors](/docs/ai-hub/ai-search/define-item-ranking#scoring-factors-manual-adjustment) for the queries that match the rule's conditions. Enabled factors override the index settings. Disabled factors fall back to the index settings. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/override-scoring-factors.png" class="medium" alt="Configuration of the Override scoring factors consequence"><figcaption>Configuration of the Override scoring factors consequence</figcaption></figure> 1. Switch on the toggle next to each [scoring factor](/docs/ai-hub/ai-search/define-item-ranking#scoring-factors-manual-adjustment) you want to override: - **Page views** - **Page views (7 days)** - **Item purchase** - **Item purchase (7 days)** - **Revenue** - **Conversion rate** - **Personalization** 2. For each enabled factor, use the slider to define the strength of its impact. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You must enable at least one scoring factor to save the consequence. </div></div></div> #### Return no results The search list will be empty. No configuration is required for this option. #### Sort query results You can organize search results according to the value of a specific item attribute in an ascending or descending order. Make sure to select attributes with values that can be put in order (like numbers). 1. From the **Attribute** dropdown list, select an item attribute which will be used for sorting. For example, you can select the price attribute, so you can organize search results from cheapest to most expensive. 2. From the **Sorting** dropdown list, select the order in which items will be sorted: - **Ascending** - Items are organized from the lowest to the highest value of the attribute. - **Descending** - Items are organized from the highest to the lowest value of the attribute. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/sort-query-results.png" class="medium" alt="Configuration of the Sort query results consequence"><figcaption>Configuration of the Sort query results consequence</figcaption></figure> #### Return custom data This is a possibility to return any custom data as a query rule consequence. The custom data is in JSON format and is located in the `extras` part of the search response object. You can also input a URL instead of a JSON. **Example**: If a query contains `forbidden word`, return customData equal to: <pre><code class="language-json">{ "custom404": "custom404.com", "forbidden-word": "forbidden word used" }</code></pre> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/return-custom-data.png" class="medium" alt="Configuration of the Return custom data consequence"><figcaption>Configuration of the Return custom data consequence</figcaption></figure> ## Multiple query rules --- ### Query rule conflicts When creating multiple rules, it is possible that their settings might cause a conflict. A conflict emerges in a situation when two query rules should be activated by the same phrase and their consequences are mutually exclusive. The result managing system resolves such conflicts according to the following rules, in order of importance: 1. Position: The earliest match wins (i.e. closest to the beginning of the query string). 2. Match length: The longest match wins (in terms of the number of words from the query string). 3. The way in which the condition matches the query, ordered from highest importance: `Is` > `Starts with` > `Ends with` > `Has`. 4. Rule ID: If there are still conflicts after all other criteria have been applied, the system takes the smallest `ruleID` in lexicographical order. In practice, this means the rule that was created first wins. This final tie-breaker rule is guaranteed to break every tie and usually occurs only when rules are duplicated. Essentially, rules are applied from the beginning of the query string to its end. ### Matching filters in multiple query rules When two or more query rule conditions are met and their consequences include [filters](/docs/ai-hub/ai-search/query-rules#filters), for example: - **Query Rule 1**: If phrase is `Shoe`, filter query results to category = “Men > Shoes” - **Query Rule 2**: If phrase is `Shoe`, filter query results to category = “Women > Shoes” You can choose the logical operator to combine those filters in the settings of your index. You can find detailed instructions in the ["Defining dependency among filters in multiple query rules" section](/docs/ai-hub/ai-search/define-language-and-separators#defining-dependency-among-filters-in-multiple-query-rules). ## Examples --- ### Promoting a new item <div class="youtube-embed youtube-facade not-prose" data-youtube-id="fNBrAX3qYMA" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to prepare an Example Rule?"><img src="https://img.youtube.com/vi/fNBrAX3qYMA/hq720.jpg" alt="Synerise Academy - AI Search - How to prepare an Example Rule?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div> When you introduce a new item in your offer, there isn’t much interaction with it at first, compared to items that were available earlier. By default, the item is at the end of the list of results. You can change this behavior and promote the item, which moves it towards the first positions in the list. For example, if you introduced a new Xbrand shoe model, you can set the following rule: `if query = Xbrand promote new Xbrand model to first position` <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> In the [AI Search Statistics](/docs/ai-hub/ai-search/ai-search-statistics), the average clicked position is available as a search statistic. You can promote an item to a specific position. </div></div></div> ### When the brand appears in search, filter results only to that brand Another case where query rules come in handy is filtering your search results. For example, you can set a rule `if query contains CoolBrand filter to brand = CoolBrand`. This way, all results will be narrowed down only to the CoolBrand products. If you want to apply such a filter for all brands, you can use facets in the following way: `if query contains {brand} filter to {brand}`. This will always filter the results to the brand in the query, if a brand is detected in it. ### Replace phone with smartphone Assumptions: - You offer items from brand XYZ in many categories (vacuum cleaners, lightbulbs, and so on). - You offer phones from other brands, but not XYZ. - You offer smartphones from brand XYZ. If you want the query "XYZ phone" to search only for smartphones, you can set the following rule: `if query is "XYZ phone" OR "phone XYZ" replace "phone" with "smartphone"` Why synonyms (another possibility in search settings) are not a solution here? Setting up a synonym would globally alter the way the search engine looks for items, it would treat "phone" and "smartphone" as equivalents. In this case we only want to manipulate the query if it contains a specific brand. ### Hiding items Sometimes you want to hide items that the search engine would consider relevant, however from a business perspective don’t make sense. For example, you have an item in your feed whose title is `red t-shirt with white sneaker` and we would like to hide this item from the search results because for some search queries it would match the query but from a business perspective it doesn't make sense to show the item. In such case, we can create a rule which hides the item with this title from search results: `if query equals "sneaker" or "sneakers", hide item which "title" is "red t-shirt with white sneaker"`. ### Filtering results by price range You can also filter the results by range attributes. A good example is for filtering within a price range. If a customer is looking for cheap books, you can set a rule: `if query is "cheap books" filter results to 'price' less than "10$"`. ### Combining consequences Sometimes you will need more than one consequence to achieve your business case. You can add multiple consequences to one condition when setting up a rule. (Xbrand smartphone – change to ULT093model, filter to Xbrand, promote latest model) For example let’s take a customer query "Xbrand smartphone". You might want to change the query to make it more relevant to your items, filter the results to Xbrand products and promote the newly released ULT093 model. You can set a rule: `if query is "Xbrand smartphone" change query to "ULT093model" and filter to 'brand' equal to "Xbrand" and promote item "ULT093" to first position`. # Creating section page recommendations Section recommendations allow Synerise users to display personalized items on the website by displaying any number of sections. The motif of each section is personalized as well as the items included in the section. It means that you can create separate areas on the website that include personalized recommendations of items based on brand, category, color, price, or any other attribute included in the item catalog. ## Distributing recommendations --- You can use the ID of the recommendation and [inject it with a snippet](/docs/assets/snippets) in other types of communication, such as: - [dynamic content](/docs/campaign/dynamiccontent) - this way you can show the recommendations on your website. - [email](/docs/campaign/e-mail) - this way you can send out recommended items through emails. - mobile application - you can use [documents](/docs/assets/documents) to build your own mobile app and show the recommended items. - [mobile push](/docs/campaign/Mobile) - you can send recommendations through notifications in your mobile application. - [web push](/docs/campaign/Webpush) - this way you can send notifications to your customers through a web browser. - [SMS](/docs/campaign/SMS) - this way you can reach your customers with recommendations on their mobile. ## Requirements --- - Create an [item catalog](/docs/ai-hub/recommendations-v2/item-feed-requirements). - You must [configure the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations): - Enable the Section page model. - In the **Attributes for distinct filters** section, you must select the attributes which will be available for use in the **Item attribute** field when [creating a section page recommendation](#configure-item-settings). In the **Item attribute** field you will choose the item feature (for example, brand) based on which the items will be selected for a slot in the recommendation. If this step is skipped, the field will remain empty, making it impossible to complete the recommendation. - Optionally, create a complementary [metadata catalog](/docs/ai-hub/item-feed/metadata-catalog) that includes additional information about items ## Select feed and recommendation type --- Select the feed from which items will be sourced to recommendations and the type of recommendations to be displayed. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Recommendations) Models > Add recommendation**. 2. Enter the name of the recommendation (it is only visible on the list of recommendation). 1. In the **Type & Items feed** section, click **Define**. 2. From the **Items feed** dropdown list, select an item feed. 3. Under **Recommendation type**, click **Select model**. 4. On the pop-up that opens, select the **Section page** model. If the recommendation is disabled, it means the AI engine is not trained yet. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Learn more about: - [recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types) - [recommendation statuses](/docs/settings/configuration/ai-engine-configuration/model-status) </div></div></div> 5. Click **Apply**. 4. Optionally, from the **Metadata catalog** dropdown, select the catalog that include additional information about items in your feed. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> More information about metadata catalogs is available [here](/docs/ai-hub/item-feed/metadata-catalog). </div></div></div> 4. Confirm the settings by clicking **Apply**. ## Configure item settings --- The next step is to define the items to be displayed in the recommendation frame. You can use slots to assign space in your recommendation frame to specific items. In the settings of a single slot, you can declare the number of items, the attribute based on which the items will be generated. A recommendation must include at least one slot. ### Adding slots 1. In the **Items** section, click **Define**. 3. Click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/analytics/_gfx/plus-button.png" alt="Plus icon" class="icon"> button. 4. If you want to name the slot, hover over the **Unnamed slot** tab and double click it. 2. When adding multiple slots, you can define their order by dragging and dropping the tabs into the desired sequence. The slot represented by the leftmost tab is considered the first slot. For more slot order options, refer to the [Define slot and item ordering](#define-slot-order) section. 5. To proceed to the slot settings, click the tab with the slot. 6. In the **Number of section** field, enter the number of rows you want to dedicate to display recommendations. 6. In the **Number of items in a section**, enter the maximum number of items to be displayed in one section. 4. From the **Item attribute** dropdown, choose the feature of the item based on which the items will be selected to the section or sections in the slot. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can't select the same attributes which are selected for the Distinct filters (step 7). </div></div></div> 5. To manage the variety of items in the sections, use **Static filters**, **Elastic filters** and **Distinct filters**. <details class="accordion"><summary>Elastic filters explained</summary><div class="accordion-content"><p>Apart from selecting the items to be displayed in the recommendation frame, the elastic filter supplements the recommendation frame if it’s not entirely filled up with items. For example, if you select to display up to 10 items, and you have only 5 items that meet the conditions of elastic filter to be displayed in the recommendation frame, then the empty slots will be filled with items which do not match elastic filter (based on scoring of each model).</p></div></details> <details class="accordion"><summary>Static filters explained</summary><div class="accordion-content"><p> When you use a static filter, it shows the fixed number of items that match the conditions of the filter. If there are not enough items to fill in the recommendation frame (the number you entered in the step 2), the recommendation frame is not displayed at all. </p> <ul> <li>If you want to <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-recommendation-types-and-default-filters">apply global item filter</a> defined for the recommendation model based on which you're creating the campaign, enable <strong>Apply Items Global Filters</strong>. Enabling this toggle applies the global item filters and they work in combination with other filters in the slot. </li> <li>If you want to apply custom static filters for the slot, click <strong>Define filter</strong>. Select one of the filter creators:<ul> <li><a href="/docs/ai-hub/recommendations-v2/recommendation-filters/#visual-builder">visual builder</a></li> <li><a href="/docs/ai-hub/recommendations-v2/recommendation-filters/#iql-query">IQL query wizard</a></li> </ul> </li> </ul></div></details> <details class="accordion"><summary>Distinct filters explained</summary><div class="accordion-content"><p>When you use a distinct filter, you increase the variety of items included in the slot. You can define exactly the allowed number of items that share the same attribute value to be shown, for example, a number of items that have the same brand, color, shape, category, and so on.</p> <ul> <li>If you want to <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-recommendation-types-and-default-filters">apply global distinct filter</a> defined for the recommendation model based on which you're creating the campaign, enable <strong>Apply Global Distinct Filters</strong>. Enabling this toggle applies global distinct filters to the slot and it overrides the settings of slot distinct filter. </li> <li>If you want to apply custom distinct filters for the slot, click <strong>Define filter</strong>. <ol> <li>In the <strong>Show only</strong> field, enter the number of items whose attribute values can be the same.</li> <li>From the <strong>Choose attribute</strong> dropdown list, select the attribute.<br> You can use each attribute only once. This means that if you add multiple filters, any attribute that has already been used will no longer be available for selection. </li> <li>To add more conditions, click <strong>Add another</strong> and repeat the steps.</li> <li>If you want the distinct filter to supplement the slot with non-matching items in case not enough matching items are found, enable the <strong>Mark filter as elastic</strong> option.</li> <li>Confirm by clicking <strong>Apply</strong>.</li> </ol> </li> </ul></div></details> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> - You can read how to build conditions based on the `category` attribute [here](/docs/ai-hub/recommendations-v2/recommendation-filters#the-category-attribute). - You can learn more about [filters](/docs/ai-hub/recommendations-v2/recommendation-filters) in recommendations and see [examples of use](/docs/ai-hub/recommendations-v2/recommendation-filters-examples). </div></div></div> 7. Save the changes by clicking **Apply**. ### Define slot order --- In this section, you can define the order of slots. However, defining the order of items within the slots is impossible for this recommendation type. Instead, the items are automatically arranged based on the Personalized recommendation model. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/slot-ordering.png" alt="A form for configuring slot order" class="large"> <figcaption> A form for configuring slot order </figcaption> </figure> 1. In the **Slots and items ordering** section, click **Define**. 2. To define the order of slots and order of items within the slots, in the **Slots and items ordering** subsection, select one of the following options: - **Arrange items in slot order**: - the slots will be presented in the order defined in the **Items** section. - the order of items is arranged based on results from the Personalization model. - **Arrange items ignoring slots and its order**: the slots will be ignored and the order of items will be arranged according to results of from Personalized model. ### Define the boosting factors --- You can increase probability of appearing in the recommendation frame. You can boost the items in three ways (both can be used at the same time): - **Metric** boosting uses pre-defined item popularity metrics to influence item scoring. Metric boosting is available only for the Similar, Cart, Visual similarity recommendation types. - **Attribute** boosting influences item scoring depending on rules applied to the item's attributes. This is done by applying a filter to items and adjusting the score of those items that match the filter. For example, you can increase the scoring of a particular brand without excluding other brands entirely. - **Personalization** boosting uses the personalization model to influence the items' scoring according to the preferences of each customer - items that fit their preferences have a higher probability of appearing in the recommendation frame. You can manage the influence of personalization model on boosting by using the Impact scrollbar. Personalization boosting is available for all recommendation types, except for Personalized, Section, and Attribute. This element has a significant impact on the model's outcome. For instance, if we set the personalization impact to 80% in the recommendation model based on **Top items**, the suggested items will be influenced mostly by the personalization model (making up 80% of the impact). Meanwhile, the **Top items** model will only contribute 20% to the recommendations (along with other factors like boosting attributes). <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recov2-boosting.png" class="large" alt="An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting"><figcaption>An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting</figcaption></figure> 1. In the **Boosting** section, click **Define**. 2. **Metric boosting**: 1. Click **Select** and select a metric to use for adjusting the score. 2. Choose the **Promote** (default) or **Demote** option. 3. Use the slider to determine how much you want the metric to influence the score of the items. 3. **Attribute boosting**: 1. Click **Add rule**. 2. Click the created rule to open its settings. 3. In the **Items scope** section, click **Define filter**. Items that meet the filter will have their scores adjusted. To learn how to build filters, see [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters). 4. Choose the **Promote** (default) or **Demote** option. 5. Use the slider to determine how much you want the metric to influence the score of the items. 4. **Personalization**: 1. Enable the **Personalization** toggle. 2. From the Impact scrollbar, select how much you want the personalization model to influence the arrangement of items in the recommendation. 4. Confirm the settings by clicking **Apply**. ### Additional settings --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-additional-settings.png" class="full" alt="The Additional settings section in the configuration form"><figcaption>The Additional settings section in the configuration form</figcaption></figure> 1. In the **Additional settings** section, click **Define**. 2. If you want to exclude items that the customer already purchased, enable the **Exclude already bought products** option. This option will exclude up to 100 items that were purchased within a specific number of days, as defined in the **Since** field, which appears after enabling the option. Optionally, you can also set this option as elastic, which will work as an [elastic filter](/docs/ai-hub/recommendations-v2/recommendation-filters#elastic-filter). 5. If you want to source the item context from an aggregate or expression results instead of the website, enable the **Item context from analytics** toggle. Then from the dropdown list, select the analysis whose result will be treated as the item context. On the basis of the item context, the engine selects the items to display in the recommendation. By default, the recommendation sources the item context from the product page where it is implemented. This option lets you override this setting, so the item context will be taken from the result of the aggregate or expression that returns for example, a recently viewed item, favorite items, recently purchased items or items purchased the most frequently. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is available for all recommendation types except for Recent interactions and Last seen. </div></div></div> 6. Optionally, you can assign a slug to the recommendation. In such a case, enable the **Recommendation slug** toggle. This option lets you assign a user-friendly, unique identifier of the recommendation which you can use to fetch recommendation campaign instead of its ID. The slug can be edited at any time. In the **Enter unique slug name** field, enter the name containing 3 to 25 characters. You can only use: - lowercase Latin alphabet letters (a-z) - digits (0-9) - `-` but it can't be the first and/or last character 7. If you want to use [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) to recommend items from across all your grouped workspaces, enable the toggle in the **Co-Brand Personalization** section. This toggle is available if your workspace uses [co-brand decisioning layer feature](/docs/settings/workspace/multibrand-workspaces). To enable it, contact the Synerise support. The badge next to the option name indicates the mode configured for your workspace group by the Synerise support team. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/co-brand-personalization.png" class="medium" alt="The Co-Brand Personalization section in the configuration of the AI Recommendation campaign"><figcaption>The Co-Brand Personalization section in the configuration of the AI Recommendation campaign</figcaption></figure> 8. To confirm the settings in the **Additional settings** section, click **Apply**. ### Saving the recommendation --- To save the recommendation: - as a draft, click **Finish later**. - and activate the recommendation, click **Save**. Once you activate the recommendation, you can use it as described in the [Distributing recommendations](#distributing-recommendations) section. # Creating lookalikes predictions In this article, you will get know how to set up your first Lookalikes prediction. Lookalikes let you compare two segments of customers and find those who display similar qualities of performance. This can be used, for example, to target a marketing campaign at customers alike to those who reacted well to a previous iteration of that campaign. You can create a lookalike prediction from scratch or by using a predefined scenario: "Find best matching customers for an annual/seasonal campaign". Predefined scenarios are configured using a user-friendly wizard that allows you to adjust scenario settings according to your preferences. This is done through a step-by-step configuration form, which provides hints on the interface to guide you. The option of creating a prediction based on a predefined scenario is available in the initial part of creating the prediction ([Select the model type](#select-the-model-type)). ## Prerequisites --- - [Configure AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity). - [Enable the Lookalikes predictions](/docs/ai-hub/predictions/enabling-predictions#enabling-lookalikes). It usually takes several hours to initialize Predictions and perform necessary calculations. - You should know how to create [segmentations](/docs/analytics/segmentations) or have a segment of customers ready for use as the source. ## Configure a prediction ### Select the model type 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Predictions) Models**. 2. Click **New prediction**. 1. On the pop-up select one of the following options: - **Use predefined prediction** - This option allows you to use the ready-made prediction scenarios and adjust its settings to your preferences in a user-friendly, step-by-step configuration form by following hints shown on the interface. If you select this option, you can skip reading the rest of the article. - **Create from scratch** - This option allows you to create your own configuration of a lookalikes prediction to achieve your custom business objective. If you use this option, select **Lookalikes**. ### Select source and target The **Audience** section of the prediction configuration include the definitions of two segments. - The **source** segment contains the "model" customers. This can be, for example, a segment of customers with the best reaction to a past marketing campaign. - The **target** segment contains customers who you want to compare with the source segment and find the ones who are similar to the source group. 1. In the **Audience** section, click **Define**. 1. In the **Source segmentation** sub-section, click **Choose segmentation**. 2. Perform one of the following actions: 1. Select an existing segmentation (you can use the search field). 2. Click **Create new** and create a new segmentation. Instructions for creating segmentations are available [here](/docs/analytics/segmentations). The segmentation will also be available for later use in the list of segmentation. 4. In the **Source segmentation** sub-section, choose or create a segmentation in the same way as the target. 5. Click **Apply**. ### Additional configuration By default, the calculation is performed once and the results are presented on a 5-point scale. 1. If you want to leave the settings as default, the predictions is ready to calculate. Continue to [saving the prediction](#save-the-prediction). 2. If you want to change the settings, in the **Settings** section, click **Change**. 3. To schedule a recurring calculation: 1. Select the **Set up recurring prediction calculation** checkbox. 2. In the input field, enter the number of days between calculations. 4. To change the scale from 5-point to 2-point, select the **2-point scale** radio button. 5. Click **Apply**. ### Save the prediction To save the prediction: - as a draft, click **Save**. - and calculate, click **Save & Calculate**. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can check the logs of the activated prediction. [Learn more](/docs/ai-hub/predictions/predictions-functionalities#previewing-logs). </div></div></div> ## Results The maximum calculation time is 24 hours. When it ends, the results are saved as events in the profiles of all customers of the target segmentation. The `score_label` parameter of the event shows the scale of similarity on a 2- or 5-point scale. You can use these events, for example, to build a new segmentation for use as the target of a marketing campaign. ## Understanding Lookalikes prediction events The outcomes of all custom predictions are saved as `snr.lookalike.score` events in the Synerise platform. Thanks to that, the predictions events are available in Decision, Experience or Automation Hubs. The schema of a prediction event is standardized. The attributes are explained in the table below the figure. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/lookalike-event.png" alt="snr.lookalike.score event" class="full"> <figcaption>snr.lookalike.score event</figcaption> </figure> | Attribute name | Description | |-------------|-------------------------------------------------------------------------------------------------| | action | An event type for the prediction - `snr.lookalike.score` | | added by | An entity that generated this event. In the case of prediction events, it is always Synerise. | | modelId | A unique identifier of the prediction | | modelName | The name of the prediction | | score_label | Prediction output: two- or five-point scale label. You can select the scale in the [settings of the prediction](#additional-configuration). | | score | The result of the prediction (based on the expression which was selected as a target while preparing a prediction). | | percentile | [Prediction percentile](/glossary/#percentiles) | | clientId | Customer's identifier | | time | Time when a prediction was generated, as a Unix timestamp | | configurationVersion | Allows to verify whether two consecutive calculations ran with the settings (*only for debug*) | | modelVersion | Model version allows to verify whether two consecutive calculations ran on the same model parameters (*only for debug*) | # Add synonyms In the **Synonyms** section, you can add and manage word substitutes for your search index. Synonyms expand search results so that customers find what they're looking for even when they use different terminology than what appears in your product catalog. Synonyms can be added manually, imported from a CSV file, or proposed automatically by AI agents that analyze search patterns and product data. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can also manage typos through a dedicated [Handling typos and missing words](/docs/ai-hub/ai-search/define-typos-handling) article and [query rules](/docs/ai-hub/ai-search/query-rules). </div></div></div> ## Synonym types --- Each synonym pair works in one of two directions: - **One-way synonyms** work in one direction only. For example, if "TV" is the source term and "television" is its synonym, searching for "TV" returns television products — but searching for "television" does not return TV results. - **Two-way synonyms** work in both directions. Terms are treated as fully interchangeable and grouped together. For example, if "smartphone", "phone", and "mobile" are two-way synonyms, searching for any of these terms returns the same results. ## Synonym states --- Every synonym has a state that indicates its origin and whether it requires your attention: | State | Description | |---|---| | **Accepted** | An active synonym — either one you created manually or an AI proposal you approved. | | **Rejected** | An AI proposal you dismissed. | ## How synonyms are created --- Synonyms come from three sources: - **Manual** — You enter synonyms one by one directly in the interface. - **CSV import** — You upload a file containing multiple synonyms at once. - **AI agents** — The system automatically proposes synonyms and submits them as Suggested for your review and manual activation. These synonyms are based on: - **User activity** — The agent uses time-window analysis to detect patterns where users search for one term, then quickly search for a related term within the same session, indicating a synonym relationship. - **Product catalog data** — For indexes with no search history yet, the agent can analyze your product catalog to generate relevant synonym proposals ([cold start option](#initial-synonym-generation-cold-start)). ## Requirements --- For imported synonyms: - The file must be encoded in UTF-8; UTF-8 BOM is not supported. - Use commas as the word separator. For synonyms proposed by AI agents: You must have a history of [`item.search` events](/docs/assets/events/event-reference/search#itemsearch) with the `searchType` parameter set to `full-text-search`. The agent analyzes search reformulations — sessions where a user searched for one term and then quickly searched for a related term — so events from such searches must be collected. This requirement does not apply to the cold start option. ## Adding synonyms manually <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Changes to synonyms are reflected within 30 minutes to several hours, depending on the size of the index. </div></div></div> ### Procedure 1. Go to **AI Hub > Indexes**. 2. In the list, click the index to which you want to add synonyms. 3. Under the name of the index, select the **Synonyms** tab. 4. Click **Add synonym**. 5. From the dropdown list, select **Add synonym**. 1. From the left dropdown list, define the type of the synonym: - **One way** 1. In the **Word** field, enter the source term. 2. In the **Synonym** field, enter the synonym for the word. - **Two ways** 1. In the **Synonyms** field, enter the terms that are interchangeable with each other. 2. To add more synonyms, click **Add synonym**. 3. To save the list, click **Add**. **Result**: The synonyms will be added and they will be assigned the **Accepted** status. ## Adding synonyms by CSV import 1. Go to **AI Hub > Indexes**. 2. In the list, click the index to which you want to add synonyms. 3. Under the name of the index, select the **Synonyms** tab. 4. Click **Add synonym**. 5. From the dropdown list, select **Import CSV**. 1. Choose the import method: - **Replace** — Deletes all existing synonyms added through the import and saves the ones from the file. - **Add** — Adds the synonyms from the file to the existing list. 2. Upload a CSV file. - The imported synonyms will get the **Accepted** status. - See [example CSV files](#example-csv-files). ### Example CSV files --- #### One-way synonyms only <pre><code class="language-plaintext">word,synonyms,type phone,smartphone,oneway</code></pre> If a customer enters `phone`, results include smartphones. Searching for `smartphone` returns only smartphones — not phones. #### Two-way synonyms only <pre><code class="language-plaintext">word,synonyms,type ,"computer,PC",synonyms</code></pre> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The first column is empty; all synonyms are in the second column. </div></div></div> The search engine returns the same results for `computer` and `PC`. #### One-way and two-way synonyms in one file <pre><code class="language-plaintext">word,synonyms,type phone,smartphone,oneway ,"computer,PC",synonyms</code></pre> - The first row defines a one-way synonym: searching for `phone` returns smartphones, but not the reverse. - The second row defines two-way synonyms (first column is empty): `computer` and `PC` return the same results. ## Adding synonyms by Synonym Agent ### Enable the Synonym Agent --- Before AI agents can propose synonyms, you must enable the Synonym Agent in the index settings. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Enabling the Synonym Agent may generate additional costs related to LLM usage. AI-generated suggestions may occasionally be inaccurate. </div></div></div> #### Procedure 1. Go to **AI Hub > Indexes**. 2. Click the index you want to configure. 3. Under the name of the index, select the **Settings** tab. 4. Find the **Synonym Agent** section. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/synonyms-agent-tab.png" class="large" alt="Synonym Agent settings section showing the agent in a disabled state"><figcaption>Synonym Agent settings section showing the agent in a disabled state</figcaption></figure> 5. Toggle the switch from **Disabled** to **Enabled**. **Result**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/synonyms-agent-enabled.png" class="large" alt="Synonym Agent settings section showing the agent in an enabled state"><figcaption>Synonym Agent settings section showing the agent in an enabled state</figcaption></figure> 6. In the **Suggestion frequency** section, select how often the agent proposes new synonyms: - **Monthly** — Uses more data for higher confidence, but learns more slowly (every 30 days). - **Weekly** — Faster training, lower confidence. 7. Click **Apply**. **Result**: The agent runs at the selected frequency and proposes synonyms in the **Synonyms** tab. When the [synonyms suggestions will be ready for review](#review-ai-proposed-synonyms), a notification banner will appear on the list of synonyms. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you disable the agent, it is queued for shutdown and stops running at the next scheduled time. </div></div></div> ### Initial synonym generation (Cold start) For new indexes with no search history, you can trigger a one-time synonym generation based on your product catalog data. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Cold start is a single-use operation. Once it completes, it cannot be run again for that index (even after you disable and enable the Synonym Agent). </div></div></div> To run the cold start: 1. In the **Synonym Agent** section, find **Initial synonym generation (Cold start)**. 2. Toggle the switch to enable it. 3. Click **Apply**. ### Review AI-proposed synonyms --- AI agents run on a recurring schedule and propose new synonyms based on search behavior and catalog data. When the synonyms suggestions are ready for review, a notification banner appears on the list of synonyms. #### Procedure 1. Go to **AI Hub > Indexes**. 2. Click the index you want to manage. 3. Select the **Synonyms** tab. **Result**: A notification banner is displayed above the synonym list. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/new-synonyms-suggestions-banner.png" class="large" alt="Synonyms tab with a notification banner informing that the Synonym Agent has generated new synonym suggestions and prompting to review and approve them"><figcaption>Synonyms tab with a notification banner informing that the Synonym Agent has generated new synonym suggestions and prompting to review and approve them</figcaption></figure> 4. On the notification banner, click **Review suggestions**. **Result**: A pop-up appears. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/suggested-synonyms.png" class="large" alt="Synonym Agent pop-up showing the Suggested tab with a list of AI-proposed one-way synonyms, each with a confidence score and options to accept, reject, or edit"><figcaption>Synonym Agent pop-up showing the Suggested tab with a list of AI-proposed one-way synonyms, each with a confidence score and options to accept, reject, or edit</figcaption></figure> 5. Review each proposal and decide: <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Accepting and rejecting synonyms is irreversible. </div></div></div> - Accept the synonym. - Reject to dismiss the proposal. - Edit the proposal. When you edit the proposal, you save and accept the edited proposal, this action is irreversible. Accepted synonyms become active with the **Accepted** state. Rejected proposals are retained with the **Rejected** state for reference. # Define item ranking You can define the criteria for sorting items in search results. Customizing these settings lets you align with customers' behaviors and preferences and increases chances for relevant search results. You can rank items either by manually adjusting scoring factors or by enabling target optimization, which automatically manages the scoring factors for a selected business target. ## Scoring factors (manual adjustment) --- Scoring factors define whether and how strongly a given metric affects the order of items in search results. For each enabled scoring factor, use the slider to define the strength of its impact. - **Page views** - Boost items which were frequently viewed by customers. - **Page views (7 days)** - Boost items which were frequently viewed by customers over the last 7 days. - **Item purchase** - Boost items which were frequently purchased by customers. - **Item purchase (7 days)** - Boost items which were frequently purchased by customers over the last 7 days. - **Revenue** - Boost items which generate the highest revenue. - **Conversion rate** - Boost items with the highest ratio of purchases to clicks in search results. - **Personalization** - Boost search results based on the individual user's preferences. ## Target optimization (automatic adjustment) --- Instead of manually defining scoring factors, you can enable target optimization to automatically optimize the ranking weights for a selected business target. When a target is selected, it replaces the manually defined scoring factors listed above, except **Personalization**, which you can still configure separately. You can choose one of the following optimization targets: - **Click-through rate** - Optimizes the ranking to increase the likelihood that customers click items in the search results. - **Conversion rate** - Optimizes the ranking to increase the likelihood that customers purchase items after clicking them in the search results. - **Revenue** - Optimizes the ranking to increase the revenue generated from the search results. - **Ranking quality (NDCG)** - Optimizes the ranking quality using Normalized Discounted Cumulative Gain, a metric that measures how well items are ordered by relevance. - **Margin** - Optimizes the ranking to boost items with the highest profit margin. This option is in [private preview](/docs/log-in-and-navigate-synerise-platform#private-preview) mode. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-search-ranking.png" class="medium" alt="Configuration of ranking"><figcaption>Configuration of ranking </figcaption></figure> ## Configuration --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. [Create](/docs/ai-hub/ai-search/create-index) or select the index on the list. 3. Go to the **Settings** tab. 4. On the **Ranking** section, click **Define**. 5. Do one of the following: - To automatically manage scoring factors, switch on the **Enable target optimization** toggle, then from the **Choose optimization target** dropdown list, select one of the [optimization targets](#target-optimization-automatic-adjustment). - To manually define scoring factors, switch on the toggle next to each [scoring factor](#scoring-factors-manual-adjustment) you want to include, then use the slider to define how strongly it affects the order of items in the search results. 6. Click **Apply**. # Define attributes The attribute filters allow you to define which item features are available in the search results, which features the customers can use to filter the results, and so on. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-search-attributes.png" class="full" alt="The configuration of attributes in AI Search"> <figcaption>The configuration of attributes in AI Search</figcaption> </figure> ## Configuration --- 1. Go to **AI Hub > Indexes**. 2. [Create](/docs/ai-hub/ai-search/create-index) or select the index on the list. 3. Go to the **Settings** tab. 4. Each attribute type has a separate section, to select or remove added attributes on the dedicated section, click **Define**. You can define the following attributes: <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The settings are saved automatically as you modify them. </div></div></div> ### Response attributes This section defines which attributes will be included in the search response. For each item returned, only attributes defined in this section will be available in the search response. Only attributes defined in this section will be available in the search response so you can show them to the customers. ### Filterable attributes Filterable attributes are those that are enabled for use in item filters for including or excluding results. Including an attribute value narrows down the search results to items with that attribute value. Excluding values of an attribute displays results with items that have different values of these attributes. #### Examples - Products in your catalog have the `sale` attribute which can take the `true` (on sale) or `false` value. Include `sale` as a filterable attribute. Now, you can filter the results by the items' sale status. - Products in your catalog have the `last_item` attribute that can take the `yes`(one item is available) or `no` (more than 1 item is on stock) values. Exclude `last_item` as a filterable attribute. Now, you can filter the items that have one item left from the search results. - You want to filter out the products that cost more than $100. Include `price` as the range-type filterable attribute and in the settings, filter items where `price` is equal to or greater than 100$. ### Facetable attributes Choose attributes that can be use as facets. Facets allow customers to sort search results by attributes and their values. For example, you can use the `color` attribute as facetable to let the customers select which colors they're interested in. The search result also includes information how many items have a particular value of a facetable attribute. For a live example, see our [use cases](/use-cases). "Challenges", "Channel", "Difficulty", and so on are facetable attributes. #### Example You want to give a customer a possibility to filter results by some attributes - `color` and `brand`. Add these attributes to the **Facetable attributes** section. When this is done, the customers will be able to narrow down the results of the filter to desired brand and color of the item and additionally they will be shown information about the number of items in each facet in the search response. This information can be displayed along with the search results and based on that filtering can be applied to the results. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> To let AI automatically select the most relevant facets per query, see [Automatic Facets](/docs/ai-hub/ai-search/automatic-facets). </div></div></div> <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> 1. The returned facets in the search response contain the top 50 distinct attribute values. 2. The sum of distinct attribute values, for filterable and facetable attributes, can't exceed 10000. That means that if the X attribute has 5000 different values and the Y attribute has 5000 different values, they cannot be used in filterable attributes at the same time. Remember that 10000 distinct values are shared for filterable AND facetable attributes. Therefore, we do not recommend filtering and/or faceting with attributes that have many distinct values in the item feed. </div></div></div> ### Sortable attributes You can enable sorting the results by the chosen attributes. You can add both range and text attributes. Sorting by range attributes allows you to arrange the returned items from highest to lowest value of the specified attribute. Sorting by text attributes allows you to order the results in an alphabetic order, ascending or descending. ### Distinct attributes Distinct attributes are item attributes applied as distinct filters. This can be used to increase result variety or deduplicate item variants. You can select multiple attributes. When [previewing search results](/docs/ai-hub/ai-search/previewing-search-engine-results), you can enable or disable the distinct filter to test how each state affects results. To apply distinct filters to real search results, use the `distinctFilter` parameter in the API, for example in the [Full-text item search](https://hub.synerise.com/api-reference/all#tag/Search/operation/SearchFullTextGet) method. ### Disabling prefix search You can disable the prefix search for specific attributes. This will prevent the search engine from trying to autocomplete the phrase for these attributes. Keep in mind that if the search engine will not find any items for the phrase it will still try to check for typos. # Creating promotions for entire basket Promotions let you prepare customized, special offers for your customers. This particular promotion lets you reduce the value of the whole shopping cart if its value matches the fixed price limit. Some settings — such as the promotion code format, cashback rules, basket pricing, and security options — apply to all promotions workspace-wide and can be configured in [Loyalty](/docs/settings/configuration/loyalty). ## Requirements --- - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise. - Import a list of stores to [Catalogs](/docs/assets/catalogs). - If you want to limit the promotion to customers with a certain loyalty score, verify with your administrator that loyalty points are being calculated. - If you want to use [promotion tags](/docs/ai-hub/promotions/promotion-tags), the tags must be in a `promotion`-type folder. ## Promotion statuses --- When you create a promotion in Synerise user interface, it gets a status which describes the progress of a promotion campaign: - **Draft** - The promotion isn't published. - **Published** - The promotion has been published and the system automatically [assigns](/docs/ai-hub/promotions/introduction-to-promotions#assigned) the promotion to the customers who meet its conditions. - **Hidden** - The promotion is published, but it is not visible in the channels it's distributed through. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotions-list.png" alt="A fragment of the promotion list" class="full"><figcaption>A fragment of the promotion list</figcaption></figure> ## Promotion limits --- ### Global limit This sets a cap on how many times the promotion can be activated, regardless of individual usage. Once this global limit is reached, the promotion becomes unavailable to everyone. - This event is generated when a [mobile SDK](/developers/mobile-sdk/loyalty#working-with-single-promotions) or [API](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions) method is used to try activating a promotion that reached its global limit. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The list of endpoints to which the request generates this event is listed in the ["Active" section](/docs/ai-hub/promotions/introduction-to-promotions#active). </div></div></div> - Changing global limits on an active promotion: - Changing the limit type (**unlimited**, **lifetime**, **relative date**) resets limit counter, and counting will start fresh from the time of the change. - Changing the limit value within a limit type is allowed and doesn't reset the counter. - The limit counter has a 365-day time-to-live, so activations beyond 365 days ago are excluded from the count. ### Per customer - Single - For promotions that can only be used once per activation. With this logic, you can set a maximum number of times a customer can activate a promotion. - Multibuy - For promotions that can be used a defined number of times per activation. With this logic, you can set limit on activations and how many times a promotion can be used within one activation. Full instruction on imposing promotion limits is described in the ["Types & limits" section](#type--limits). ## Procedure --- For your reading convenience, the procedure is divided into sections according to the UI. **You must complete all of the sections.** If you want to save a draft for later completion, click the **Finish later** button in the upper-right corner of the page. You can do this at any point of the procedure. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you click **Finish later** while working on a published promotion, it returns to draft status. </div></div></div> ### Creating a new promotion 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. In the upper-right corner of the page, click **Add promotion**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotion-type-selection.png" alt="Selection of the promotion scope" class="large"><figcaption>Selection of the promotion scope</figcaption></figure> 3. Enter a name for the promotion.<br> 4. To inform other users about the purpose of the promotion, enter a description. 5. Select the **For entire basket** option. **Result:** The default settings are applied to the promotion. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotion-empty-cart.png" alt="A blank promotion" class="large"><figcaption>A blank promotion</figcaption></figure> ### Audience Select an audience for the promotion by performing one of the following actions: - If you want to create a promotion for everyone (default setting), no actions are required. - If you want to create a promotion for one or more customer segments: 1. In the **Audience** section, click **Change**. 2. Select **Segment**. 3. Click the **Select segment** button. 4. In the pop-up that opens, select the checkboxes of the segments that you want to include. 5. Click **Apply**. The pop-up closes. 6. Click **Apply**. ### Content 6. In the **Content** section, click **Define**. 7. **Optional:** In the **Promotion code**, modify the default promotion code. The default code is unique. If you enter a new code, it must be unique too. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you use Synerise as [loyalty engine](/docs/ai-hub/promotions/introduction-to-promotions#full-variant), the POS uses this code to redeem the promotion. </div></div></div> 8. In the **Price** field, enter `0`. This field is deprecated. 9. In the **Price before discount** field, enter the price that will be displayed as the original price. 10. In the **Display name** field, enter a customer-visible name for the promotion. 11. In the **Description** field, enter a customer-visible description for the promotion. 12. Add thumbnails in one of the following ways: - If you want to add thumbnails from the database, click **Media manager** and choose a file from the list that opens. - If you want to upload a file, drag and drop the file to the **Thumbnails** field or click **browse** and choose a file from your local storage. 13. Add images in one of the following ways: - If you want to add thumbnails from the database, click **Media manager** and choose a file from the list that opens. - If you want to upload a file, drag and drop the file to the **Images** field or click **browse** and choose a file from your local storage. 14. To add tags to the promotion, click **Add tag** and choose a tag. 15. To add JSON code with advanced params, click **Advanced options** and paste the JSON code into the text box that appears. 16. Click **Apply**. ### Type & limits 17. In the **Type & limits** section, click **Change**. 18. From the **Type** drop-down list, select the promotion type. - **General** promotions are available to all customers. - **Custom** promotions are a category that has no special requirements. You can use this category, for example, to store promotions shown in a particular place in your application. - **Members only** promotions are available to customers who joined a loyalty program. - **Handbill** promotions can be selected by the [AI promotion engine](/docs/ai-hub/personalized-promotions/introduction-to-ai-promotions) for a customer. Selecting this promotion type requires [defining cashback rules](#define-cashback-rules). 19. Enter a priority for the promotion. Priority defines the order of display in the customer's view. 1 is the highest priority. If two or more promotions applicable to a customer have the same priority, the order of display is determined by the AI engine. 20. Choose the promotion logic: - For promotions that can only be used once per activation, choose **Single**. With this logic, you can set a maximum number of times a customer can activate a promotion. - For promotions that can be used a defined number of times per activation, choose **Multibuy**. With this logic, you can set limit on activations and how many times a promotion can be used within one activation. 22. In the **Limit per profile** field: - for **Single** promotion logic, enter how many times the promotion can be activated. A promotion can be used once per activation. Redemption settings will be defined in the further part of the process, in the **Redemption type** field. <details class="accordion"><summary>Click here to see example scenario and its configuration</summary><div class="accordion-content"><table> <thead> <tr> <th>Scenario</th> <th>Configuration</th> </tr> </thead> <tbody><tr> <td>A customer can activate the promotion three times. During each activation, the customer can apply a 10% discount to the entire purchase once, regardless of the basket value. The promotion will be redeemed after the first usage, however, the customer will still have two more activations available for use.</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/single-full-cart.png" class="medium" alt="Example configuration of Single promotion logic"><figcaption>Example configuration of the Single promotion logic </figcaption></figure></td> </tr> </tbody></table></div></details> - for **Multibuy** promotion logic, define how many times the promotion can be activated. In the **Number of usage per activation** field, enter the number of times the promotion can be used in a single activation. Redemption settings will be defined in the further part of the process, in the **Redemption type** field. <details class="accordion"><summary>Click here to see example scenarios and its configurations</summary><div class="accordion-content"><table> <thead> <tr> <th>Scenario</th> <th>Configuration</th> </tr> </thead> <tbody><tr> <td>A customer can activate the promotion three times. During each activation, the customer can apply a 10% discount to the entire purchase twice, regardless of the basket value. The promotion will be redeemed after it has been used a total of six times (resulting from three activations with two promotion uses per activation).</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/multibuy-partial-cart.png" class="medium" alt="Example configuration of Multibuy promotion logic"><figcaption>Example configuration of Multibuy promotion logic - partial redemption</figcaption></figure></td> </tr> <tr> <td>A customer can activate the promotion twice. Within each activation, the customer can employ a $20 discount on the entire purchase twice, regardless of the basket value. The promotion is considered redeemed after the first usage; however, the customer will still have one activation available for use.</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/multibuy-full-cart.png" class="medium" alt="Example configuration of Multibuy promotion logic"><figcaption>Example configuration of Multibuy promotion logic - full redemption</figcaption></figure></td> </tr> </tbody></table></div></details> 25. In the **Promotion global limits** section, define the [promotion global limits](#global-limit). - Changing the limit type (**unlimited**, **lifetime**, **relative date**) resets limit counter, and counting will start fresh from the time of the change. - Changing the limit value within a limit type is allowed and doesn't reset the counter. - The limit counter has a 365-day time-to-live, so activations beyond 365 days ago are excluded from the count. 1. Select one of the following tabs: - **Unlimited** - to set the promotion without an activation limit. This is the default setting. No further configuration is needed. - **Lifetime** - to set a limit without time range. In the **Activation global limit** field, enter the number of times a promotion can be activated by all profiles collectively. - **Relative** - Sets a limit that applies within a time window relative to each activation (for example, counting activations within a day of each activation request). This means the system checks how many promotions have been activated within a defined time window before the current activation attempt. 1. In the **Activation global limit** field, enter the number of time a promotion can be activated by all profiles collectively. 2. In **Time range**, choose the period for counting the limit. **EXAMPLE**: - **Activation time**: October 12, 2025, 10:00 AM - **Limit window:** 1 day When activating the promotion, the system checks how many activations occurred from October 11, 2025, 10:00 AM to October 12, 2025, 10:00 AM. If this number exceeds the global limit, activation is blocked. 24. In the **Cart** section, define the price range which qualifies the shopping cart to get a discount. 24. From the **Discount type** drop-down list, select one of the following discount types: - **None** does not grant any discount, you can use it for displaying information banners. - **Percentage** sets the discount amount as a percentage of the original price. Example: if the original price is 1.00 USD and **Value** is `20`, the final price is 0.80 USD. - **Amount** sets a fixed discount amount to subtract from the original price. - **Cashback** lets an end user decide how many loyalty points to redeem for a discount when completing a transaction. Selecting this discount type requires further configuration described in the ["Define cashback rules" section](#define-cashback-rules). 25. In **Discount mode**: - to grant a fixed discount (the same discount amount for each purchase), select **Static**. Then in the **Value** field, enter a value for the type selected in **Discount type**. - to apply step discounts (each purchase triggers a higher discount), select **Steps**. Then, in **Transaction number**, provide the transaction number, which represents the purchase sequence, along with the discount value (**Discount value**) assigned to that transaction. 26. From the **Redemption type** dropdown, select whether the promotion is redeemed after one or more usages. 26. Click **Apply**. #### Define cashback rules If you selected Cashback as a discount type, proceed according to the instructions below. The cashback promotions can be activated with the following endpoints: - [Activate a promotion](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/ActivateAPromotion) `/v4/promotions/promotion/activate` <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The `maxTransactionPercentage`/**Limit by transaction percentage value** limit does not apply since there is no cart context. Instead, the system will redeem either the number of points specified in `pointsToUse` or, if higher, the maximum allowed by `maxTransactionAmount`. </div></div></div> - [Process basket](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/processSale_POST) `/v4/promotions/v2/sale/process-sale/{identifierType}/{identifierValue}` #### Procedure 1. In the **Digital Cashback rules** section, select one of the following tabs: - **Global rules** - If you want to configure the global settings for cashback, select this tab. Once defined, these settings will be automatically applied whenever you create a promotion of the cashback discount type and choose to use the global rules for that promotion. The global cashback rules can only be defined on the interface in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/settings-icon.svg" alt="Settings icon" class="icon"> **Settings > Loyalty program**. The instructions are available at [Loyalty](/docs/settings/configuration/loyalty). - **Custom** - If you want to define the cashback rules only for the promotion you're creating, use the **Custom** tab. Then, proceed to further configuration of cashback rules: 1. In **Define a points-to-cash conversion multiplayer**, enter how many loyalty points equal one unit of currency. 2. In **Minimum points required**, enter the minimum number of points which can be used. 3. In **Maximum points allowed**, enter the maximum number of points that can be used. 4. In **Limit by transaction value**, enter the maximum transaction value that can be covered by cashback. 5. In **Limit by transaction percentage value**, define the maximum percentage of the transaction value that can be covered by cashback. 2. Confirm by clicking **Apply**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/cashback-rules.png" class="medium" alt="Configuration of custom cashback rules"><figcaption>Configuration of custom cashback rules</figcaption></figure> ### Schedule 1. In the **Schedule** section, click **Change**. 2. In the **Display time** sub-section, choose when the promotion becomes visible to customers. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> A promotion must be published to be visible. Publishing the promotion is the last step in this procedure, after all the settings are made. "Immediately" means "immediately after publishing". </div></div></div> 3. **Scheduled promotions only**: Set the time when the promotion is visible to customers by picking dates in the **Start** and **End** fields. 4. In the **Activity time** sub-section, define the time when the promotion can be activated: - If you want the time to be the same as the visibility time, select the **Same as display time** checkbox. - If you want to set a date range, pick the dates in the **Start** and **End** fields. 5. In the **Lasting** field, enter the time (in seconds) that a promotion remains redeemable after it is activated. `0` is interpreted as `infinity`. 6. Click **Apply**. ### Stores 1. In the **Stores** section, click **Define**. 2. From the **Select stores** drop-down list, select a catalog of stores. 3. Choose a set of stores: - If you want to apply the promotion to all stores in the catalog, select the **Entire catalog** radio button. - If you want to apply the promotion to particular stores from the catalog: 1. Click **Select stores**. 2. In the pop-up that opens, select the checkboxes of the stores where you want to apply the promotion. 3. Click **Apply**. The pop-up closes. 4. Click **Apply**. ### Add voucher codes --- Optionally, in the **Voucher pool** section, you can select a voucher pool to assign voucher codes to profiles. The voucher code will be available to get in the contents of the promotion object and the code can be used on the customer’s entire cart. Each time the promotion is activated, a new voucher code is assigned. How and when the voucher code appears or is used depends on the promotion setup and the platform (for example, a mobile app or a website). We strongly recommend monitoring your voucher pool levels as explained in [Monitor Voucher Pool Levels and Receive Alerts for Replenishment](/use-cases/voucherpools). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> To learn about code types, how to create a voucher pool, and how to add, assign, and distribute codes, see [Voucher pools](/docs/assets/code-pools). </div></div></div> 1. On the **Voucher pool** section, click **Define**. 2. From the **Voucher Pool** dropdown list, select a voucher pool from which the voucher codes will be retrieved. **Result**: You are shown a voucher pool summary - the number of voucher codes available for assignment (**Available vouchers**), the number of voucher codes in total in a voucher pool (**pool size**). 3. Use the **Enable voucher pool integration** toggle to enable or disable voucher assignment to a profile. By default, voucher assignment is enabled. When this option is disabled, you can still activate a promotion for a profile, but a voucher code won't be assigned (the code will not be returned). 4. To allow users other than the assigned end-user to redeem the voucher code, enable the **Allow voucher transfer** toggle. This option is supported **only** by the [`promotions/voucher/batch-redeem`](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchers) and [`promotions/voucher/batch-redeem-for-profile`](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchersForProfile) endpoints. - When this option is **disabled**, voucher codes are assigned to specific profiles and cannot be redeemed by other end-users. - When this option is **enabled**, and a voucher is redeemed, the following events are generated on the profile of the voucher code owner (the end-user to whom the voucher code was initially assigned): - [`client.removePoints`](/docs/assets/events/event-reference/loyalty#clientremovepoints) with the `beneficiaryClientUUid` parameter which contains the UUID of the end-user who redeemed the voucher, - [`voucherCode.redeemed`](/docs/assets/events/event-reference/loyalty#vouchercoderedeemed); 4. Confirm the settings by clicking **Apply**. ### Saving a draft or publishing - If you want to publish the promotion, click **Publish**. **Result:** If the schedule was set to "Immediately", the promotion becomes visible after you click **Publish**. If it was scheduled for a date, it becomes visible at that date. - If you want to save the promotion as a draft or return a published promotion to draft status, click **Finish later**. # Creating propensity predictions Propensity predictions let you evaluate how likely customers are to buy products with specific features, such as brand, category, color, and much more. You can create a propensity prediction from scratch or by using one of the predefined scenarios: - Find customers who will buy a specific item, brand, or category; - Find customers who will buy any item; - Find customers who will buy through a specific communication channel; - Find customers who will buy offline Predefined scenarios are configured using a user-friendly wizard that allows you to adjust scenario settings according to your preferences. This is done through a step-by-step configuration form, which provides hints on the interface to guide you. The option of creating a prediction based on a predefined scenario is available in the initial part of creating the prediction ([Select the model type](#select-the-model-type)). ## Prerequisites - [Configure AI Engine for Propensity and Best Fit](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity). It usually takes several hours to initialize the model and perform necessary calculations. - The attributes that you want to use for propensity predictions must be configured as [filterable attributes](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity#selecting-filters). ## Configure a prediction ### Select the model type 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Predictions) Models**. 2. Click **New prediction**. 1. On the pop-up select one of the following options: - **Use predefined prediction** - This option allows you to use the ready-made prediction scenarios and adjust its settings to your preferences in a user-friendly, step-by-step configuration form by following hints shown on the interface. If you select this option, you can skip reading the rest of the article. - **Create from scratch** - This option allows you to create your own configuration of a propensity prediction to achieve your custom business objective. If you use this option, select **Propensity**. ### Select customers to be analyzed Select the audience for whom you want to prepare a prediction. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/select-audience.png" alt="Selecting an audience to be analyzed" class="full"> <figcaption> Selecting a group of customers </figcaption> </figure> 1. In the **Audience** section, click **Define**. 2. Click **Choose segmentation** and perform one of the following actions: - From the list, select an existing segmentation. You can use the search field. - To define a new group segmentation, at the bottom of the dropdown list, click the **Create new** button. 1. In the **Segmentation name** field, enter the name of the group of customers and click **Next step**. 2. Build the segmentation. See [this article](/docs/analytics/segmentations/creating-segmentations) for instructions. 3. Click **Create segmentation**. 3. Confirm by clicking **Apply**. ### Select items <!-- TODO: add image --> 1. In the **Item feed** section, click **Define**. 2. Click **Choose item feed**. 3. From the list of available catalogs, select the item feed you want to analyze. This can be the same catalog as the one you use for recommendations. **Result**: The **Items filter** sub-section appears. 1. Click **Define item filter**. 2. Define the filters that describe the item or items that you want to calculate the prediction for. - The filters are created using the same [visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder) as recommendations filters, but some operators are not available for Predictions. - You can use [the `created` attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#the-created-attribute) which lets you filter the items based on the date of adding an item to the feed. - Only attributes [selected as filterable when configuring the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-propensity#selecting-filters) are available for use. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/propensity-item-select.png" class="large" alt="The Item selection view after configuring the filters"><figcaption>The Item selection view after configuring the filters</figcaption></figure> 3. Click **Apply**. ### Additional settings By default, the calculation is performed once and the results are presented on a 5-point scale. 1. If you want to leave the settings as default, the predictions is ready to calculate. Continue to [saving the prediction](#save-the-prediction). 2. If you want to change the settings, in the **Settings** section, click **Change**. 3. To schedule a recurring calculation: 1. Select the **Set up recurring prediction calculation** checkbox. 2. In the input field, enter the number of days between calculations. 4. To change the scale from 5-point to 2-point, select the **2-point scale** radio button. 5. Click **Apply**. ### Save the prediction To save the prediction: - as a draft, click **Save**. - and calculate, click **Save & Calculate**. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can check the logs of the activated prediction. [Learn more](/docs/ai-hub/predictions/predictions-functionalities#previewing-logs). </div></div></div> ## Results The maximum calculation time is 24 hours. ### Understanding propensity prediction results | Attribute name | Description | |-------------|-------------------------------------------------------------------------------------------------| | action | An event type for the prediction - `snr.propensity.score` | | added by | An entity that generated this event. In the case of prediction events, it is always Synerise. | | modelId | A unique identifier of the prediction | | modelName | The name of the prediction | | score_label | Prediction output: two- or five-point scale label. You can select the scale in the [settings of the prediction](#additional-settings). | | score | The result of the prediction | | percentile | [Prediction percentile](/glossary/#percentiles) | | clientId | Customer's identifier | | time | Time when a prediction was generated, as a Unix timestamp | | configurationVersion | Allows to verify whether two consecutive calculations ran with the settings (*only for debug*) | | modelVersion | Model version allows to verify whether two consecutive calculations ran on the same model parameters (*only for debug*) | # Creating attribute recommendations By means of the attribute recommendations you can display a frame with the personalized item attribute without showing the items in the recommendation frame. This way, you create unique and personalized sets that promote brands, categories, style, or any other features of the items. ## Distributing recommendations --- You can use the ID of the recommendation and [inject it with a snippet](/docs/assets/snippets) in other types of communication, such as: - [dynamic content](/docs/campaign/dynamiccontent) - this way you can show the recommendations on your website. - [email](/docs/campaign/e-mail) - this way you can send out recommended items through emails. - mobile application - you can use [documents](/docs/assets/documents) to build your own mobile app and show the recommended items. - [mobile push](/docs/campaign/Mobile) - you can send recommendations through notifications in your mobile application. - [web push](/docs/campaign/Webpush) - this way you can send notifications to your customers through a web browser. - [SMS](/docs/campaign/SMS) - this way you can reach your customers with recommendations on their mobile. ## Requirements --- - You must [configure the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations) for this recommendation type. - [Create an item catalog](/docs/ai-hub/recommendations-v2/item-feed-requirements) - Optionally, create a complementary [metadata catalog](/docs/ai-hub/item-feed/metadata-catalog) that includes additional information about items ## Select feed and recommendation type --- Select the feed from which items will be sourced to recommendations and the type of recommendations to be displayed. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Recommendations) Models > Add recommendation**. 2. Enter the name of the recommendation (it is only visible on the list of recommendations). 1. In the **Type & Items feed** section, click **Define**. 2. From the **Items feed** dropdown list, select an item feed. 3. Under **Recommendation type**, click **Select model**. 4. On the pop-up that opens, select the **Attribute** model. If the recommendation is disabled, it means the AI engine is not trained yet. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Learn more about: - [recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types) - [recommendation statuses](/docs/settings/configuration/ai-engine-configuration/model-status) </div></div></div> 5. Click **Apply**. 4. Optionally, from the **Metadata catalog** dropdown, select the catalog which includes additional information about items in your feed. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> More information about metadata catalogs is available [here](/docs/ai-hub/item-feed/metadata-catalog). </div></div></div> 4. Confirm the settings by clicking **Apply**. ## Configure item settings --- The next step is to define the items to be displayed in the recommendation frame. You can use slots to assign space in your recommendation frame to specific items. In the settings of a single slot, you can declare the number of items and the attribute based on which the items will be recommended. A recommendation must include at least one slot. ### Adding slots 1. In the **Items** section, click **Define**. 3. Click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/analytics/_gfx/plus-button.png" alt="Plus icon" class="icon"> button. 4. If you want to name the slot, hover over the **Unnamed slot** tab and double click it. 2. When adding multiple slots, you can define their order by dragging and dropping the tabs into the desired sequence. The slot represented by the leftmost tab is considered the first slot. For more slot order options, refer to the [Define slot and item ordering](#define-slot-order) section. 5. To proceed to the slot settings, click the tab with the slot. 6. In the **Number of items** subsection, enter the minimum and maximum number of items to include in the slot. 4. From the **Item attribute** dropdown, choose the feature of the item based on which the items will be selected to the section or sections in the slot. 6. To manage the variety of items in the sections, use **Static filters** and **Elastic filters**. <details class="accordion"><summary>Elastic filters explained</summary><div class="accordion-content"><p>Apart from selecting the items to be displayed in the recommendation frame, the elastic filter supplements the recommendation frame if it’s not entirely filled up with items. For example, if you select to display up to 10 items, and you have only 5 items that meet the conditions of elastic filter to be displayed in the recommendation frame, then the empty slots will be filled with items which do not match elastic filter (based on scoring of each model).</p></div></details> <details class="accordion"><summary>Static filters explained</summary><div class="accordion-content"><p> When you use a static filter, it shows the fixed number of items that match the conditions of the filter. If there are not enough items to fill in the recommendation frame (the number you entered in the step 2), the recommendation frame is not displayed at all. </p> <ul> <li>If you want to <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-recommendation-types-and-default-filters">apply the global item filter</a> defined for the recommendation model based on which you're creating the campaign, enable <strong>Apply Items Global Filters</strong>. Enabling this toggle applies the global item filters and they work in combination with other filters in the slot.</li> <li>If you want to apply custom static filters for the slot, click <strong>Define filter</strong>. Select one of the filter creators:<ul> <li><a href="/docs/ai-hub/recommendations-v2/recommendation-filters/#visual-builder">visual builder</a></li> <li><a href="/docs/ai-hub/recommendations-v2/recommendation-filters/#iql-query">IQL query wizard</a></li> </ul> </li> </ul></div></details> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> - You can read how to build conditions based on the `category` attribute [here](/docs/ai-hub/recommendations-v2/recommendation-filters#the-category-attribute). - You can learn more about [filters](/docs/ai-hub/recommendations-v2/recommendation-filters) in recommendations and see [examples of use](/docs/ai-hub/recommendations-v2/recommendation-filters-examples). </div></div></div> 7. Save the changes by clicking **Apply**. ### Define slot order --- In this section, you can define the order of slots. However, defining the order of items within the slots is impossible for this recommendation type. Instead, the items are automatically arranged based on the Personalized recommendation model. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/slot-ordering.png" alt="A form for configuring slot order" class="large"> <figcaption> A form for configuring slot order </figcaption> </figure> 1. In the **Slots and items ordering** section, click **Define**. 2. To define the order of slots and order of items within the slots, in the **Slots and items ordering** subsection, select one of the following options: - **Arrange items in slot order**: - the slots will be presented in the order defined in the **Items** section. - the order of items is arranged based on results from the Personalization model. - **Arrange items ignoring slots and its order**: the slots will be ignored and the order of items will be arranged according to results of from Personalized model. ### Define the boosting factors --- You can increase probability of appearing in the recommendation frame. You can boost the items in three ways (both can be used at the same time): - **Metric** boosting uses pre-defined item popularity metrics to influence item scoring. Metric boosting is available only for the Similar, Cart, Visual similarity recommendation types. - **Attribute** boosting influences item scoring depending on rules applied to the item's attributes. This is done by applying a filter to items and adjusting the score of those items that match the filter. For example, you can increase the scoring of a particular brand without excluding other brands entirely. - **Personalization** boosting uses the personalization model to influence the items' scoring according to the preferences of each customer - items that fit their preferences have a higher probability of appearing in the recommendation frame. You can manage the influence of personalization model on boosting by using the Impact scrollbar. Personalization boosting is available for all recommendation types, except for Personalized, Section, and Attribute. This element has a significant impact on the model's outcome. For instance, if we set the personalization impact to 80% in the recommendation model based on **Top items**, the suggested items will be influenced mostly by the personalization model (making up 80% of the impact). Meanwhile, the **Top items** model will only contribute 20% to the recommendations (along with other factors like boosting attributes). <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recov2-boosting.png" class="large" alt="An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting"><figcaption>An example of a Boosting section with metric boosting used to promote items, attribute boosting used to demote items and personalization boosting</figcaption></figure> 1. In the **Boosting** section, click **Define**. 2. **Metric boosting**: 1. Click **Select** and select a metric to use for adjusting the score. 2. Choose the **Promote** (default) or **Demote** option. 3. Use the slider to determine how much you want the metric to influence the score of the items. 3. **Attribute boosting**: 1. Click **Add rule**. 2. Click the created rule to open its settings. 3. In the **Items scope** section, click **Define filter**. Items that meet the filter will have their scores adjusted. To learn how to build filters, see [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters). 4. Choose the **Promote** (default) or **Demote** option. 5. Use the slider to determine how much you want the metric to influence the score of the items. 4. **Personalization**: 1. Enable the **Personalization** toggle. 2. From the Impact scrollbar, select how much you want the personalization model to influence the arrangement of items in the recommendation. 4. Confirm the settings by clicking **Apply**. ### Additional settings --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-additional-settings.png" class="full" alt="The Additional settings section in the configuration form"><figcaption>The Additional settings section in the configuration form</figcaption></figure> 1. In the **Additional settings** section, click **Define**. 2. If you want to exclude items that the customer already purchased, enable the **Exclude already bought products** option. This option will exclude up to 100 items that were purchased within a specific number of days, as defined in the **Since** field, which appears after enabling the option. Optionally, you can also set this option as elastic, which will work as an [elastic filter](/docs/ai-hub/recommendations-v2/recommendation-filters#elastic-filter). 5. If you want to source the item context from an aggregate or expression results instead of the website, enable the **Item context from analytics** toggle. Then from the dropdown list, select the analysis whose result will be treated as the item context. On the basis of the item context, the engine selects the items to display in the recommendation. By default, the recommendation sources the item context from the product page where it is implemented. This option lets you override this setting, so the item context will be taken from the result of the aggregate or expression that returns for example, a recently viewed item, favorite items, recently purchased items or items purchased the most frequently. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is available for all recommendation types except for Recent interactions and Last seen. </div></div></div> 6. Optionally, you can assign a slug to the recommendation. In such a case, enable the **Recommendation slug** toggle. This option lets you assign a user-friendly, unique identifier of the recommendation which you can use to fetch recommendation campaign instead of its ID. The slug can be edited at any time. In the **Enter unique slug name** field, enter the name containing 3 to 25 characters. You can only use: - lowercase Latin alphabet letters (a-z) - digits (0-9) - `-` but it can't be the first and/or last character 7. If you want to use [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) to recommend items from across all your grouped workspaces, enable the toggle in the **Co-Brand Personalization** section. This toggle is available if your workspace uses [co-brand decisioning layer feature](/docs/settings/workspace/multibrand-workspaces). To enable it, contact the Synerise support. The badge next to the option name indicates the mode configured for your workspace group by the Synerise support team. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/co-brand-personalization.png" class="medium" alt="The Co-Brand Personalization section in the configuration of the AI Recommendation campaign"><figcaption>The Co-Brand Personalization section in the configuration of the AI Recommendation campaign</figcaption></figure> 8. To confirm the settings in the **Additional settings** section, click **Apply**. ### Saving the recommendation --- To save the recommendation: - as a draft, click **Finish later**. - and activate the recommendation, click **Save**. Once you activate the recommendation, you can use it as described in the [Distributing recommendations](#distributing-recommendations) section. # Edit search method, searchable attributes, and define search relevance In this article, you can find instructions on how to change the search method and searchable attributes in existing index. If you haven't created any yet, refer to the ["Create an index"](/docs/ai-hub/ai-search/create-index) article. Apart from editing the search method and defining searchable attributes, you can define search relevance settings such as: - Matching words to control how items will be matched with the query phrase - Ranking function to select query scoring method - Tie breaker to resolve a situation where two or more items have the same score or ranking in a given context. ## Configuration --- To edit the search method and ranking settings: 1. Go to **AI Hub > Indexes**. 2. [Create](/docs/ai-hub/ai-search/create-index) or select the index on the list. 3. Go to the **Settings** tab. 4. On the **Search method** section, click **Define**. 5. Optionally, you can change the search method. 6. By clicking **Select attributes**, you can add or remove searchable attributes. 5. To define search relevance settings, click **Advanced options**: - [Matching words](#matching-words) - [Ranking function](#ranking-function) - [Tie breaker](#tie-breaker) ### Matching words In the **Matching words** section, you can specify how multiple-word queries are processed. When a user enters a search query, the system compares the words in the query with the searchable attributes (selected while [creating an index](/docs/ai-hub/ai-search/create-index)) of items in the index. By default, the **At least one word must match** option is enabled. For example, when a customer searches for `white shoes`, the search returns white shoes, but also other white items and shoes that are not white. To narrow down the results to `white shoes` only, you can use the **All words must match** option. The table below explains the different matching options. Note that the Matching Words section is available only for Keywords and Hybrid search methods. | Option name | Description | |---------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Adaptive | This method automatically adjusts the matching behavior based on the length of the query. <br> - **For short queries (up to 2 words)**, an item is considered a match when every word from the query phrase is present in the item's searchable attributes. <br> - **For longer queries (more than 2 words)**, an item is considered a match when all except one word from the query are present in the item's searchable attributes. <br> Use this option when you want a balanced search — tight for short queries and more flexible for longer ones, ensuring relevant results. | | At least one word must match | An item is considered a match for the query when at least one query word matches the searchable attributes. Use this option when you want to relax the search criteria and accept less relevant results. | | All words must match | An item is considered a match when every word from the query phrase is present in the item's searchable attributes. Use this option when you want to tighten the search criteria at the cost of retrieving fewer results. | | Minimum number of words that must match | Define the minimum number of words from the search query that the item's searchable attributes must contain. | | Maximum number of words that can be omitted | Define the maximum number of words from the query phrase that an item doesn't need to contain in its searchable attributes. | | Low match enhancement | When this option is enabled and the number of items returned in search results is lower than 5, you can complement search results with other items. You can select one of the following methods for selecting additional items: <br> - **Adaptive** - This option works as described in this table. <br> - **Any words** - If any word from the query matches the item's searchable attributes, the item is selected to be included in the results. <br> - **Minimum match** - A configurable number of words from the query must match the item's searchable attributes so it can be included in the results. | ### Ranking function In this section, you can choose between two methods of scoring items. The ranking function is used by the search engine to calculate the item's relevance to a customer's query. The relevance is one of the factors taken into account while scoring items. The items are returned in order according to their score. You can select one of two options: - **The basic function** - This option is not configurable. - **The adjustable function** - This option contains two configurable parameters described in the table below: | Option name | Description | |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Length of attributes | Adjust how the length of the searchable attribute values affects the distribution of score for an item when a word from the query matches the searchable attributes. An item gets a higher score when a word from the query matches attributes with fewer values (words) in contrast with the same word that matches longer attributes. The difference between the scores is controlled with this parameter; the higher the parameter, the bigger the difference will be. | | Word frequency | Each occurrence of a word in the query phrase that matches the searchable attributes will add an amount to the item score. The higher the value of the word frequency parameter, the less is added to the overall score after every occurrence of the same word in the searchable attribute importance group. | <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You may want to perform A/B tests when you use this function to asses the results for particular values for the parameters. </div></div></div> #### Example - A brand name is included in the `name`, `brand`, and `title` parameters of an item. - All the above attributes are searchable. - The **Word frequency** parameter is set to a high value. - A customer enters the brand name as the query. **Result**: This item **is not** scored higher than items that include the brand only in the `brand` parameter. ### Tie breaker If a word from the query matches two or more searchable attributes and each of these attributes has a different importance level assigned, they contribute to the score of the item. The tie breaker parameter defines a weight by which the second (and subsequent) matched attribute is multiplied while adding to the score. One way to use this mechanism is to assign two importance levels to an attribute while setting up searchable attributes. If a word from the query matches an attribute with two importance levels, that word adds more to the final score than a word that matches an attribute with one importance level. # Define typos and missing words management <!-- <details class="accordion"><summary>Click for video tutorial</summary><div class="accordion-content"><div class="youtube-embed youtube-facade not-prose" data-youtube-id="t8-Wah09U2Q" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to use Search Settings?"><img src="https://img.youtube.com/vi/t8-Wah09U2Q/hq720.jpg" alt="Synerise Academy - AI Search - How to use Search Settings?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> <details class="accordion"><summary>Click for video tutorial</summary><div class="accordion-content"><div class="youtube-embed youtube-facade not-prose" data-youtube-id="cBekmZWkcPo" role="button" tabindex="0" aria-label="Play What is ranking? | AI Search Engine | Synerise AI Growth Ecosystem"><img src="https://img.youtube.com/vi/cBekmZWkcPo/hq720.jpg" alt="What is ranking? | AI Search Engine | Synerise AI Growth Ecosystem" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> --> You can define the search engine behavior in situations when a customer enters a query which contains a typo or if their query is missing some words. This way, you can provide relevant results regardless of any errors or missing words in the query. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-search-handling-typos.png" class="full" alt="Configuration of handling typos and missing words"><figcaption>Configuration of handling typos and missing words</figcaption></figure> ## Configuration --- 1. Go to **AI Hub > Indexes**. 2. [Create](/docs/ai-hub/ai-search/create-index) or select the index on the list. 3. Go to the **Settings** tab. 4. In the **Handling typos and missing words** section, click **Define**. 5. From the **Replace words** dropdown list, select one of the following options: - **Popularity** - The search engine compares words from the searchable attributes and suggests replacements based on word similarity but also takes the popularity of the suggested words into account. - **Accuracy** - In this option, the similarity of the compared words is the key factor. The number of different letters between two words is evaluated and suggested phrases are provided. 6. To define advanced settings such as the number of words that can be replaced by the engine or disabling typo tolerance for searchable attributes, and so on, click **Advanced options**. ### Advanced options explained | Option name | Explanation | |-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Maximum number of misspelled words | You can define how many letter differences there can be between the missing word and words suggested by the search engine as replacements. | | Maximum length of the compared part of the word | While comparing the missing words from the query with the potential replacements, they are divided into smaller parts. These parts are compared with the same parts lengthwise in the indexed searchable attributes. With this parameter, you can specify how big these parts are. | | Use always | By default, the search engine will not use the suggested replacement for missing words if there are items that can be returned for the whole phrase. If the searched phrase contains more than one word, and one of them has a typo, the search engine will still be able to return items based on the correct words in the phrase. In this case the suggested word is not used. By enabling this option, the suggested word will always be used when searching for items. | | Disable typo tolerance for searchable attributes | By default, the search engine returns results even when a user makes a mistake while typing the search query. You can disable this behavior for situations when a user types a search query that is an item attribute (for example, a brand, item name, SKU, and so on). | | Disable typo tolerance for words | By default, the search engine returns results even when a user makes a mistake while typing the search query. You can disable this behavior for situations when a user a specific word. | | Enable typo tolerance for numeric values | By default, the search engine returns results if a search query is a numeric attribute and it is not an exact match. Disabling typo tolerance for numeric values lets you produce a search result only when values such as postal codes or SKUs are exact matches | # A/B/X testing A/B/X testing is a way to try out different recommendation setups in Synerise to see which one works best. You can test different recommendations within one test for a section of a page or even the whole page without needing any extra tools or complicated calculations. You don't have to make any changes to recommendation setup to use this feature. While creating the test, you will choose a base variant, which is a recommendation (either existing or newly created) that you will request by its ID. Each test variant is a distinct recommendation. Synerise will randomly assign a customer to one of the variants. When the test is done, you can switch to the best setup without needing any coding. The winning setup is marked in the statistics of the test based on specific metrics. ### Key features --- - Launch tests without any changes to your existing setup. - Compare up to 5 variants, including your base campaign. - Precisely control user exposure to each variant. - Access pre-built dashboards showcasing critical metrics (such as conversion rate, click through rate, average revenue, and more) - Automatically declare winners based on statistical significance. - Implement winning variants without developer intervention. - Convenient outcome preview - you can preview and compare recommendation results directly within the platform. ### Feature overview --- 1. **A/B/X Test Setup** - You can create up to 5 variants (including base variant) in a single test. - Each variant requires selecting one recommendation (draft or active status). - Variants can be distributed equally or manually with allocation between 1% and 99%. 2. **Variant Assignment** - When a request for the base variant for a customer is made, the customer is randomly assigned to one of the test variants. - UUID is the profile identifier used to assign customers to groups. If a customer logs in on multiple devices or browsers, this customer can be assigned to more than one variant. - Profiles are assigned to a variant for approximately 180 days. - A [`variant.assign`](/docs/assets/events/event-reference/recommendations#variantassign) event is generated on the profile card. 3. **Usage Restrictions** - Each recommendation can only be used in one A/B/X test at a time. - There are no limits on the number of active A/B/X tests. - This feature ignores the [global control group](/docs/settings/configuration/global-control-group) - customers who belong to the global control group can be shown recommendations regardless. 4. **Combination Restrictions** - The base recommendation type determines the allowed recommendation types in A/B/X testing: - If [Section page recommendation](/docs/ai-hub/recommendations-v2/recommendation-types#section-page) is the base, all variants must be of the **Section page** type. - If [Attributes recommendation](/docs/ai-hub/recommendations-v2/recommendation-types#attribute) is the base, all variants must be of the **Attributes** type. - No restrictions apply if any other type is the base variant. 5. **Displaying Recommendations** - Refer to guidelines in the ["Embedding a recommendation in templates"](/docs/ai-hub/recommendations-v2/distributing-recommendations#embedding-a-recommendation-in-templates) section. - Recommendations are presented to the defined audience based on recommendation settings. 6. **Performance Evaluation** - A/B/X tests run indefinitely by default. Performance metrics such as clicks, CTR, and revenue are continuously calculated. You can stop the A/B/X test manually. - Once the test is complete, you can select the best-performing variant. Regardless of the selected variant, the ID of the recommendation will remain the same and no further actions are required. 7. **Custom Analysis** - You can perform analyses using [recommendation events](/docs/assets/events/event-reference/recommendations) and the following event parameters: - `variantId`: Unique identifier of the variant. - `variantName`: The name of the variant. - `experimentId`: Unique identifier of the test. 8. **Testing external models** - If you want to include recommendations from an external model in the test, you can use the **External** recommendation campaign type to pass external results and add them to the test. For details, see [A/B/X testing with external models](/docs/ai-hub/recommendations-v2/abx-test-with-external-model). ## Requirements --- - You must [create at least two recommendations](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign). - The recommendations you select for A/B/X testing must have the same preview attributes. In the ["Selecting attributes for preview"](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-attributes-for-preview) section you can learn to configure preview attributes. ## Configuration --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > (AI Recommendations) A/B/X Tests > New A/B/X test**. 2. On the top of the screen, you can change the name of the A/B/X test. 3. In the **Variants and profile allocation** section, click **Define**. **Result**: A configuration form for variants is displayed. Two variants are automatically created: **Base variant** and **Variant**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/ab-reco-test-config-form.png" class="full" alt="A blank configuration form for A/B/X recommendation test variants"><figcaption>A blank configuration form for A/B/X recommendation test variants</figcaption></figure> 4. In the **Base variant** tab, from the **Select recommendation campaign** dropdown list, select a recommendation that will be used as the base variant. 5. Go to the **"B" Variant** tab. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/b-variant-ab-reco-test.png" class="medium" alt="B Variant tab"><figcaption>B Variant tab</figcaption></figure> 6. From the **Select recommendation campaign** dropdown list, select a recommendation for this variant. 5. To add more variants, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/add-variant-icon.png" alt="Plus icon" class="icon"> and select recommendations for them. 8. To customize variant allocation, in the **Profile allocation** section, use the slider and set preferred variant allocation. 9. Confirm the settings by clicking **Apply**. 10. To: - save the test as a draft, click **Save**. - save and activate the test, click **Save & Run**. ## Stopping the test --- The test will be running until you stop it. Before stopping the test, you can consult the results each variant has achieved in the [Statistics tab](#statistics). We recommend running the test for at least several days. 1. To stop the test, go to the details of the test by clicking its name on the list. 2. In the upper-right corner, click **Stop test**. **Result**: A pop-up appears. 3. On the pop-up, select one of the following options: - **Stop test and keep current variant configuration** - The A/B/X test will be stopped and the configuration of the recommendation which was selected as the base variant remains the same. If the base recommendation is used in active campaigns, nothing will change. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This action is irreversible. </div></div></div> - **Use configuration from another variant** - The A/B/X test will be stopped, and the configuration of the recommendation which was declared as the base variant can be replaced with the configuration of one of the tested variants. In further steps, you can select which variant will overwrite the current base configuration. If the base recommendation is used in active campaigns, its configuration will be automatically replaced. The old base configuration can't be restored. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/stop-abx-reco-test.png" class="large" alt="A pop-up with options concluding A/B/X test"><figcaption>A pop-up with options concluding A/B/X test</figcaption></figure> 4. Click **Next**. 4. If you selected the **Use configuration from another variant**, select the recommendation variant with which you will overwrite the configuration under the base variant by clicking **Choose**. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The next action is irreversible. </div></div></div> 5. Confirm the action by clicking **Confirm**. ## Statistics --- Statistics are based on the [recommendation events](/docs/assets/events/event-reference/recommendations), [`product.buy`](/docs/assets/events/event-reference/items#productbuy) and [`transaction.charge`](/docs/assets/events/event-reference/items#transactioncharge) events. The following metrics are calculated: - **Clicks** - The number of unique clicks on a recommendation frame. - **Unique users** - The number of customers for whom a recommendation was generated. - **CTR** - Click-through rate: the number of clicks on a recommendation frame divided by the number of generated recommendations. - **Conversion rate** - The number of unique purchased items divided by the number of all clicks on an item within a recommendation frame. - **Average revenue** - The average revenue (per customer) the recommendation generated during the test. It is calculated by dividing the total revenue by the number of unique customers who made a purchase. ### How to interpret winners? The winner status is declared exclusively for individual metrics and not for the entire variant. The following metrics can be declared as winners: **CTR**, **conversion rate**, and **average revenue**. - For CTR and CR, we use one-tailed 2-proportion Z-test with 95% confidence level, so if the variant metric is labeled "WINNER", it means that there is a 95% probability that the observed metrics difference is not due to random chance. - For Average Revenue, we use one-tailed 2-sample T-test, with n-2 degrees of freedom, so if the variant metric is labeled "WINNER", it means that there is a statistically significant difference in Average Revenue between the groups. ### Where to find statistics? To view the A/B/X test statistics: 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > (AI Recommendations) A/B/X Tests**. 2. On a running or finished test, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three dot icon" class="icon" > 3. From the dropdown list, click **Show statistics**. **Result**: The preview of A/B/X test statistics is displayed. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/abx-test-reco-stats.png" class="full" alt="Statistics of A/B/X recommendation test"><figcaption>A/B/X recommendation test</figcaption></figure> ### Statistics overview | Metric name | Description | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Clicks | It is the number of unique clicks on a recommendation frame of a given variant. | | Unique users | It is the number of unique profiles for whom recommendation was generated. | | CTR | (Click Through Rate) It is the number of clicks on a recommendation frame of a given variant divided by the number of recommendation generations from a given variant. | | Conversion rate | It is the number of unique products bought divided by the number of all clicks on a recommendation from a given variant. Clicks are tied to the `transaction.charge` event. Clicks made within 24 hours of a transaction count towards the conversion rate of the day when the transaction was made. | |Avg. revenue| (Average revenue) It is calculated by dividing revenue* by the number of unique customers (those for whom recommendation was generated). | `*`Revenue - Revenue generated by the recommendations. It is counted when a customer buys an item within 24 hours after clicking the item in the recommendation frame. # Recommendation filters Filters can apply additional logic on top of recommendation results served by the AI engine. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> When [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) is enabled, items from grouped workspaces are included in the filter results. </div></div></div> They are used in two situations: - For filtering, to exclude or include items from a recommendation. - For score boosting, to promote or demote matching items. Filters can only use item attributes that you set as filterable while [configuring AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations). You can use static customer attributes, such as `city`, `name`, `birthdate`, segmentations, and tags. The allowed formats of the attributes are: string, integer, float, boolean, objects, and arrays. The attribute names are case sensitive, however the filter values are not. So, the filter `brand == "ABC"` is equivalent to `brand == "abc"`, but different than `Brand == "ABC"`. ## Filter types --- Before you create the filter rules, you must decide which filter type you will use: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-types.png" alt="Filter types" class="large"> <figcaption> Filter types </figcaption> </figure> ### Elastic filter This type of filter allows you to select the items to be included in the slot and supplement the slot if it’s not entirely filled up with the items. For example, if you select to display up to 10 items, and you have only 5 items that meet the conditions of elastic filter to be included in the slot, then the slot will be filled with additional items which do not match the elastic filter (based on scoring). ### Static filter This type of filter allows you to show a fixed number of items that match the conditions of the filter. - If the applied filter conditions (that don't include any customer context) are too strict and there are not enough items to fill in the recommendation slot, the slot is not generated at all. - If the filter conditions include customer context from one of the following sources: [aggregate](/docs/ai-hub/recommendations-v2/recommendation-filters#aggregate), [expression](/docs/ai-hub/recommendations-v2/recommendation-filters#expression), or a [profile attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#customer-context-value), and the context cannot be retrieved for any reason: - By default, the filter is ignored and the slot will be generated without applying the filters. - If **Fail slot when the context is missing** is selected from the **Ignore filter** dropdown list, the slot is not generated at all. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/static-filters-ignore-limits.png" class="full" alt="The Ignore filter option in static filters in AI Recommendations"><figcaption>The Ignore filter option in static filters in AI Recommendations</figcaption></figure> There are two types of static filters: - If you want to [apply global item filter](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-recommendation-types-and-default-filters) defined for the recommendation model based on which you're creating the campaign, enable **Apply Items Global Filters**. Enabling this toggle applies the global item filters and they work in combination with other filters in the slot. - If you want to apply custom static filters for the slot, click **Define filter**. Select one of the filter creators: - [visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder) - [IQL query wizard](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query) ### Distinct filter This type of filter allows you to increase the variety of items included in the slot. You can define the allowed number of items that share the same attribute value to be shown, for example, a number of items that have the same brand, color, shape, category, and so on. - For all recommendation types except for **Last seen**, the engine considers up to 1000 items with the highest score that match the recommendation type. For example, if you selected the **Cross-sell** type, the engine analyzes up to 1000 items that match the cross-sell recommendation type, and then selects the number of items you chose to include in the slot. - For the **Last seen** recommendation type, the engine considers the last 100 page visit events. Based on the data from these events, the engine selects the number of items you chose to include in the slot. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This filter can only use attributes defined when [configuring the recommendation engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-attributes-to-increase-item-variety). </div></div></div> There are two types of distinct filters: - If you want to [apply global distinct filter](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-recommendation-types-and-default-filters) defined for the recommendation model based on which you're creating the campaign, enable **Apply Global Distinct Filters**. Enabling this toggle applies these global distinct filters automatically to all slots in a recommendation, streamlining recommendation consistency and quality. - If you want to apply custom distinct filters for the slot, click **Define filter**. 1. In the **Show only** field, enter the number of items whose attribute values can be the same. 2. From the **Choose attribute** dropdown list, select the attribute. You can use each attribute only once. This means that if you add multiple filters, any attribute that has already been used will no longer be available for selection. 3. To add more conditions, click **Add another** and repeat the steps. 4. If you want the distinct filter to supplement the slot with non-matching items in case not enough matching items are found, enable the **Mark filter as elastic** option. 5. Confirm by clicking **Apply**. ## Filter building methods --- You can create filter rules by using two filter wizards: - **Visual Builder** - You can construct the filter conditions similarly to creating a [segmentation](/docs/analytics/segmentations/creating-segmentations) in the **Decision Hub**. The list below presents the features available in the wizard: - Creating separate filters and then defining conditional dependencies between them - A separate option for matching/not matching filter conditions - A separate option for defining formula of conditions - Advanced elements, such as functions, require using the IQL query editor. You can open the editor from the query builder. - The range of options available to build filter conditions and the form of building the conditions may restrict the scope of business applications - **IQL query** - Advanced may construct a formula of the filter, which is similar to [creating expressions](/docs/crm/expressions/creating-expressions). The list below presents the capabilities of the wizard: - Possibility to create filter conditions for advanced business applications - Building one formula involves all conditions and dependencies between them - Additional elements that visual builder lacks: functions, segmentations, tags, take all, and take none options ### Filter limits --- While building the filter conditions, remember about the [limits](/docs/ai-hub/recommendations-v2/introduction-to-recommendation-campaigns#limits). ## Visual builder --- In the visual builder, you need to define the filters by: - selecting one or more attributes - describing the condition for the attribute using operators and their values - defining the dependency between the filters by preparing a formula <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> See [the article](/docs/ai-hub/recommendations-v2/recommendation-filters-examples) with examples of filters in the visual builder. </div></div></div> ### Selecting attributes --- You can select the following attribute types: - **Attributes** - The list of item attributes sourced from the main item feed. The list contains a [predefined **created** attribute](#the-created-attribute). - **Supplemental attributes** - The list of item attributes sourced from [supplemental catalogs](/docs/ai-hub/item-feed/supplemental-catalog) connected to the main item feed. - **Item metrics** - By using predefined metrics as filter conditions in the recommendation settings, you can showcase popular items from your store. You can find these metrics in the **Item metrics** tab. When you select a metric as an attribute, you can use numerical values and operators associated with numbers. You can use these metrics: | Metric name | Explanation | |--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Page visit count in the last 7 days | This metric counts the number of visits on a product page in the last 7 days. You can use the results of the metric in the recommendation filters, for example, to show items which were visited more than X times in the last 7 days. | | Page visit count in the last 30 days | This metric counts the number of visits on a product page in the last 30 days. You can use the results of the metric in the recommendation filters, for example, to show items which were visited more than X times in the last 30 days. | | Sold items count in the last 7 days | This metric counts the number of items which were sold in the last 7 days. You can use the results of the metric to exclude items which weren't purchased in the last 7 days. | | Sold items value in the last 30 days | This metric calculates the total value of items sold within the past 30 days, including tax. The results of this metric can be used to showcase items that have generated revenue above specific threshold in the last 30 days. | | Sold items count from the same weekday last week | This metric counts the number of items which were sold on the same day of the week last week, for example, assuming that today is Thursday, the metric counts the number of items sold on last Thursday. You can use the results of the metrics to exclude items which weren't purchased at all on last Thursday. | | Sold items count in the last 30 days | This metric counts the number of items which were sold in the last 30 days. The results of this metric can be used to exclude items which weren't purchased in the last 30 days. | | Sold items count yesterday | This metric counts the number of items which were sold the day before. The results of this metric can be used to showcase items whose purchase count exceeds a specific threshold. | | <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filters-visual-builder-attribute.png" alt="Selection of an attribute" class="large"> <figcaption> Selection of an attribute in the visual builder </figcaption> </figure> 1. An item feed is already chosen and filterable attributes have been defined. 2. From the dropdown list, select an attribute of an item (in this example, `brand` is the selected attribute). **Result**: The **Operator** button appears. #### The `category` attribute --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/category-level-range.png" alt="Defining category in filters" class="large"> <figcaption> Defining category in the visual builder </figcaption> </figure> The `category` attribute allows for additional settings. Its structure represents the hierarchy of categories that the item belongs to (read more [here](/docs/ai-hub/item-feed/item-feed-in-catalog#category-attribute)). It allows you to define what part of the category should be taken into account by the filter. For a given category value, you can define the part using the level range. You can choose from the following options: - **Whole category** - As a result, all levels of the category are taken into account by the filter. - **Take first subcategories** - In the **How many levels?** field, enter a number to define how many subcategories from the left will be included. For example, if the category is "X > Y > Z", and you type `1`, then the resulting category value is `"X"` - **Cut last subcategories** - In the **How many levels?** field, enter a number to define how many subcategories from the right will be dropped. For example, if the category is "X > Y > Z", and you type `1`, then the resulting category value is `"X > Y"` #### The `created` attribute The `created` attribute lets you filter items on the basis of date of adding the item to the feed (time in this attribute is specified down to the second). This is a date-type attribute which lets you boost recently added items. You can choose from the following operators: - **Later than or at** - This includes items added to the feed on or after the specified date. - **Later than** - This includes items added to the feed after the specified date. - **Earlier than or at** - This includes items added to the feed before or on the specified date. - **Earlier than** - This includes items added to the feed before the specified date. - **At** - This includes items added to the feed exactly on the specified date. You can choose from the following values: - **Date** - You can pick an exact date and time from the calendar as the required value of the `created` attribute. - **Relative date** - You can define the number of minutes, hours, days, months or years before or after the current date and time. - **Context** - The value of the attribute is taken from the context item's entry in the item feed. This option is available only in the recommendation filters. ### Describing conditions by operators --- The next step is defining the conditions concerning the selected attribute by using operators. The list of operators contains: - **Is defined** - If the selected attribute has any other value than `null`. For example, if a filter is set to "`brand` is defined", the result contains only those items which have a specified brand (in the item feed). - **Equal** - If the selected attribute has an exact value. For example, if a filter is set to "`brand` equals `acme`", then the result contains items of Acme brand. - **Does not equal** - It excludes a particular value of an attribute. For example, if a filter is set to "`brand` does not equal `acme`", then the result contains all items except for the items of Acme brand. - **In** - It checks whether the attribute is present in a selected array(s). For example, if a filter is set to "`attribute.color` in `red, blue` /array/", then the result contains all items that are in the red and blue color. - **Not In** - It checks whether the attribute is not present in a selected array(s). For example, if a filter is set to "`attribute.color` in `red, blue` /array/", then the result will not contain items in red and blue color. - **Less than** - For example, if a filter is set to "`price.value` less than `50`", then the result contains items that are cheaper than 50 dollars (or other currency you use). - **Less than or equals** - For example, if a filter is set to "`attribute.size` less than or equals `43`", then the result contains items of size 43 or less. - **More than** - For example, if a filter is set to "`attribute.quantity` more than `10`", then the result contains those items whose quantity in your stock is greater than 10. - **More than or equals** - For example, if a filter is set to "`discountAmount` more than or equals `20`", then the result contains items which are discounted by $20 or more. ### Defining the values of operators --- The examples presented in the [Describing conditions by operators section](/docs/ai-hub/recommendations-v2/recommendation-filters#describing-conditions-by-operators) already contain the value of the operator. The list of values is as follows: #### Value from the list <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-select-value.png" alt="Value from the list" class="medium"> Out of the list of attributes sourced from the feed, you select one, like in the example: "`brand` equals `acme`" #### Context value <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-context.png" alt="Context value" class="medium"> The filters of any recommendation type can use the attributes of the item that the customer is currently browsing. For example, you can create a filter that shows items with the same category as the viewed item: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/context-value-filter-example.png" alt="Example of a context value operator" class="large"> <figcaption> In this example, the result contains the items that have the same category as the item the customer is currently browsing. </figcaption> </figure> #### Customer context value <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-profile-attribute.png" alt="Profile attribute" class="medium"> It allows you to use the customer attribute as the value of the item attribute. For example, you can filter displayed items by size, using the size value stored in an attribute of a customer who displays the recommendation. #### Array <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-array.png" alt="Array" class="medium"> This value type is only available for the **In** operator. It lets you include items whose attribute matches a value from an array. You can use it with attributes whose values are strings, numbers, and arrays. If you compare an array to an array, at least one value between them must be the same. To define an array: 1. Click **0 items**. **Result**: A pop-up appears. 2. In the text box, you can paste the array from a notepad, enter values manually or you can select values from the dropdown list. 3. Confirm your choice by clicking **Add**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/adding-array-values.png" class="large" alt="Adding values to an array"><figcaption>Adding values to an array</figcaption></figure> 4. Save the array by clicking **Apply**. **Result**: The output of the filter conditions in Figure 5 will include items whose color attribute contains at least one of the colors defined in an array. #### Aggregate <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-aggregate.png" alt="Aggregate" class="medium"> Allows you to select an aggregate as a value of the attribute from the item catalog. - The **aggregate result must match the item attribute** type defined in the feed. For example, if the attribute of an item is a number (price), you must select an aggregate that produces a number as the result. - You can use **two various aggregates** or **expressions**, or **one expression** and **one aggregate**. This **limit** applies per **one recommendation campaign** for filtering and boosting options. Multiple occurrences of the same aggregate count as one towards the limit. - If the condition contains an aggregate whose result is **null**, this condition is **skipped**. If it's the only condition, the result is that no filter is applied (all items match). - Using `null` as a **condition** in an aggregate is **impossible**. Using a `null` value as a string is not supported. #### Expression <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-expression.png" alt="Expression" class="medium"> Allows you to select an expression as a value of the attribute from the item catalog. - The **expression result must match the item attribute** type defined in the feed. For example, if the expression of an item is a text string (favorite color of the customer), you must select the expression that produces a result which is a text string as well. - You can use **two various expressions** or **aggregates**, or **one expression** and **one aggregate**. This **limit** applies to **one recommendation campaign** for filtering and boosting options. Multiple occurrences the same expression count as one towards the limit. - If the condition contains an expression whose **result** is **null**, this condition is **skipped**, unless it's the only condition. - Using `null` as a **condition** in an expression is **impossible**. Using a `null` value as a string is not supported. #### Formula <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-formula.png" alt="Formula" class="medium"> You can create it through the [IQL Query builder](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query). It allows you to define the advanced conditions, which can be done with the available operators and its value types. For example, if you want to display in the recommendation frame items which are discounted more than the currently viewed item. <details class="accordion"><summary>Click here to see the tutorial for the Formula example</summary><div class="accordion-content"><div class="vimeo-embed vimeo-facade not-prose" data-vimeo-id="498296155" role="button" tabindex="0" aria-label="Play Recommendation filters: Display items with a greater discount than the currently viewed item"><img src="https://i.vimeocdn.com/video/1356789480-cef13527ab9f86f2d25d85c9fb28f47002113d03d4e7024541e705952649225b-d_1280?region=us" alt="Recommendation filters: Display items with a greater discount than the currently viewed item" class="vimeo-facade-thumb" loading="lazy" /><span class="vimeo-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="#00adef"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> ### Defining filter conditions --- You can define how filters coexist by defining the dependency between them by using logical operators. Below you can find exemplary configuration of filters. <details class="accordion"><summary>Click to see the video</summary><div class="accordion-content"><div class="vimeo-embed vimeo-facade not-prose" data-vimeo-id="498375277" role="button" tabindex="0" aria-label="Play Vimeo video"><span class="vimeo-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="#00adef"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> ## IQL Query --- The IQL Query wizard allows for a greater flexibility of creating the formula of the filter due to the wide range of elements and the possibility combine them using mathematical operators. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> See [the article](/docs/ai-hub/recommendations-v2/recommendation-filters-examples#iql-query) with examples of filters in the visual builder. </div></div></div> ### Elements of the formula --- The filter formula can be built of the following elements: - String (a sequence of characters) - Number - Boolean - Array (a group of elements) - Take All (include all items) - Take None (include no items) - Attributes: - **Attribute** - any attribute from the item feed - **Segmentation** - **Boolean** - **Metric** - **Supplemental attribute** - item attributes sourced from [supplemental catalogs](/docs/ai-hub/item-feed/supplemental-catalog) connected to the main item feed. - Segmentations - Profile Tags - Functions For the list of functions, see ["IQL query functions"](#iql-query-functions) - Context - **Item Context** - to access attribute of an item a profile is currently viewing. - **Profile Context** - to access an attribute of a profile. - **Aggregate context** - to access the result of an aggregate calculated for the context profile. - **Expression context** - to access the result of an expression calculated for the context profile. The elements of the filter formula can be combined with the following mathematical operators: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-mathematical-operators.png" alt="Mathematical and logical operators in IQL Query wizard" class="full"> <figcaption> Mathematical and logical operators in IQL Query wizard </figcaption> </figure> - You can use operators such as `AND`, `HAS`, `IN`, and `OR`. - `AND` and `OR` have the same function in the formula as `AND` and `OR` in the Visual Builder (which is defining conditional dependencies between filters). - The `IN` operator works the same in both wizards and allows you to check if a value is included in an array. The first argument is a value, and the second is an array. - The `HAS` operator is available only in the IQL wizard. It allows you to check if an array includes a value. The first argument is an array, and the other is a value. - The brackets `()` let you group elements, for example to dictate the order of mathematical operations. ### IQL query functions | Function | Description | Syntax & Example of use | |----------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | TIMESTAMP | Converts a date-time string or a Unix timestamp string into a Unix timestamp (integer) which can be used in filters. If the ISO string doesn't include a timezone definition, the timezone of the workspace applies. Unix timestamps are always in UTC. | **1. Syntax**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/timestamp-syntax.png" class="large" alt="TIMESTAMP function syntax"><figcaption>TIMESTAMP function syntax</figcaption></figure> **2. Example of use**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/timestamp-example.png" class="large" alt="TIMESTAMP function usage example"><figcaption>TIMESTAMP function usage example</figcaption></figure> In this example, the function converts the result of an expression to a Unix timestamp which is then compared with the `created` attribute. | | NOW | Returns the current time (time of executing the filter) | **1. Syntax**:<br> This function doesn't have any arguments.<br>**2. Example of use**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/date-add-example.png" class="full" alt="DATE_ADD and NOW usage example"><figcaption>DATE_ADD and NOW usage example</figcaption></figure> In this example, 2 days are added to the current time (the time of executing the filter). | | DATE_ADD | Adds or subtracts a number of time units (`minutes`; `hours`; `days`; `months`; `years`) to a date variable. | **1. Syntax**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/date-add-syntax.png" class="large" alt="DATE_ADD syntax"><figcaption>DATE_ADD syntax</figcaption></figure> The arguments are: <ol><li>The time unit</li><li>The number to add (to subtract, enter a negative value)</li><li>The date to add/subtract from</li></ol>**2. Example of use**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/date-add-example.png" class="full" alt="DATE_ADD and NOW usage example"><figcaption>DATE_ADD and NOW usage example</figcaption></figure> In this example, 2 days are added to the current time (the time of executing the filter). | | ADD | Adds two values to each other. To add more at once, use SUM. | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/add-function-syntax.png" alt="ADD function syntax in AI Hub recommendation filters" class="full"></figure> Only of of the values can be dynamic (profile or item context), the other must be a static number.<br>**2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/add-function-example.png" alt="ADD function example in AI Hub recommendation filter including items more expensive than the currently browsed product" class="full"></figure> In this example, the result includes items which are more expensive than the item the customer is currently browsing. | | AVG | Returns the average value of a selected attribute (for example, a shoe size) | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/avg-function-syntax.png" alt="AVG function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/avg-function-example.png" alt="AVG function example in AI Hub recommendation filter returning items with the average size relative to the currently browsed product" class="full"></figure> In this example, the result includes items that have the average size in relation to size of the item the customer is currently browsing. | | BOTTOM_K | Returns the bottom K number of items from a list generated based on a specified item attribute, which may be expressed as a range such as price, number of visits to the item's page, or the quantity of item purchases. The final component of the function syntax allows for defining filter conditions to narrow down the results of the function; if you don't want to apply filters, select the **Take All** option - this component cannot be empty. | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/bottomk-function-syntax.png" alt="BOTTOM_K function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/bottomk-function-example.png" alt="BOTTOM_K function example in AI Hub recommendation filter returning the 10 least visited items of a specified brand in the last 7 days" class="full"></figure> In this example, the result will be 10 least visited items of the `clicmo` brand in the last 7 days | | CATEGORY | Allows to define the categories to be included or excluded while filtering items | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/category-function-syntax.png" alt="CATEGORY function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/category-function-example.png" alt="CATEGORY function example in AI Hub recommendation filter including items of exactly the same category as the currently browsed product" class="full"></figure> In this example, the result includes items of exactly the same category as the item the customer is currently browsing. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/category-function-example2.png" alt="CATEGORY function example in AI Hub recommendation filter including items in Electronics > Phones and Smartphones > Smartphones and its subcategories" class="full"></figure> In this example, all items that belong exactly to `Electronics > Phones and Smartphones > Smartphones`, or in one of the subcategories of `Electronics > Phones and Smartphones > Smartphones` are included in the result. The filter also includes items that have the category defined in the `additionalCategories` parameter. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The number allows to manipulate the category value. A positive number defines how many subcategories from the right should be dropped. If in the second example `0` was replaced with `1`, these would be the categories included in the filter: `Electronics > Phones and Smartphones`. A negative number defines how many subcategories from the left should be included. If in the second example `0` was replaced with `-1`, `Electronics` would be included in the filter. </div></div></div> | | IF | Allows logical comparisons between values and defining actions to be performed when the condition is met or not. | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/if-function-syntax.png" alt="IF function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/example-query-iql.png" alt="IF function example in AI Hub recommendation filter using a conditional IQL query to apply different price range rules based on item size and brand" class="full"></figure> Explanation is available in the [Examples of use](/docs/ai-hub/recommendations-v2/recommendation-filters-examples#iql-query) section (example 3). | | MULTIPLY | Multiplies the value of a variable by a specified constant | 1. Syntax <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/multiply-function-syntax.png" alt="MULTIPLY function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/multiply-function-example.png" alt="MULTIPLY function example in AI Hub recommendation filter including items whose price exceeds the currently viewed product's price multiplied by 0.8" class="full"></figure> In this example, the result includes items whose final price is higher than the price of the item the customer is currently browsing multiplied by `0.8`. | | TO_ARRAY | If you want to use an aggregate which returns a list of results, you need to convert that result to an array which can be deserialized by the filter. This is because Synerise aggregates return arrays as strings `"["foo","bar"]"` | **1. Syntax**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/toarray-function-syntax.png" class="large" alt="Empty 'To array' function"><figcaption>Empty TO_ARRAY function</figcaption></figure><br>**2. Example of use**: An aggreagate returns an array saved to a string and is converted back into an array that can be deserialized: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/toarray-function-example.png" class="full" alt="TO_ARRAY usage example"><figcaption>TO_ARRAY usage example</figcaption></figure> In this example, an aggregate returns a list (as string) of the brands of a customer's last 5 purchases. The TO_ARRAY function converts the result for use with the IN operator. | | MIN | This function returns the lowest value in a set of values | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/min-function-syntax.png" alt="MIN function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/min-function-example.png" alt="MIN function example in AI Hub recommendation filter including items larger than the smallest size of the currently browsed product" class="full"></figure> In this example, the result includes items whose size is larger than the smallest size of the item the customer is currently browsing. | | MAX | This function returns the highest value in a set of values. | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/max-function-syntax.png" alt="MAX function syntax in AI Hub recommendation filters" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/max-function-example.png" alt="MAX function example in AI Hub recommendation filter including items larger than the largest size of the currently browsed product" class="full"></figure> In this example, the result includes items whose size is larger than the largest size of the item the customer is currently browsing. | | NOT | Negates a filter | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/not-function-syntax.png" alt="NOT function syntax in AI Hub recommendation filter showing the required parameter for negating a filter condition" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/not-function-example.png" alt="NOT function example in AI Hub recommendation filter excluding pink-colored items from recommendation results" class="full"></figure> In this example, the result includes items of all colors except for pink. | | REQUIRED | Returns an error instead of null when a profile context is unavailable. Recommendations in the affected slot are not displayed at all. You can use this to make sure that recommendations are only displayed when the context is available.| **1. Syntax**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/iql-required-syntax.png" class="large" alt="REQUIRED function syntax"><figcaption>REQUIRED function syntax</figcaption></figure> As the argument, you can use: aggregates, expressions, segmentations, profile attributes, and profile tags (to return an error if the profile doesn't have any tags - to check for particular tags instead, use the IN operator) <br>**2. Example of use**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/iql-required-example.png" class="large" alt="REQUIRED function example"><figcaption>REQUIRED function example</figcaption></figure> In the example, the filter checks if the `brand` attribute of an item matches a value from a profile's tags. If the profile doesn't have any tags at all, the recommendation slot is not generated.| | SUM | Adds two or more values to each other. | **1. Syntax**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/iql-sum-syntax.png" class="large" alt="SUM function syntax"><figcaption>SUM function syntax</figcaption></figure> The argument must be an array of static numbers or a context (item or profile) which return an array of static numbers<br> **2. Example of use**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/iql-sum-example.png" class="large" alt="SUM function example"><figcaption>SUM function example</figcaption></figure> In the example, the function sums the `price.value` attribute of all context items. | | TOP_K | Returns the top K number of items from a list generated based on a specified item attribute, which may be expressed as a range such as price, number of visits to the item's page, or the quantity of item purchases. The final component of the function syntax allows for defining filter conditions to narrow down the results of the function; if you don't want to apply filters, select the **Take All** option - this component cannot be empty. | **1. Syntax** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/topk-function-syntax.png" alt="TOP_K function syntax in AI Hub recommendation filter showing the parameters to return the top K items by a range attribute" class="full"></figure> **2. Example of use** <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/topk-function-example.png" alt="TOP_K function example in AI Hub recommendation filter returning the top 10 best-selling in-stock items from the last 7 days" class="full"></figure> In this example, the result will be the top 10 best-selling items from the last 7 days that are currently in stock. | ### Creating a formula in the wizard --- Using the elements listed above and mathematical operators, you can create a filter formula that defines the conditions an item must meet in order to match the filter. In the tutorial below, the condition of the filters states that the recommendation displays only items that are of the same brand as the item currently displayed by a customer and the number of available items in the stock is higher than 12. If an item doesn't meet two conditions simultaneously, it won't be included in the result of the filter. <div class="vimeo-embed vimeo-facade not-prose" data-vimeo-id="499227379" role="button" tabindex="0" aria-label="Play Vimeo video"><span class="vimeo-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="#00adef"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div> ## Comparison between filters --- The table below shows the same business application of the filter in the two filter wizards. Earlier in the article, you can find explanations of similar examples as those presented in the table. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Click the image to enlarge it. </div></div></div> | Visual Builder | IQL Query | |----------------|------------| | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/color-visual-builder1.png" alt="Visual Builder filter in AI Hub comparing item color attribute" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/comparison-iql-example1.png" alt="IQL Query filter in AI Hub comparing item color attribute" class="full"></figure> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/visual-builder-user-context-example.png" alt="Visual Builder filter in AI Hub using customer profile context to match an item attribute" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-builder-user-context-example.png" alt="IQL Query filter in AI Hub using customer profile context to match an item attribute" class="full"></figure> | | *Not applicable* | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/example-query-iql.png" alt="IQL Query filter in AI Hub with a conditional expression applying different rules based on item size and brand" class="full"></figure> | | *Not applicable* | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/client-tags.png" alt="IQL Query filter in AI Hub filtering recommendations by customer profile tags" class="full"></figure> | | *Not applicable* | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/client-segmentations.png" alt="IQL Query filter in AI Hub filtering recommendations by customer segmentation membership" class="full"></figure> | | *Not applicable* | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-iql-bracket.png" alt="IQL Query filter in AI Hub showing bracket grouping of conditions with AND and OR operators" class="full"></figure> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/visual-builder-comparison3.png" alt="Visual Builder range filter in AI Hub comparing a numeric item attribute with an operator" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-builder-comparison3.png" alt="IQL Query range filter in AI Hub comparing a numeric item attribute with an operator" class="full"></figure> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/visual-builder-comparison4.png" alt="Visual Builder filter in AI Hub filtering by item subcategory hierarchy level" class="full"> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/category-function-example2.png" alt="CATEGORY function filter in AI Hub including items in Electronics > Phones and Smartphones > Smartphones and its subcategories" class="full"> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/expression-comparison-visual-builder.png" alt="Visual Builder filter in AI Hub comparing a value derived from a Synerise expression" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/expression-comparison-iql.png" alt="IQL Query filter in AI Hub comparing a value derived from a Synerise expression" class="full"></figure> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/aggregate-comparison-visual-builder.png" alt="Visual Builder filter in AI Hub comparing a customer aggregate metric value" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/aggregate-comparison-iql.png" alt="IQL Query filter in AI Hub comparing a customer aggregate metric value" class="full"></figure> | | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/predefined-metric-visualbuilder-comparison.png" alt="Visual Builder filter in AI Hub comparing a predefined Synerise metric value" class="full"></figure> | <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/predefined-metric-iql-comparison.png" alt="IQL Query filter in AI Hub comparing a predefined Synerise metric value" class="full"></figure> |</figure></figure> # A/B/X testing with external models You can use the External recommendations to include recommendations made by a third-party model in Synerise [A/B/X tests](/docs/ai-hub/recommendations-v2/recommendation-abx-test). ## Adding an external recommendation to tests To use this feature: 1. Create a recommendation campaign and set the type to **External**. To learn how to create a recommendation campaign, see [Creating recommendations](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign). 2. Create an A/B/X test and select the above recommendation as one of the variants. To learn how to create an A/B/X test, see [A/B/X testing](/docs/ai-hub/recommendations-v2/recommendation-abx-test). 3. When making a recommendation request, add the item IDs selected by the external model. - Those items must exist in the item feed used by the recommendation variant assigned to the profile. - The items can be sent: - In the query parameters of a [GET request](https://hub.synerise.com/api-reference/ai-recommendations#tag/Recommendations/operation/GetRecommendationsByCampaignV2) (`externalItemId`) - In the request body of a [POST request](https://hub.synerise.com/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendationsByCampaignV2) (`recommendedItemsFromExternalModel`). - In the `externalItemsIds` variable in [`recommendations3`](/developers/inserts/recommendations-v2#external-recommendations) and [`recommendations_json3`](/developers/inserts/recommendations-v2#recommendations-as-json) inserts. - If you don't add the external items and the external variant is assigned to the profile, no items are returned and a recommendation event isn't generated. See the diagram below. 4. Monitor the results of the test as described in [A/B/X testing](/docs/ai-hub/recommendations-v2/recommendation-abx-test). ## Logic overview This diagram explains how an A/B/X test response is processed when at least one of the variants is an external recommendation. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/abxtest-external.png" class="large" alt="Flowchart shows how an A/B/X test is processed when an external recommendation is included"><figcaption>How an A/B/X test is processed when an external recommendation is included</figcaption></figure> ## Logic description From the perspective of sending the external items: - If you send the external item(s) when you request an A/B/X test for a profile: 1. A variant is assigned or retrieved for the profile. 2. The response includes the recommended items and recommendation events are generated. - If you _don't_ send the external item(s) when you request an A/B/X test for a profile: 1. A variant is assigned or retrieved for the profile. 2. If the selected variant is an external recommendation: 1. The response doesn't include any items (because they weren't provided). The response includes information about the variant. 3. A recommendation event isn't generated. 4. You must make another request, this time providing the items from the external model. These items must exist in the item feed associated with the assigned variant. 5. The response includes the recommended items and you can display them. 6. A recommendation event is generated. 7. If the selected variant is a recommendation from a Synerise model: 1. The response includes the recommended items and you can display them. 2. A recommendation event is generated. # Creating promotions for selected products Promotions let you prepare customized, special offers for your customers which you can distribute in your mobile application, interactive kiosk or print out on receipts. The output of a promotion in Synerise is a code snippet sent to the medium on which you want to display the promotion. This medium must interpret the code with the logic implemented in the medium. Some settings — such as the promotion code format, cashback rules, basket pricing, and security options — apply to all promotions workspace-wide and can be configured in [Loyalty](/docs/settings/configuration/loyalty). ## Requirements --- - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise. - Optionally, you can import a list of stores to [Catalogs](/docs/assets/catalogs), which will let you select stores where the promotion is active. - If you want to limit the promotion to customers with a certain loyalty score, verify with your administrator that loyalty points are being calculated. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can find the example expression that counts loyalty points [here](/docs/crm/expressions/loyalty-point-count). </div></div></div> - If you want to use [promotion tags](/docs/ai-hub/promotions/promotion-tags), the tags must be in a `promotion`-type folder. ## Promotion statuses --- When you create a promotion in Synerise user interface, it gets a status which describes the progress of a promotion campaign: - **Draft** - The promotion isn't published. - **Published** - The promotion has been published and the system automatically [assigns](/docs/ai-hub/promotions/introduction-to-promotions#assigned) the promotion to the customers who meet its conditions. - **Hidden** - The promotion is published, but it is not visible in the channels it's distributed through. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotions-list.png" alt="A fragment of the promotion list" class="full"><figcaption>A fragment of the promotion list</figcaption></figure> ## Promotion limits --- ### Global limit This sets a cap on how many times the promotion can be activated, regardless of individual usage. Once this global limit is reached, the promotion becomes unavailable to everyone. - This event is generated when a [mobile SDK](/developers/mobile-sdk/loyalty#working-with-single-promotions) or [API](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions) method is used to try activating a promotion that reached its global limit. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The list of endpoints to which the request generates this event is listed in the ["Active" section](/docs/ai-hub/promotions/introduction-to-promotions#active). </div></div></div> - Changing global limits on an active promotion: - Changing the limit type (**unlimited**, **lifetime**, **relative date**) resets limit counter, and counting will start fresh from the time of the change. - Changing the limit value within a limit type is allowed and doesn't reset the counter. - The limit counter has a 365-day time-to-live, so activations beyond 365 days ago are excluded from the count. ### Per customer - Single - For promotions that can only be used once per activation. With this logic, you can set a maximum number of times a customer can activate a promotion. - Multibuy - For promotions that can be used a defined number of times per activation. With this logic, you can set limit on activations and how many times a promotion can be used within one activation. Full instruction on imposing promotion limits is described in the ["Types & limits" section](#type--limits). ## Procedure --- For your reading convenience, the procedure is divided into sections according to the UI. If you want to save a draft for later completion, click the **Finish later** button in the upper-right corner of the page. You can do this at any point of the procedure. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you click **Finish later** while working on a published promotion, it returns to draft status. </div></div></div> ### Creating a new promotion 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Regular Promotions**. 2. In the upper-right corner of the page, click **Add promotion**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotion-type-selection.png" alt="Selection of the promotion scope" class="large"><figcaption>Selection of the promotion scope</figcaption></figure> 3. Enter a name for the promotion.<br> 4. To inform other users about the purpose of the promotion, enter a description. 5. Select the **For selected items** option. **Result:** The default settings are applied to the promotion. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotion-empty-items.png" alt="A blank promotion" class="large"><figcaption>A blank promotion</figcaption></figure> ### Audience Select an audience for the promotion by performing one of the following actions: - If you want to create a promotion for everyone (default setting), no actions are required. - If you want to create a promotion for one or more customer segments: 1. In the **Audience** section, click **Change**. 2. Select **Segment**. 3. Click the **Select segment** button. 4. In the pop-up that opens, select the checkboxes of the segments that you want to include. 5. Click **Apply**. The pop-up closes. 6. Click **Apply**. ### Content In this section, you can define the basic settings related to the design of the promotion such as the description of an item, image, price before discount, and any other element you want to define in the form of a JSON frame. 6. In the **Content** section, click **Define**. 7. **Optional:** In the **Promotion code**, modify the default promotion code. The default code is unique. If you enter a new code, it must be unique too. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you use Synerise as [loyalty engine](/docs/ai-hub/promotions/introduction-to-promotions#full-variant), the POS uses this code to redeem the promotion. </div></div></div> 8. In the **Price** field, enter `0`. This field is deprecated. 9. In the **Price before discount** field, enter the price that will be displayed as the original price. 10. In the **Display name** field, enter a customer-visible name for the promotion. 11. In the **Description** field, enter a customer-visible description for the promotion. 12. Add thumbnails in one of the following ways: - If you want to add thumbnails from the database, click **Media manager** and choose a file from the list that opens. - If you want to upload a file, drag and drop the file to the **Thumbnails** field or click **browse** and choose a file from your local storage. 13. Add images in one of the following ways: - If you want to add thumbnails from the database, click **Media manager** and choose a file from the list that opens. - If you want to upload a file, drag and drop the file to the **Images** field or click **browse** and choose a file from your local storage. 14. To add tags to the promotion, click **Add tag** and choose a tag. 15. To add JSON code with advanced params, click **Advanced options** and paste the JSON code into the text box that appears. 16. Click **Apply**. ### Type & limits <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If Synerise is not used by your infrastructure as the promotion engine (which means calculating the amount to be deducted from the price), the settings defined here don't impact the logic of the promotion which, in such case, is implemented in the point of sales. </div></div></div> 17. In the **Type & limits** section, click **Change**. 18. From the **Type** drop-down list, select the promotion type. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Except for the **Handbill** promotion type, this categorization is only used for easier promotion management. </div></div></div> - **General** promotions are available to all customers. - **Custom** promotions not covered by the other types, for example loyalty rewards - **Members only** promotions are available to customers who joined a loyalty program. - **Handbill** promotions which can only be selected by the [AI promotion engine](/docs/ai-hub/personalized-promotions/introduction-to-ai-promotions) for a customer. 19. Enter a priority for the promotion. Priority defines the order of display in the customer's view. 1 is the highest priority. If two or more promotions applicable to a customer have the same priority, the order of display is determined by the date of creation. The one that was created earlier takes the priority over the other promotion. 20. Choose the promotion logic: - For promotions that can only be used once per activation, choose **Single**. With this logic, you can set a maximum number of times a customer can activate a promotion. - For promotions that can be used a defined number of times per activation, choose **Multibuy**. With this logic, you can set limit on activations and how many times a promotion can be used within one activation. 22. In the **Limit per profile** field: - for **Single** promotion logic, enter how many times the promotion can be activated. A promotion can be used once per activation. Redemption settings will be defined in the further part of the process, in the **Redemption type** field. <details class="accordion"><summary>Click here to see example scenario and its configuration</summary><div class="accordion-content"><table> <thead> <tr> <th>Scenario</th> <th>Configuration</th> </tr> </thead> <tbody><tr> <td>A customer can activate the promotion three times. During each activation, the customer can apply a 10% discount to an item once. The promotion will be redeemed after the first usage, however, the customer will still have two more activations available for use.</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/single-full-item.png" class="medium" alt="Example configuration of Single promotion logic"><figcaption>Example configuration of the Single promotion logic </figcaption></figure></td> </tr> </tbody></table></div></details> - for **Multibuy** promotion logic, define how many times the promotion can be activated. In the **Number of usage per activation** field, enter the number of times the promotion can be used in a single activation. Redemption settings will be defined in the further part of the process, in the **Redemption type** field. <details class="accordion"><summary>Click here to see example scenarios and its configurations</summary><div class="accordion-content"><table> <thead> <tr> <th>Scenario</th> <th>Configuration</th> </tr> </thead> <tbody><tr> <td>A customer can activate the promotion two times. During each activation, the customer can apply a $10 discount to the item. The promotion will be redeemed after it has been used a total of four times (resulting from two activations with two promotion uses per activation).</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/multibuy-partial-item.png" class="medium" alt="Example configuration of Multibuy promotion logic"><figcaption>Example configuration of Multibuy promotion logic - partial redemption</figcaption></figure></td> </tr> <tr> <td>A customer can activate the promotion twice. Within each activation, the customer can employ a 10% discount to the item. The promotion is considered redeemed after the first usage; however, the customer will still have two more activations available for use.</td> <td><figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/multibuy-full-item.png" class="medium" alt="Example configuration of Multibuy promotion logic"><figcaption>Example configuration of Multibuy promotion logic - full redemption</figcaption></figure></td> </tr> </tbody></table></div></details> 25. In the **Promotion global limits** section, define the [promotion global limits](#global-limit). - Changing the limit type (**unlimited**, **lifetime**, **relative date**) resets limit counter, and counting will start fresh from the time of the change. - Changing the limit value within a limit type is allowed and doesn't reset the counter. - The limit counter has a 365-day time-to-live, so activations beyond 365 days ago are excluded from the count. 1. Select one of the following tabs: - **Unlimited** - to set the promotion without an activation limit. This is the default setting. No further configuration is needed. - **Lifetime** - to set a limit without time range. In the **Activation global limit** field, enter the number of times a promotion can be activated by all profiles collectively. - **Relative** - Sets a limit that applies within a time window relative to each activation (for example, counting activations within a day of each activation request). This means the system checks how many promotions have been activated within a defined time window before the current activation attempt. 1. In the **Activation global limit** field, enter the number of time a promotion can be activated by all profiles collectively. 2. In **Time range**, choose the period for counting the limit. **EXAMPLE**: - **Activation time**: October 12, 2025, 10:00 AM - **Limit window:** 1 day When activating the promotion, the system checks how many activations occurred from October 11, 2025, 10:00 AM to October 12, 2025, 10:00 AM. If this number exceeds the global limit, activation is blocked. 24. From the **Discount type** drop-down list, select one of the following discount types: - **Percentage** sets the discount amount as a percentage of the original price. Example: if the original price is 1.00 USD and **Value** is `20`, the final price is 0.80 USD. - **Points** awards loyalty points for redeeming the promotion. - **2 for 1** allows a customer to receive a second, identical product for free. - **Exact price** sets a fixed price for the product. - **Amount** sets a fixed discount amount to subtract from the original price. - **Multibuy** is currently unused. 25. In the **Value** field, enter a value for the type selected in **Discount type**. 26. **Multibuy only:** From the **Redemption type** dropdown, select whether the promotion is redeemed after one or more activations. 28. From the **Discount mode** dropdown list, select one of the options: - **Static** - it's a fixed amount of discount (the unit depends on the selected type of promotion) - **Steps** - allows you to increase the discount amount as the number of transactions grows <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Steps can be used only for **Percentage**, **Amount**, and **Exact price** discount types. </div></div></div> 27. Only for **Percentage**, **Amount**, and **Exact price** discount types, you can use the following options: - **Buy one get one** - You can enable a promotion that allows you to give a discount for an item after the purchase a specific item (for example, buy one and get one 20% off or buy one and get one for $1). <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/bogo-example.png" alt="Example configuration of buy one get one" class="large"><figcaption>Example configuration of buy one get one promotion. In this configuration, a customer gets an item for $1 after the purchase of a specified item. </figcaption> </figure> - **Basket trigger** - This option allows you to create a promotion that can be used only if the basket value exceeds a threshold. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/basket-trigger-promotion-example.png" alt="Example configuration of basket triggered promotion" class="large"><figcaption>Example configuration of basket triggered promotion. In this configuration, a customer gets a 10% discount when their basket value exceeds $99. </figcaption> </figure> 26. Click **Apply**. ### Schedule In this section, you can define the time range when: - a regular promotion is available and visible - handbill-type promotions (for personalized promotions) are available to be drawn by the AI engine 1. In the **Schedule** section, click **Change**. 2. In the **Display time** sub-section, choose when the promotion becomes visible to customers. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> A promotion must be published to be visible. Publishing the promotion is the last step in this procedure, after all the settings are made. "Immediately" means "immediately after publishing". </div></div></div> 3. **Scheduled promotions only**: Set the time when the promotion is visible to customers by picking dates in the **Start** and **End** fields. 4. In the **Activity time** sub-section, define the time when the promotion can be activated: - If you want the time to be the same as the visibility time, select the **Same as display time** checkbox. - If you want to set a date range, pick the dates in the **Start** and **End** fields. 5. In the **Lasting** field, enter the time (in seconds) that a promotion remains redeemable after it is activated. `0` is interpreted as `infinity`. 6. Click **Apply**. ### Stores Optionally, you can select the stores where the promotion can be used. 1. In the **Stores** section, click **Define**. 2. From the **Select stores** drop-down list, select a catalog of stores. 3. Choose a set of stores: - If you want to apply the promotion to all stores in the catalog, select the **Entire catalog** radio button. - If you want to apply the promotion to particular stores from the catalog: 1. Click **Select stores**. 2. In the pop-up that opens, select the checkboxes of the stores where you want to apply the promotion. 3. Click **Apply**. The pop-up closes. 4. Click **Apply**. ### Items In this section, select the discounted items. 1. In the **Items** section, click **Define**. 2. From the **Select items** drop-down list, select a catalog of items. 3. Choose a set of items: - If you want to apply the promotion to all items in the catalog, select the **Entire catalog** radio button. - If you want to apply the promotion to particular items from the catalog: 1. Click **Select items**. 2. In the pop-up that opens, select the checkboxes of the items that you want to include in the promotion. 3. Click **Apply**. The pop-up closes. 4. Click **Apply**. ### Loyalty To limit the promotion to customers with a certain loyalty score, verify with your administrator that loyalty points are being calculated. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can find the example expression that counts loyalty points [here](/docs/crm/expressions/loyalty-point-count). </div></div></div> 1. In the **Loyalty** section, click **Change**. 2. If you want to enable the promotion only to customers who gathered a certain number of loyalty points, perform the following actions: 1. Select the **Minimum loyalty score** checkbox. 2. In the **Value** field, enter the number of required points. 3. Click **Apply**. ### Add voucher codes --- Optionally, in the **Voucher pool** section, you can select a voucher pool to assign voucher codes to profiles. The voucher code will be available to get in the contents of the promotion object and the code can be used on the selected items to be included in the promotion. Each time the promotion is activated, a new voucher code is assigned. How and when the voucher code appears or is used depends on the promotion setup and the platform (for example, a mobile app or a website). We strongly recommend monitoring your voucher pool levels as explained in [Monitor Voucher Pool Levels and Receive Alerts for Replenishment](/use-cases/voucherpools). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> To learn about code types, how to create a voucher pool, and how to add, assign, and distribute codes, see [Voucher pools](/docs/assets/code-pools). </div></div></div> 1. On the **Voucher pool** section, click **Define**. 2. From the **Voucher Pool** dropdown list, select a voucher pool from which the voucher codes will be retrieved. **Result**: You are shown a voucher pool summary - the number of voucher codes available for assignment (**Available vouchers**), the number of voucher codes in total in a voucher pool (**pool size**). 3. Use the **Enable voucher pool integration** toggle to enable or disable voucher assignment to a profile. By default, voucher assignment is enabled. When this option is disabled, you can still activate a promotion for a profile, but a voucher code won't be assigned (the code will not be returned). 4. To allow users other than the assigned end-user to redeem the voucher code, enable the **Allow voucher transfer** toggle. This option is supported **only** by the [`promotions/voucher/batch-redeem`](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchers) and [`promotions/voucher/batch-redeem-for-profile`](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchersForProfile) endpoints. - When this option is **disabled**, voucher codes are assigned to specific profiles and cannot be redeemed by other end-users. - When this option is **enabled**, and a voucher is redeemed, the following events are generated on the profile of the voucher code owner (the end-user to whom the voucher code was initially assigned): - [`client.removePoints`](/docs/assets/events/event-reference/loyalty#clientremovepoints) with the `beneficiaryClientUUid` parameter which contains the UUID of the end-user who redeemed the voucher, - [`voucherCode.redeemed`](/docs/assets/events/event-reference/loyalty#vouchercoderedeemed); 4. Confirm the settings by clicking **Apply**. ### Saving a draft or publishing - If you want to publish the promotion, click **Publish**. **Result:** If the schedule was set to "Immediately", the promotion becomes visible after you click **Publish**. If it was scheduled for a date, it becomes visible at that date. - If you want to save the promotion as a draft or return a published promotion to draft status, click **Finish later**. # Managing predictions Open **Predictions** to manage existing predictions and check their details such as logs of every single prediction (except for prediction drafts). The pane to the left of the list allows you to filter the list of predictions and see your usage limits. ## Actions on the prediction list --- In the list, you can perform the following actions for one prediction at a time: | Action name | Description | |-------------|-------------------------------------------------------------------------------------------------| | Calculate | Immediately starts the first calculation of the prediction. | | Recalculate | Immediately starts a re-calculation of the prediction. | | Edit | Opens the editing mode of the prediction. | | Duplicate | Creates a draft copy of the prediction. | | Delete | Deletes the prediction from the list without removing the events it generated. | | Stop | Stops the calculation of the prediction. | ## Prediction statuses --- The predictions can have the following statuses: | Status name | Description | |---------------|----------------------------------------------------------------------------------------------------------------------------------| | Calculating | The prediction is not ready, the calculation is in progress. | | Recalculating | The prediction is being recalculated. This may be started manually or according to the configuration of the prediction. | | Active | The prediction is ready. | | Draft | The prediction is saved as a draft and not ready to be submitted for calculation. | | Issue | Prediction generated results, but during the calculation some warnings occurred. Please adhere to the suggested changes. | | Error | The prediction didn’t pass the calculation stage, try to submit it for calculation once again with the suggested changes or contact the Synerise support team. | | Outdated | Contact the Synerise support team. | ## Prediction logs --- The Prediction Logs show you the status of an active prediction. You can check the logs to learn when your prediction might be ready, such as when you just activated your prediction or when it is recalculated. There is no specific time given when the prediction will be calculated, but you can see clearly how far in the process your prediction is and track how long it takes to get there. The logs contain details from the last 10 runs (recalculations). You can find the following information in the logs: - the stage at which the prediction is currently, - the progress of the process (expressed as a percentage), - elapsed time (the duration of the process in a stage), - date and time a process in a stage started, - log details available for copying (available after the calculation of the prediction) - error message for the latest run ### Stages When a prediction is activated it goes through the following stages: | Status | Description | |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Started/Scheduled | It is the first stage of processing a prediction: <br> - **Started** - the prediction is activated <br> - **Scheduled** - the activation of the prediction is scheduled at a future date | | Data preparation | At this stage, the system organizes and uploads the data for model training. This stage will not be repeated. | | Training | At this stage, the model is trained based on the provided data. This stage is followed by the calculation of the prediction and will not be repeated. | | Predicting | The prediction is calculated based on the model that was trained on the provided data. This stage can be repeated when you set the prediction to be recalculated in the configuration of the prediction. | ### Previewing logs --- To access the logs of the prediction: 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **(AI Predictions) Models**. 2. On the list of the predictions, click the prediction you want to see details of. 3. Select the **Logs** tab. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/prediction-logs.png" class="full" alt="The preview of logs"><figcaption>The preview of the prediction logs</figcaption></figure> 4. Next to the run of which you want to see the details, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three dot icon" class="icon" > icon. 5. From the dropdown list, select **View logs**. **Result**: A pop-up appears with the prediction log. <details class="accordion"><summary>Click here to see a fragment of a prediction log</summary><div class="accordion-content"><pre><code class="language-plaintext">Model id: XXXXXXXXXXXX Run id: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Started at: 2023-03-27T08:19:35.968000 2023-03-27T08:22:46.153391639Z 2023-03-27 08:22:46 [gsmodels.training] Running training for model_id=XXXXXXXXXXXX 2023-03-27T08:22:46.188222886Z 2023-03-27 08:22:46 [gsmodels.model_configuration] Downloading feature groups metadata 2023-03-27T08:22:46.501382138Z 2023-03-27 08:22:46 [gsmodels.training] Getting data for feature selection 2023-03-27T08:23:01.598561180Z 2023-03-27 08:23:01 [gsmodels.training] Running feature selection 2023-03-27T08:23:03.792744644Z 2023-03-27 08:23:03 [gsmodels.training] Selected 2 out of 197 features (1 out of 4 feature groups). 2023-03-27T08:23:03.792761653Z 2023-03-27 08:23:03 [gsmodels.training] Selected feature groups: {'transaction_charge_lifetime'} 2023-03-27T08:23:03.812890938Z 2023-03-27 08:23:03 [gsmodels.training] Getting data for training 2023-03-27T08:23:27.799897482Z 2023-03-27 08:23:27 [gsmodels.training] Loaded 339321 rows. 2023-03-27T08:23:27.802709891Z 2023-03-27 08:23:27 [gsmodels.training] Getting target statistics 2023-03-27T08:23:27.814395343Z 2023-03-27 08:23:27 [gsmodels.training] Classes distribution: '0': 316093, '1': 23228, total rows: 339321 2023-03-27T08:23:28.188081785Z 2023-03-27 08:23:28 [gsmodels.training] Training 2023-03-27T08:23:30.156435752Z 2023-03-27 08:23:30 [gsmodels.training] Training finished 2023-03-27T08:23:30.156466673Z 2023-03-27 08:23:30 [gsmodels.training] Getting metrics 2023-03-27T08:23:31.433284183Z 2023-03-27 08:23:31 [gsmodels.training] Training metrics 2023-03-27T08:23:31.433404908Z 2023-03-27 08:23:31 [gsmodels.training] { 2023-03-27T08:23:31.433423697Z 2023-03-27 08:23:31 [gsmodels.training] "accuracy": 0.9968466344453613, 2023-03-27T08:23:31.433440324Z 2023-03-27 08:23:31 [gsmodels.training] "f1": 0.9773389103616243, 2023-03-27T08:23:31.433446411Z 2023-03-27 08:23:31 [gsmodels.training] "precision": 0.9618070029178825, 2023-03-27T08:23:31.433482319Z 2023-03-27 08:23:31 [gsmodels.training] "recall": 0.9933806909912819, 2023-03-27T08:23:31.433486067Z 2023-03-27 08:23:31 [gsmodels.training] "roc_auc": 0.995881139038252, 2023-03-27T08:23:31.433518355Z 2023-03-27 08:23:31 [gsmodels.training] "balanced_accuracy": 0.9904820141799053, 2023-03-27T08:23:31.433523310Z 2023-03-27 08:23:31 [gsmodels.training] "ndcg": 0.9953841716713426, 2023-03-27T08:23:31.433526307Z 2023-03-27 08:23:31 [gsmodels.training] "avg_precision": 0.9619352874525635 2023-03-27T08:23:31.433565399Z 2023-03-27 08:23:31 [gsmodels.training] } 2023-03-27T08:23:31.666928161Z 2023-03-27 08:23:31 [gsmodels.training] Validation metrics 2023-03-27T08:23:31.666965694Z 2023-03-27 08:23:31 [gsmodels.training] { 2023-03-27T08:23:31.666970312Z 2023-03-27 08:23:31 [gsmodels.training] "accuracy": 0.9968466344453613, 2023-03-27T08:23:31.666982606Z 2023-03-27 08:23:31 [gsmodels.training] "f1": 0.9773640786968479, 2023-03-27T08:23:31.667016070Z 2023-03-27 08:23:31 [gsmodels.training] "precision": 0.9608985024958403, 2023-03-27T08:23:31.667054754Z 2023-03-27 08:23:31 [gsmodels.training] "recall": 0.9944037882049075, 2023-03-27T08:23:31.667088336Z 2023-03-27 08:23:31 [gsmodels.training] "roc_auc": 0.9960857895235649, 2023-03-27T08:23:31.667100999Z 2023-03-27 08:23:31 [gsmodels.training] "balanced_accuracy": 0.9914299516393723, 2023-03-27T08:23:31.667104683Z 2023-03-27 08:23:31 [gsmodels.training] "ndcg": 0.9948570584075384, 2023-03-27T08:23:31.667137914Z 2023-03-27 08:23:31 [gsmodels.training] "avg_precision": 0.9646890438948853 2023-03-27T08:23:31.667151243Z 2023-03-27 08:23:31 [gsmodels.training] } 2023-03-27T08:23:32.056626092Z 2023-03-27 08:23:32 [gsmodels.training] Test metrics 2023-03-27T08:23:32.056702368Z 2023-03-27 08:23:32 [gsmodels.training] { 2023-03-27T08:23:32.056724111Z 2023-03-27 08:23:32 [gsmodels.training] "accuracy": 0.9969940765626382, 2023-03-27T08:23:32.056729217Z 2023-03-27 08:23:32 [gsmodels.training] "f1": 0.9783806697753286, 2023-03-27T08:23:32.056737940Z 2023-03-27 08:23:32 [gsmodels.training] "precision": 0.9636743215031315, 2023-03-27T08:23:32.056794806Z 2023-03-27 08:23:32 [gsmodels.training] "recall": 0.993542832544124, 2023-03-27T08:23:32.056799284Z 2023-03-27 08:23:32 [gsmodels.training] "roc_auc": 0.9954989600303854, 2023-03-27T08:23:32.056839005Z 2023-03-27 08:23:32 [gsmodels.training] "balanced_accuracy": 0.9907905389661424, 2023-03-27T08:23:32.056858283Z 2023-03-27 08:23:32 [gsmodels.training] "ndcg": 0.9953921574572213, 2023-03-27T08:23:32.056861879Z 2023-03-27 08:23:32 [gsmodels.training] "avg_precision": 0.9682815577902703 2023-03-27T08:23:32.056887169Z 2023-03-27 08:23:32 [gsmodels.training] } 2023-03-27T08:23:32.056961044Z 2023-03-27 08:23:32 [gsmodels.training] Getting feature importance 2023-03-27T08:23:32.599428102Z 2023-03-27 08:23:32 [gsmodels.training] Saving model 2023-03-27T08:23:32.610470225Z 2023-03-27 08:23:32 [gsmodels.training] Uploading model 2023-03-27T08:23:33.010795571Z 2023-03-27 08:23:33 [gsmodels.training] Publishing training results</code></pre></div></details> # Creating personalized promotions Personalized promotions is a set of promotions selected by the AI engine for a particular customer. The promotions are managed by creating any [promotion type](/docs/ai-hub/promotions/creating-promotions#type--limits), which provide settings for the AI engine. When a promotion is generated for a customer, the AI retrieves the promotion available to the customer and selects the most relevant ones. ## Business advantages --- - High quality mechanisms of selecting items for a personalized promotion: - Checking the group of customers to whom the promotion is assigned. - Selecting the promotions whose start and end date covers the activity time of the personalized promotions. - In-built mechanisms that prevent overlapping items included in general promotions and advertising flyers with the items in personalized promotions. - In-built mechanism that prevents overlapping active promotions. - The great flexibility of promotion sets allows users to create relevant promotions that will apply in the distant future (in a year and longer). ## Prerequisites --- - Create a catalog that will be the source of items from the promotion. This can be your [item feed imported to a catalog](/use-cases/import-product-feed-to-catalog). The product identifiers (for example, `sku`) in the feed in the catalog must be consistent with product identifiers from transaction and interaction events. - Your transaction data history must be at least three months long. - Optionally, create a [catalog](/docs/assets/catalogs/creating-catalogs) with items you don't want to show in the personalized promotions. The product identifiers (for example, `sku`) in the feed in the catalog must be consistent with product identifiers from transaction and interaction events. - Optionally, if you want to consider only specific promotion candidates, create a filter on the list of (regular) promotions to be reused while preparing the personalized promotion. <details class="accordion"><summary>Click here to see how to build the filter</summary><div class="accordion-content"><ol> <li>Go to <strong>AI Hub > Regular Promotions</strong>.</li> <li>On the right side of the screen, click the filter icon. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/promotion-filter-define.gif" alt="Clicking the filter icon" class="full"></figure> </li> <li>Click <strong>Define</strong>.</li> <li>On the pop-up, define the conditions by clicking <strong>Choose filters</strong>. The list contains all parameters from the product feed. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/promotion-filter-defined.png" alt="Promotion targeted at anonymous customers" class="full"> <figcaption>Promotion targeted at anonymous customers</figcaption> </figure></li> <li>To add a new condition, repeat the previous step.</li> <li>Save the filter by clicking <strong>Save filter</strong>.</li> </ol></div></details> ## Create promotion candidates --- **Required actions**: - [create a promotion of any type, define the discount types and redemption settings ](/docs/ai-hub/promotions/creating-promotions#type--limits) - [schedule how long the items are available as candidates for the personalized promotion](/docs/ai-hub/promotions/creating-promotions#type--limits) - [select the items for the promotion](/docs/ai-hub/promotions/creating-promotions#items) ## Create a personalized promotion --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/handbill-general.png" alt="Configuring a personalized promotion" class="large"> <figcaption>Configuring a personalized promotion </figcaption> </figure> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub menu icon" class="icon"> **AI Hub > Personalized promotions > New promotion**. 2. Select the type of promotion: - **Check-in** - Example of use: If you have an interactive kiosk in your point of sales, your customers can register their loyalty card before they enter the shopping area. Then, they receive a print out of promotions available only for them. - **Check-out** - A promotion is generated based on their current transaction. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> It's the only type that allows you to prepare a personalized promotion for an anonymous customer. </div></div></div> - **Mobile app** - You can apply promotions dedicated only for the users of your mobile application. 3. In the **A/B test settings** add variants of the personalized promotion by clicking **Define**. You can define variants of the promotions and set up a control group. The control group is a part of the customer base that doesn't receive the promotions, so you can measure the effectiveness of your actions. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You must add at least one variant to continue creating the promotion. </div></div></div> 1. Click the plus button to add the first (and/or more) variants. 3. If you want to set up a control group, select the **Enable a control group** checkbox. 4. Adjust the size of each variant and the control group by using the slider. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/personalized-promotions/_gfx/variant-slider.gif" alt="Variant size adjustment" class="large"> <figcaption>Variant size adjustment</figcaption> </figure> 2. In the **Advanced options**, select how items are selected for the promotion. - **AI Engine** - By selecting this option, the AI engine chooses the items to be included in the promotion. - **Randomization** - By selecting this option, the items included in the promotions are chosen randomly. 3. Confirm by clicking **Apply**. **Result**: The remaining configuration options become available. ### Defining limits and order of discounted items --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-limits-promotions.png" alt="Filters and limits in the personalized promotions" class="full"> <figcaption>Filters and limits in the personalized promotions </figcaption> </figure> In the **Filters and limits** section, you can: - From the **Types** dropdown, select the types of promotions that can be selected. If you apply changes to this section without selecting a promotion type, Handbill is selected as the default option. - With the **Avoid overlapping promotions** toggle, choose what happens when an item is already part of an assigned promotion: - Enabled (default): A new promotion for this item is NOT generated. - Disabled: A new promotion is generated. - With the **Keep slot order** toggle, choose how items are ordered: - Enabled: Promotions are grouped by slot and the slots are returned in the order you set. - Disabled (default): Promotions are returned in an order AI for each customer by the AI. They are not grouped by slots. - If you want to add slots, click **Add another**. - With the **Promotions in slot** field, for each slot, define the number of returned promotions. - With the **Filter** selector, for each slot, select an item filter [created earlier](/docs/ai-hub/personalized-promotions/creating-ai-promotions#prerequisites) <details class="accordion"><summary>Click to see example</summary><div class="accordion-content"><figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-limits-promotions-example.png" alt="Personalized promotion for items of specific brand" class="full"> <figcaption>Personalized promotion for items of specific brand </figcaption> </figure> You can prepare a discount for 3 items of a defined brand, for example.</div></details> - **Check-out promotions only**: - If you want to add a basket condition, click **Add condition**. The conditions apply only to anonymous profiles. - With the **Minimum requirements for basket** fields, set the minimum value and/or number of items in the basket required for triggering this promotion. - If you want to add more conditions, click **Add condition**. At least one condition needs to met for the promotion to apply. ### Excluding items from promotions --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/exclude-items-promotions.png" alt="Exclude items from a promotion" class="full"> <figcaption> Exclude items from a promotion </figcaption> </figure> <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is available only for the Check-out type. </div></div></div> You can exclude items from the personalized promotion. You can either pick the items from a catalog or exclude an entire catalog. ### Defining promotion schedule --- In the **Activity** section, you can schedule the personalized promotions. - **Relative** - Select the activity time of the promotion, it is counted from the moment of generating a promotion for a customer (for example, if you distribute personalized promotions through a mobile application, the moment of generating a promotion is entering a section where the promotions are displayed). When the activity time of a personalized promotion expires, it is replaced with another one (if there are promotion candidates available). - **Absolute** - Select the exact date when a personalized promotion expires. The start date is the moment of generating a promotion for a customer (for example, if you distribute personalized promotions through a mobile application, the moment of generating a promotion is entering a section where the promotions are displayed). After it expires, the promotion won't be replaced by any other candidate. - **Recurring** - Define the days of the week when a personalized promotion is active. After it expires, it is replaced with another one (if there are promotion candidates available) <details class="accordion"><summary>Click here to see examples for recurring activity</summary><div class="accordion-content"><ul> <li>To generate new personalized promotions during the weekend, select Friday and Monday at 0:00. The personalized promotion will be generated on Friday at 00:00 and it will expire on Sunday at 23:59. On Monday at 0:00 the new personalized promotion is generated and it is valid to Thursday at 23:59. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recurring-example-one.png" alt="Limits for check-out" class="full"> <figcaption>Recurring limit, personalized promotion during the week and weekends </figcaption> </figure></li> <li>To generate personalized promotions every day at 5:00 in the morning, copy the settings from the image below: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recurring-example-two.png" alt="Limits for check-out" class="full"> <figcaption>Recurring limit, personalized promotion generated every day </figcaption> </figure></li> <li>To generate new promotions once a week, copy the settings from the image below: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recurring-example-three.png" alt="Limits for check-out" class="full"> <figcaption>Recurring limit, personalized promotion generated once a week</figcaption> </figure></li> </ul></div></details> ### AI engine boosting settings --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/engine-settings-promotions.png" alt="AI engine boosting settings" class="full"> <figcaption>AI engine boosting settings </figcaption> </figure> - If the items to your personalized promotion are selected by AI engine, in the **Engine settings** section, define the following parameters: - Adjust the variety of offered products by using the **Variety factor** slider. - In the **Group size** field, enter the maximum number of similar products that can be offered as promotions. - Adjust the frequency of delivering the same items in a promotion by using the **Redistribution frequency factor** slider. - Adjust the importance of a product's popularity by using the **Popularity boosting** slider. - To be able to assign multiple sets of promotions to customers, [create a filter](/docs/ai-hub/promotions/managing-promotions#saving-filters) on the list of promotions. # Item feed in a catalog You can upload an item feed to a [Synerise catalog](/use-cases/import-product-feed-to-catalog). ## General limitations --- - The name of the item catalog must be an alphanumeric string without any special characters nor whitespaces, following this regex pattern: `[a-zA-Z0-9]*`. - Item attribute names must be an alphanumeric string without whitespaces, following this regex pattern `^[_a-zA-Z0-9]+[\-_a-zA-Z0-9]*$`. - Item attribute string values must be alphanumeric. They can't contain following characters: - `"` - quotation mark - `'` - inverted comma - `.` - dot - `,` - comma - space or any whitespace character Therefore, `complex.name` is forbidden and you should rather use camelCase: `complexName` (preferred) or underscore format: `complex_name`. - Attribute names are case-sensitive. - Synerise accepts any properly formatted JSON which contains `itemId` and with proper key names. Later, item attributes are being returned by the API without changing or parsing values, which also applies to HTML/XML tags as values. You should handle the raw data retrieved from API in a way that will avoid the risk of XSS attack. - The item feed limit for [visual similarity](/docs/ai-hub/recommendations-v2/recommendation-types#visual-similarity) recommendation model is 1,000,000 items, regardless of the item feed type. ## Item format --- The format of an item is a JSON. Each object represents an item with its attributes, for instance: <pre><code class="language-json">{ "itemId": "Xa34ad3d", "intAttribute": 5, "floatAttribute": 2.5124, "stringAttribute": "asfdqw", "timestampAttribute": 1356846157, "booleanAttribute": true, "arrayOfStringsAttribute": ["A", "B", "C"], "nestedObject": { "a": 1, "b": "value" }, "nestedObjectsArray": [ { "x": "y" } ] }</code></pre> ## Attributes --- ### Required attributes <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Make sure to use the exact names as provided in the table below when setting up your item feed. </div></div></div> | Attribute name | Function | Why is it required? | |----------------|-------------------------|--------------------------------------------------------------------------------------------------------| | [`itemId`](#unique-identifier) | Unique identifier | Prevents any duplication of items and allows for accurate tracking and management of the items within the feed | | `title` | The name of the item | For visibility and searchability of the items and for training the AI model for the feed | | [`category`](#category-attribute) | The category of an item | For search and filter capabilities and for training the AI model for the feed | ### Accepted attribute values - string: `"foo"` - integer: `12` - float: `12.34` - boolean: `true/false` - nested objects: `{ "sub": { "a1": "v1", "a2": "v2" } }` - array (of strings, integers, floats, booleans, nested objects, arrays): `["foo", "bar"]` - timestamp: should be formatted as Unix timestamp, for example, `1356846157` - date: `2024-01-01T10:00:00Z` or Unix timestamp (`12345664000`) sent as a string ### Unique identifier --- Each item (each JSON document) must contain an `itemId` field which is a reserved key used as a unique item identifier. Its value type must be a string and it's case sensitive. As `itemId` is an item identifier, it is specially treated: - It is always returned by search API. - It is always returned by recommendations API. - Events (especially `page.visit` and `transaction.charge`) should contain a matching `itemId` ### Item availability attribute --- If you want to include the item availability attribute (`availability`) in your item catalog, the attribute's value must be a boolean. ### Category attribute --- `category` is a special attribute which is used to define the hierarchy of categories which an item belongs to. It must have the following format: ```plaintext X > Y > Z ``` Where `X` is a top level category and `Z` is the lowest category level. For example, `Electronics > Phone and Smartphones > Smartphones`. Category levels should be joined with ` > ` (literally space>space). When you have an item which belongs to more than one category, you can pass the `additionalCategories` field in the following format: ```json "additionalCategories": ["A > B > C", "D > E > F"] ``` Both `category` and `additionalCategories` are used when you filter by categories. ### Attribute best practices --- - We recommend using `category` as the attribute name for item categories, or `additionalCategories` if an item belongs to multiple categories; - Attribute names starting with `calculated.` or `inventory.` are not allowed. # AI Recommendations Recommendation allow users to present unique AI-powered item recommendations through several channels in order to promote items and encourage customers to make a purchase. We use the AI engine to acquire information from your website and analyze large portions of data such which is mainly customers' activity (visits to a website, purchases, historical data, and information included in the product feed). This way the Synerise application can produce relevant recommendations that match preferences of customers and circumstances of displaying the recommendation frame. In Synerise, a user can show recommendations within the following channels: - on the website (through [dynamic content](/docs/campaign/dynamiccontent)) - [emails](/docs/campaign/e-mail) - [web push notification](/docs/campaign/Webpush) - [mobile push notifications](/docs/campaign/Mobile) - mobile applications built based on [Documents](/docs/assets/documents) ## Business applications --- 1. Monetize customers' data and interactions to personalize experience across multiple touchpoints in different communication channels including web, mobile application, email, and many others. 2. Boost conversion at any step of customer journey from home page, category or item page, to cart, to post-purchase activities. 3. Generate top quality real-time recommendations for both recognized, unrecognized, and first-time customers based on various types of interaction. 4. Configure, launch, and deploy models to run and monitor performance of recommendation with only a few clicks with a simple user interface. 5. Tailor recommendation results to your business needs with recommendation configuration settings, including A/B testing, advanced filtering, boosting, and sorting options. 6. Benefit from state-of-the-art machine learning models powered by Synerise proprietary AI engine - Cleora. No need to manually process data ingestion and cleansing processes, models parameters tuning or retraining as framework does it for you. ## Requirements --- <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> To access AI Recommendations and manage recommendations campaign, you must have the following [permissions](/docs/settings/identity-access-management/permissions#permissions): - Permissions from the **Communications > Recommendations** set (at least **Read** to see the campaigns). - All permissions from the **Assets > Catalogs** set. </div></div></div> - [Prepare an item feed](/docs/ai-hub/recommendations-v2/item-feed-requirements) - Use consistent item identifiers in feed and events; events must include the item identifier - [Configure the AI engine](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations) - Meet the minimum data requirements of interactions and events. For users of multiple workspaces, we provide the option to train models for a workspace using data from other workspaces in situations where a data shortage in the target workspace prevents model training. This option is available for training the following recommendation models: [Personalized](/docs/ai-hub/recommendations-v2/recommendation-types#personalized), [Section page recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#section-page), [Attribute recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#attribute), [Cross-sell and Cart recommendations](/docs/ai-hub/recommendations-v2/recommendation-types#cross-sell-and-cart-recommendations), [Next interaction](/docs/ai-hub/recommendations-v2/recommendation-types#next-interaction). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The minimum requirements are approximate and allow model training. Meeting the minimum requirements does not ensure optimal operation. The quality of AI models increases with input data volume. </div></div></div> <table style="margin-left:auto;margin-right:auto"> <thead> <tr> <th>Recommendation type</th> <th>Minimum requirements</th> <th>Recommended requirements</th> </tr> </thead> <tbody> <tr> <td>- Personalized <br>- Section <br>- Attribute <br>- Next interaction </td> <td>- At least 1,000 unique profiles who visited a product page more than once. <br> - At least 10,000 of one of the following:<ul><li><a href="/docs/assets/events/event-reference/web-and-app/#pagevisit"><code>page.visit events</code></a> from item pages and <a href="/docs/assets/events/event-reference/web-and-app/#productview"><code>product.view events</code></a> from item views in a mobile application</li><li><a href="/docs/assets/events/event-reference/items/#transactioncharge"><code>transaction.charge events</code></a></li></ul> - Optionally, you can additionally select <a href="/docs/settings/configuration/ai-engine-configuration/custom-model-training/">custom events for model training</a>.</td> <td> - 50,000 unique profiles who visited a product page more than once (at least two different items). <br> - 1,000,000 in total of <a href="/docs/assets/events/event-reference/web-and-app/#pagevisit"><code>page.visit events</code></a> from item pages, <a href="/docs/assets/events/event-reference/web-and-app/#productview"><code>product.view events</code></a> from item views in a mobile application, and <a href="/docs/assets/events/event-reference/items/#transactioncharge"><code>transaction.charge events</code></a> <br> - The <code>title</code> and <code>category</code> item attributes must be selected as <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-training-attributes">training attributes</a> in the configuration of the AI engine (<b>Synerise > Settings > AI Engine Configuration</b>). <br> - To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a>.</td> </tr> <tr> <td>- Similar items<sup>1</sup> <br> - Item comparison</td> <td>At least one item attribute must be selected in the <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-training-attributes">training attributes section</a> in the AI engine configuration (<b>Synerise > Settings > AI Engine Configuration</b>). </td> <td>The <code>title</code> and <code>category</code> item attributes must be selected as <a href="/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations/#selecting-training-attributes">training attributes</a> in the configuration of the AI engine (<b>Synerise > Settings > AI Engine Configuration</b>). <br> - To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a> </td> </tr> <tr> <td>Visual similarity</td> <td>- Packshot images defined in the item catalog <br> - Image resolution of at least 640x480px</td> <td>- Packshot images defined in the item catalog <br> - Image resolution of at least 640x480px <br> - To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a></td> </tr> <tr> <td>- Cross-sell <br>- Cart recommendations</td> <td>At least 1,000 transactions with basket size > 1</td> <td>- At least 25,000 transactions with basket size > 1 <br> - To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a></td> </tr> <tr> <td>- Last seen <br>- Recent interactions</td> <td>No requirements</td> <td>To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a></td> </tr> <tr> <td>Top items</td> <td>At least 10,000 <a href="/docs/assets/events/event-reference/web-and-app/#pagevisit"><code>page.visit events</code></a> or <a href="/docs/assets/events/event-reference/items/#transactioncharge"><code>transaction.charge events</code></a> with at least 10 unique products</td> <td>To collect recommendation statistics, you must generate a <a href="/docs/assets/events/event-reference/recommendations/#recommendationclick">recommendation.click event</a>, which is triggered when a request is sent to the <a href="https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatProductSearchClickUsingPOST"> "Item clicked in recommendation" endpoint </a></td> </tr> </tbody> </table> <sup>1</sup>Similar item recommendations can be created with only the item feed, but events are recommended to build a more effective model. ## Limits Item feed limits: - For [visual similarity](/docs/ai-hub/recommendations-v2/recommendation-types#visual-similarity) recommendation model, the item feed can contain up to 1,000,000 items, regardless of the item feed type. The following are the default limits: - Maximum number of active recommendation campaigns: 1,000 - Maximum number of active and draft recommendation campaigns: 10,000 - Maximum number of AI recommendation models: 25 - Maximum number of items in recommendation: 100 - Maximum length of a filter (IQL string): 10,000 characters The following are the permanent limits (cannot be changed) per a recommendation. The limits apply both for filtering and boosting options: - Maximum number of unique segmentations: 1 - Maximum number of unique aggregates/expressions: 2 - Maximum number of unique customer attributes: 20 <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Multiple occurrences of the same analysis (a segmentation, expression, aggregate) or attribute count as one towards the limit. </div></div></div> ## Contents # Recommendation filters - examples of use This article is the continuation of the [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters) article and it contains the examples of recommendation filters usage. Each example considers a different business need. ## Visual Builder --- ### Defining condition between filters #### Example 1 <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-conditions-example.png" alt="A or B dependency" class="large"> <figcaption> A or B dependency </figcaption> </figure> If there are items that meet the conditions of the filter A (for example, if there are 13 or more pieces of an item), the recommendation frame shows the items described in the filter A. If there are no items that meet the filter A conditions, the recommendation frame shows the items that match the filter B (items of a different brand than the currently viewed item), if there are any. If there are no items that meet the conditions of any of the filters (neither filter A nor B), then the recommendation frame is empty. #### Example 2 <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-conditions-example.png" alt="A or B dependency" class="large"> <figcaption> A and B dependency </figcaption> </figure> The condition of both filters (A and B) must be met. It means the recommendation frame shows an item of which you have more than 12 pieces in stock and the brand of an item is different than the brand of the currently displayed item. If there are no items that meet the filter conditions simultaneously, the recommendation frame is empty. #### Example 3 <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-conditions-example3.png" alt="A or B dependency" class="large"> <figcaption> A and (B or C) dependency </figcaption> </figure> Items must meet the conditions of two filters at the same time: - the condition defined in the filter A (you must have 13 or more pieces of a specific item in your stock) - the conditions defined either in B or C filters **Success**: - Items meet conditions of A and B filters. - Items meet conditions of A and C filters. - Items meet all conditions (then) **Failure**: - Items don't meet the conditions of the filter A. - Items don't meet the conditions of both filters B and C. **Result**: The recommendation frame is empty ### Examples of use --- <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can see the same examples for the IQL Query wizard. Go to the [Examples](/docs/ai-hub/recommendations-v2/recommendation-filters-examples#iql-query) in IQL Query section. </div></div></div> 1. The goal of the recommendation is to display items whose number in your stock is greater than 12. To make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-example-of-use3.png" alt="Visual builder filter in AI Hub restricting recommendations to items with stock quantity greater than 12" class="full"> <figcaption> Items in recommendations are of the same brand as the currently displayed item </figcaption> </figure> 2. The goal of the recommendation is boost brand loyalty by promoting items of specific brand whose number of purchases exceeded over 150 times in the last 30 days. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/visualbuilder-metric-example.png" alt="Visual builder filter in AI Hub boosting brand loyalty by including items purchased more than 150 times in the last 30 days" class="full"> <figcaption> Items of specific brand which were purchased over 150 times in the last 30 days </figcaption> </figure> 2. The goal of the recommendation is to display items with size matched individually for each customer. To make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/visual-builder-user-context-example.png" alt="Visual builder filter in AI Hub using customer profile context to match recommended item size individually to each customer" class="full"> <figcaption> Size of the items adjusted individually for each customer </figcaption> </figure> 2. The goal of the recommendation is to display items in the recommendation frame of the same brand as the currently viewed items. In order to make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-example-of-use.png" alt="Visual builder filter in AI Hub restricting recommendations to items of the same brand as the currently viewed product" class="full"> <figcaption> The items displayed in recommendations </figcaption> </figure> <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can see the same example for the IQL Query wizard. Go to the Examples in IQL Query section. </div></div></div> 2. The goal of the recommendation is to display items in the recommendation frame that is discounted more than the currently viewed product. In order to make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/filter-example-of-use2.png" alt="Visual builder filter in AI Hub showing items more discounted than the currently viewed product" class="full"> <figcaption> Items in recommendations are of the same brand as the currently displayed item </figcaption> </figure> <details class="accordion"><summary>Click here to see the tutorial</summary><div class="accordion-content"><div class="vimeo-embed vimeo-facade not-prose" data-vimeo-id="498296155" role="button" tabindex="0" aria-label="Play Recommendation filters: Display items with a greater discount than the currently viewed item"><img src="https://i.vimeocdn.com/video/1356789480-cef13527ab9f86f2d25d85c9fb28f47002113d03d4e7024541e705952649225b-d_1280?region=us" alt="Recommendation filters: Display items with a greater discount than the currently viewed item" class="vimeo-facade-thumb" loading="lazy" /><span class="vimeo-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="#00adef"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div></div></details> <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> While creating the filters, consider the conditions set in the filters and the dependency between them (described by `OR` and `AND` operators) as well. </div></div></div> ## IQL Query --- ### Examples of use 1. The goal of the recommendation is to display items which number in your stock is greater than 12. To make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-wizard-example2.png" alt="IQL query filter in AI Hub restricting recommendations to items with stock quantity greater than 12" class="full"> <figcaption> The items displayed in recommendations </figcaption> </figure> 2. The goal of the recommendation is to display items with size matched individually for each customer. To make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-builder-user-context-example.png" alt="IQL query filter in AI Hub using customer profile context to match recommended item size individually to each customer" class="large"> <figcaption> Size of the items adjusted individually for each customer </figcaption> </figure> 2. The goal of the recommendation is to display items in the recommendation frame of the same brand as the currently viewed items. In order to make it happen, set the filters to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-wizard-example1.png" alt="IQL query filter in AI Hub showing items of the same brand as the currently viewed product" class="full"> <figcaption> Items in recommendations are of the same brand as the currently displayed item </figcaption> </figure> 3. The goal of the recommendation is to display items in the recommendation frame that are more expensive (above $180) when the size of the currently viewed item is larger than 36 and if this item is of the XYZ brand. In other case (when the size is smaller than 36 or the brand is not XYZ), the recommendation frame shows items which cost less than $180. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/example-query-iql.png" alt="IQL query filter in AI Hub using a conditional rule to show expensive items for large XYZ-brand sizes and cheaper items in all other cases" class="full"> </figure> 4. The goal of the recommendation is to promote items which are popular in summer. In order to make it happen, set the filter to the following configuration: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-summer-season-example.png" alt="IQL query filter in AI Hub promoting items popular in the summer season" class="full"> <figcaption> Recommending items popular in a selected season </figcaption> </figure> ## Use cases with practical examples --- - [Promote customer's favorite products in recommendations](/use-cases/boost-favorite-products) - [Excluding category of recently purchased products in recommendations](/use-cases/reco-excluding-recently-purchased-category) # Previewing recommendations You can check the preview of the recommendation in the following cases: - If you want to see the set of items recommended when there is a specific item or items in the shopping cart. - If you want to see the set of items recommended for a selected customer. - If you want to see the set of items recommended for a selected channel or channels. The context of the preview depends on the recommendation type selected. Below, you can find a table that shows which context is used in the preview of each type of recommendation. | Recommendation type | Item context | Customer context | Supplemental catalog context | |-----------------------|---------------------------------------------------------------|----------------------------------------------------------------|-----------------------------------------------------------------| | [Similar items](/docs/ai-hub/recommendations-v2/recommendation-types#similar-items) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Cross-sell](/docs/ai-hub/recommendations-v2/recommendation-types#cross-sell-and-cart-recommendations) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Cart](/docs/ai-hub/recommendations-v2/recommendation-types#cross-sell-and-cart-recommendations) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Last seen](/docs/ai-hub/recommendations-v2/recommendation-types#last-seen) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt="Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Top items](/docs/ai-hub/recommendations-v2/recommendation-types#top-items) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Personalized](/docs/ai-hub/recommendations-v2/recommendation-types#personalized) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark">| <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Visual similarity](/docs/ai-hub/recommendations-v2/recommendation-types#visual-similarity) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Item comparison](/docs/ai-hub/recommendations-v2/recommendation-types#item-comparison) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Recent interactions](/docs/ai-hub/recommendations-v2/recommendation-types#recent-interactions) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt="Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Section page](/docs/ai-hub/recommendations-v2/recommendation-types#section-page) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark">| <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Attribute](/docs/ai-hub/recommendations-v2/recommendation-types#attribute) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [Next interaction](/docs/ai-hub/recommendations-v2/recommendation-types#next-interaction) | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark">| <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | [External](/docs/ai-hub/recommendations-v2/recommendation-types#external)`*` | n/a | n/a | n/a| `*`- Previews are not available for external recommendations. ## Previewing recommendations (item context) --- This preview of recommendations is based on simulating the presence of an item in the cart. 1. Go to **AI Hub > (AI Recommendations) > Models**. 2. From the list of recommendations, click the recommendation you want to preview. **Result**: You are redirected to the recommendation details. 3. Select the **Preview** tab. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> For the Top items, the preview of the items is shown immediately after selecting the tab. </div></div></div> 4. In the **Item context** section, from the **Choose model item** dropdown list, select an item. **Result**: An item is added to the cart. In the **Recommended items** section, you can see the items recommended based on the item selected in the cart. ## Previewing recommendation (customer context) --- This preview of recommendations is based on the profile of a selected customer. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Available only for the Personalized recommendation, Last seen, and Recent interactions type. </div></div></div> 1. Go to **AI Hub > (AI Recommendations) > Models**. 2. From the list of recommendations, click the recommendation of which you want to preview. **Result**: You are redirected to the recommendation details. 3. Select the **Preview** tab. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-preview-profile-context.png" class="medium" alt="A dropdown menu that allows you to select a customer for whom the items in the recommendation are presented"><figcaption>A dropdown menu that allows you to select a customer for whom the items in the recommendation are presented</figcaption></figure> 4. In the **User context** section, from the **Choose profile** dropdown list, select a customer. 5. If the recommendation campaign has [co-brand personalization](/docs/settings/workspace/multibrand-workspaces/ai-recommendations) enabled, to include or exclude items from other workspaces in the group in the preview, enable the **Co-Brand Personalization** toggle. **Result**: In the **Recommended items** section, you can see the items recommended displayed in the recommendation frame for the selected customer. ## Previewing recommendation (supplemental catalog context) --- The recommendation preview is based on the selected [supplemental catalog](/docs/ai-hub/item-feed/supplemental-catalog) and its chosen channel(s). This ensures that the results are filtered and adjusted to reflect the availability and pricing details specific to those channels. The raw data reflects these changes, but the visual preview does not show them. To see the updated data, click **More Details** on any item in the preview and select the **Raw data** tab. 1. Go to **Communication > Recommendations**. 2. From the list of recommendations, click the recommendation which you want to preview. **Result**: You are redirected to the recommendation details. 3. Select the **Preview** tab. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-preview-supplemental-catalog-context.png" class="medium" alt="A dropdown menu that allows you to select a supplemental catalog, enabling filtering of recommended items based on the channels defined within that catalog"><figcaption>A dropdown menu that allows you to select a supplemental catalog, enabling filtering of recommended items based on the channels defined within that catalog</figcaption></figure> 4. In the **Supplement catalog context** section, click **Define**. 5. On the pop-up, to select a supplemental catalog, click **Add**. 6. From the **Catalog** dropdown list, select the supplemental catalog. 7. From the **Channels** dropdown list, select one or more channels whose item data you want to use for the recommendation preview. 8. Confirm by clicking **Apply**. 9. On any item in the preview, click **More Details**. 10. Select the **Raw data** tab. <div class="content-tabs" data-tab-group="tabgrp-1246"> <div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1246-0" data-tab-group="tabgrp-1246" data-tab-active="true">With supplemental catalog context</button><button class="tab-button" data-tab-id="tabgrp-1246-1" data-tab-group="tabgrp-1246">Without</button></div> <div class="tab-panel" data-tab-id="tabgrp-1246-0" data-tab-group="tabgrp-1246" data-tab-active="true"> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/supp-catalog-preview-after.png" class="medium" alt="The Raw data tab presents information about an item sourced from the supplemental catalog"><figcaption>The Raw data tab presents information about an item sourced from the supplemental catalog</figcaption></figure> </div> <div class="tab-panel" data-tab-id="tabgrp-1246-1" data-tab-group="tabgrp-1246"> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/supp-catalog-preview-before.png" class="medium" alt="The Raw data presents information about an item sourced from the main feed"><figcaption>The Raw data presents information about an item sourced from the main feed</figcaption></figure> </div> </div> ## Editing preview attributes --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/preview-attributes-recommendations.png" alt="Selecting attributes for preview" class="full"> <figcaption> Selecting attributes for preview </figcaption> </figure> You can set the preview attributes by clicking **Edit preview attributes**. By changing the preview attributes, you can control the attribute values that will appear in the preview. More information about attributes for preview is available the ["Selecting attributes for preview" section](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-recommendations#selecting-attributes-for-preview). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This setting is mutual for the Recommendation and AI search preview. </div></div></div> # Configuring A/B/X tests A/B/X tests allow you to seamlessly test various index settings. This is extremely helpful while optimizing your search engine settings. You can create indices with different settings and compare them in real time to your production index or you can test two or more indices in one test, these are just examples of business scenarios. The advantage of the feature is that when the test is set up, the traffic that reaches the base index is relocated among the base index and variants, according to the customer allocation set up in the test. So you won’t need to implement any changes on your frontend side. Before you configure an A/B test, you must create indicies with settings that you want to test. For the test to be conclusive these should be singular changes to the base index. ## Prerequisites --- - Import a product feed to Synerise. You can find instructions [here](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search). - Implement the [transaction events](/developers/web/methods-reference#tracking-transactions) and `item.search.click` event that is generated when an item shown in the search results is clicked. Use this [API method](https://hub.synerise.com/api-reference/data-management#tag/AI-Events/operation/publishAiCompatItemSearchClickUsingPOST). - [Create indexes](/docs/ai-hub/ai-search/create-index) <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> In order to avoid creating the settings from scratch you can duplicate the base index (with or without its rules and synonyms). Go to **AI Hub > Indexes**, and on the index you want to duplicate, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three dot icon" class="icon" > **> Duplicate**. We recommend introducing singular changes to each version of the base index, so the test will be conclusive. </div></div></div> ## Create A/B/X test --- 1. To create a new test, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > (AI Search) A/B/X tests > New A/B/X test**. 2. Enter the name of your A/B/X test. 3. In the **Variants and profile allocation** section, click **Define**. 4. Click the **Base variant** tab. 5. From the dropdown list, select the index which will be your baseline. It's highly recommended to choose a production index. 6. To add the next variant, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/add-variant-icon.png" alt="Plus icon" class="icon">. 7. From the **Index** dropdown list, select an index for this variant. You can rename the tab for better management of the versions. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can't use an index which is being used in another A/B test. </div></div></div> 8. To add the next variant repeat steps 6 and 7. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can add up to 5 variants. </div></div></div> 9. In the **Profile allocation** section, assign the percentage of customers to each variant. Once a customer is assigned to an index, the customer will be receiving items scored by that index in the search results. 10. Confirm the settings by clicking **Apply**. 11. If you want to save the test without launching it, click **Save**. 12. When the test is ready to launch, click **Save&Run**. After the test runs so long that all variants have searches, you can check the [Statistics](/docs/ai-hub/ai-search/ab-test-statistics). After the test, you can export the settings of a winning index to the baseline index (provided you selected the production index as your baseline index). <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can check the [use case](/use-cases/ai-search-ab-test) that describes testing two indexes: one that promotes personalized results and the one that promotes bestsellers. </div></div></div> ## Export settings of the winning version --- Exporting settings overrides any settings of the base index and finishes the A/B test. You may also end the test, analyze the results and export the settings later. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > (AI Search) A/B/X Tests**. 2. From the list, select the A/B/X test. 3. Click the **Statistics** tab. 4. On the variant, click **Export settings**. 5. On the pop-up, click **Confirm**. # Supplemental catalog The supplemental catalog is a feed designed to store price and availability attributes for items across different stores or sales channels. It cannot operate as a standalone item feed and must be used alongside a main item feed that contains the complete item information. In this setup, the main item feed does not need to include price or availability data, as these will be sourced from the supplemental catalog. The supplemental catalog obtains its data from a catalog created and populated in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/data-modeling-hub-icon.svg" alt="Data Modeling Hub icon" class="icon"> **Data Modeling Hub > Catalogs** - this is the first step in implementing a supplemental catalog. Then, you create a supplemental catalog feed based on this catalog and link it to your chosen main item feed(s). For detailed instructions, see the ["Implementing supplemental catalogs" section](#implementing-supplemental-catalogs). ### Business benefits - Manage prices and availability individually for each store or sales channel. - Achieve better organization of attributes in recommendation filters. ### Purpose and usage - Must contain the `price` and `availability` item attributes, but can include additional attributes as well. - When connected with the main item feed: - The **main item feed** includes common item attributes. - The **supplemental catalog** holds item prices and availability per store or sales channel. - When supplemental catalog or catalogs are connected with the item feed, the supplemental attributes are available for use in: - the [recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters): <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/supplemental-attributes-filters.png" class="medium" alt="Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder"><figcaption>Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder</figcaption></figure> - the [recommendation preview](/docs/ai-hub/recommendations-v2/previewing-recommendations#previewing-recommendation-supplemental-catalog-context) (only `channel` attribute from the catalog): <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-preview-supplemental-catalog-context.png" class="medium" alt="A dropdown menu that allows you to select a supplemental catalog, enabling filtering of recommended items based on the channels defined within that catalog"><figcaption>A dropdown menu that allows you to select a supplemental catalog, enabling filtering of recommended items based on the channels defined within that catalog</figcaption></figure> ### Requirements - The file imported into a catalog must include the following attributes: <div class="content-tabs" data-tab-group="tabgrp-1245"> <div class="tab-buttons"><button class="tab-button" data-tab-id="tabgrp-1245-0" data-tab-group="tabgrp-1245" data-tab-active="true">for CSV files</button><button class="tab-button" data-tab-id="tabgrp-1245-1" data-tab-group="tabgrp-1245">for JSON files</button></div> <div class="tab-panel" data-tab-id="tabgrp-1245-0" data-tab-group="tabgrp-1245" data-tab-active="true"> | Attribute | Description | Value type | |-------------|------------------------------------------------------|------------| | `itemId` | Unique identifier of the item. | string | `channelId` | Identifier of a store or sales channel. | a string that matches this regular expression: `^[-_a-zA-Z0-9:]+$` | | `price.value` | A price of an item in a store or sales channel | float | | `availability` | Availability of an item in a store / sales channel | boolean | **Example**: <pre><code class="language-plaintext">channelId,itemId,availability,price.value store100,Xa34ad3d,true,29.99 store101,Xa34ad3d,true,25.99 store102,Xa34ad3d,true,27.99 store103,Xa34ad3d,false,28.99</code></pre> </div> <div class="tab-panel" data-tab-id="tabgrp-1245-1" data-tab-group="tabgrp-1245"> - The `itemKey` must be an item ID (this information is important for importing JSON file to a catalog through API). - The file must contain the following parameters and objects: - The `itemId` parameter must be a string. - The `availability` parameter must be a boolean. - The `channelId` parameter must be a string. - The `price` object must be a float. **Example**: <pre><code class="language-json">{ "itemId": "59067514940593", "availability": true, "channelId": "europeRegion", "price": { "value": "12.99" } }</code></pre> </div> </div> <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Regardless of the file type you import to a catalog (either through a simple import or through a workflow), you must enable the **JSON dot notation** toggle. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/assets/_gfx/selecting-catalog.png" class="large" alt="Selection of the catalog"><figcaption>Selection of the catalog</figcaption></figure> </div></div></div> - The required file format depends on the method you will choose to upload data to a catalog: - for a [simple import](/docs/assets/imports/importing-data-to-catalogs) - only CSV files are supported. - for [a workflow method](/use-cases/import-product-feed-to-catalog) - The accepted file format depends on the data source. Refer to the [list of supported sources](/docs/automation/integration) — only Get Data nodes allow sourcing data. - for [API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs) - Data is defined within the request payload. Be sure to follow the request size limits. ### Implementing supplemental catalogs To connect a supplemental catalog to your main item feed, follow these steps: #### Create a catalog to serve as the data source for the supplemental catalog This catalog will hold the data that your supplemental catalog feed will use. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/data-modeling-hub-icon.svg" alt="Data Modeling Hub icon" class="icon"> **Data Modeling Hub > Catalogs > New catalog**. 2. In **Catalog name**, provide the name of the catalog. 3. Confirm by clicking **Apply**. **Result**: An empty catalog is added to the catalog list. 4. Upload a file with [the required data](#requirements). - While uploading data to a catalog, you will need to indicate a primary key, for details see [Requirements](#requirements). - You can upload data through the following methods: - through a [simple import](/docs/assets/imports/importing-data-to-catalogs) to a catalog - this lets you conduct a one-off import of data - [through a workflow](/use-cases/import-product-feed-to-catalog) to a catalog - this lets you conduct one-off or cyclical imports to a catalog using the Automation Hub. - [through an API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync) to a catalog - this lets you conduct one-off or cyclical imports to a catalog using an API method. #### Create a supplemental catalog feed linked to your catalog This feed lets you use the catalog as a data source for price and availability information for your main item feed and control which item attributes will be available in the **Supplemental attributes** tab in the recommendation filter. 1. Go to **Settings > AI engine configuration > Add feed**. **Result**: A pop-up appears. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/add-feed-pop-up.png" class="medium" alt="A pop-up with selection of the item feed type"><figcaption>A pop-up with selection of the item feed type</figcaption></figure> 2. Select **Catalog**. **Result**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/feed-catalog-options.png" class="medium" alt="A pop-up with selection of the item feed type"><figcaption>A pop-up with selection of the item feed type</figcaption></figure> 2. Select **Supplemental catalog**. 3. On the pop-up, from the **Catalog** dropdown list, select the catalog which will [be the source of data](#create-a-catalog-to-serve-as-the-data-source-for-the-supplemental-catalog). **Result**: The supplemental catalog feed is added to the list. 3. Find the created supplemental catalog feed on the list and click it. 3. In the **Product feed connection** section, connect this feed to your main item feed or feeds. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/supplemental-feed-config.png" class="large" alt="Configuration of the supplemental catalog"><figcaption>Configuration of the supplemental catalog</figcaption></figure> 4. In the **Filterable attributes** section, you must select the item attributes from the supplemental catalog which will be available in recommendation filters. - The attributes will be available in [recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters) in the **Supplemental attributes** tab. - While selecting the attributes to be available in the filters you can define their value types by using: text, range, and datetime options. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Make sure `price.value` is set to **Range** and `channelId` is set to **Text**. </div></div></div> <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/attribute-value-types.png" class="medium" alt="Defining value types for attributes selected in the Filterable attributes section"><figcaption>Defining value types for the attributes selected in the Filterable attributes section</figcaption></figure> 5. In the **Response attributes** section, you must select the item attributes from the supplemental catalog which will be returned in the recommendation. 5. Confirm the settings by clicking **Save**. ## Supplemental attributes A list of item attributes sourced from the supplemental catalog are available in the recommendation filters only when [the item feed is connected with any supplemental catalog](#create-a-supplemental-catalog-feed-linked-to-your-catalog). If several supplemental catalog feeds are connected with the item feed, then this tab gathers all attributes from all supplemental catalogs. - In [the visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder), you can find them in the **Supplemental attributes** tab: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/supplemental-attributes-filters.png" class="medium" alt="Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder"><figcaption>Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder</figcaption></figure> - In the [IQL filter builder](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query), you can find them in **Supplemental attribute** in the **Attribute** category: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/iql-builder-supplemental-attribute.png" class="medium" alt="A dropdown for the Attribute category"><figcaption>A dropdown for the Attribute category in IQL filter builder</figcaption></figure> ## Supplemental catalog status You can track item inconsistency for the supplemental catalogs, more information is available in the ["Item consistency" section](/docs/settings/configuration/ai-engine-configuration/feed-status#item-consistency). # Recommendation statistics The Synerise platform offers you a full statistics panel in the recommendation details. In the **AI Hub > (AI Recommendations) Models** view, you can view the statistics in two ways: - On the [list of recommendations](#list-of-recommendations), you can view basic statistics for each campaign. - After opening a recommendation's details, you can see more statistics on the [**Statistics** tab](#statistics-tab) Before you read the description of the metrics in the statistics, there is a term that you may not be familiar with: - **a unique recommendation frame** - it is a very first view of a recommendation frame (for example, if a customer sees a recommendation frame whose ID is `1234`, and this recommendation is displayed for the second, third and more times, these views are not considered unique) The statistics are calculated from these events: - [recommendation.click](https://hub.synerise.com/api-reference/data-management#operation/publishAiCompatRecommendationClickUsingPOST) - [recommendation.view](https://hub.synerise.com/api-reference/data-management#operation/publishAiCompatRecommendationViewUsingPOST) - `recommendation.generated` - this event is generated automatically after a request is sent to any endpoint that starts with [`recommendations/v2/recommend`](https://hub.synerise.com/api-reference/ai-recommendations#tag/Recommendations) - [transaction.charge](https://hub.synerise.com/api-reference/data-management#operation/CreateATransaction) <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Some metrics, particularly those counting unique values (such as unique views), use approximate aggregation algorithms for performance reasons. As a result, the displayed values may differ slightly from exact counts. The margin of error is typically less than 0.5% relative to the metric's value — for example, a count of 1,000,000 unique views may differ from the exact figure by up to ~5,000. This does not affect the overall interpretation of the data. </div></div></div> ## List of recommendations --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-stats-list.png" class="full" alt="Metrics on the list of recommendations"><figcaption>Metrics on the list of recommendations</figcaption></figure> |Metric name|Description|Required events| |--- |--- |--- | | CTR |(Click Through Rate) It is the number of clicks on <br> a recommendation frame divided by the number of <br> generated in the last 30 days.| - `recommendation.click`,<br> - `recommendation.generated`| |Revenue|Revenue generated by the recommendations in the last 30 days. <br> It is counted when a customer buys an item within <br> 24 hours after clicking the item in the recommendation frame.|- `recommendation.click`,<br> - `transaction.charge`, <br> - `recommendation.generated`| ## Statistics tab --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/reco-main-stats.png" class="full" alt="A part of recommendation statistics in the Statistics tab"><figcaption>A part of recommendation statistics in the Statistics tab</figcaption></figure> In this tab, you can find detailed statistics: ### Campaign metrics |Metric name|Description|Required events| |--- |--- |--- | | CTR |(Click Through Rate) It is the number of clicks on <br> a recommendation frame divided by the number of <br> recommendation generations in the last 30 days.| - `recommendation.click`,<br> - `recommendation.generated`| | Conversion Rate | It is the number of unique products bought <br> divided by the number of all clicks. <br> Clicks made within 24 hours of a transaction <br>count towards the conversion rate of the day <br> when the transaction was made. |- `recommendation.click`,<br> - `transaction.charge`| |Avg. revenue| (Average revenue) It is calculated by dividing revenue <br> by the number of unique customers (those for whom <br> recommendation was generated). <br> You can find the explanation of <br> how revenue is calculated further in this table. |- `recommendation.click`,<br> - `transaction.charge`, <br> - `recommendation.generated`| |Generations |It is the number of generated recommendation frames. |`recommendation.generated`| |Views|It is the total number of unique recommendation frames <br> a customer has seen.|- `recommendation.view`,<br> - `recommendation.generated`| |Clicks|The number of unique clicks on a recommendation frame. |- `recommendation.click`,<br> -`recommendation.generated`| |Unique Products Bought |The number of purchased unique items. <br> For example, if a customer purchased 2 pieces <br> of the same product, the number of unique items is 1.| `transaction.charge`| |Revenue|Revenue generated by the recommendations. <br> It is counted when a customer buys an item within <br> 24 hours after clicking the item in the recommendation frame.|- `recommendation.click`,<br> - `transaction.charge`,<br> - `recommendation.generated`| |Click Through <br> Rate and Conversion Rate (chart)|The chart compares CTR (number of clicks on <br> a recommendation frame divided by the number of <br> recommendation generations) and Conversion Rate <br> (number of unique products bought divided by <br> the number of all clicks) in a given period.|- `recommendation.click`,<br> - `recommendation.generated`, <br> - `transaction.charge`| |Recommendations <br> viewed vs generated|It is a contrast between two situations: when a recommendation <br> was actually viewed (for example, when a customer <br> scrolled down to the recommendation frame and saw it) <br> and when the customer entered the website, <br> but didn't see the generated recommendation.|- `recommendation.view`,<br> - `recommendation.generated`| |Clicks in Recommendation|It is the graphic representation of the total amount <br> of clicks on the product (within <br> a recommendation frame) during the selected period. |- `recommendation.click`,<br> - `recommendation.generated` | |Unique Products Bought |It is the graphic representation of the number of <br> purchased unique items in the selected period. | - `transaction.charge`,<br> - `recommendation.generated`,<br> - `recommendation.click`| |Number of Products Bought|It is the total number of the purchased items during <br> the selected period.|- `recommendation.click`,<br> - `transaction.charge`,<br> - `recommendation.generated`| ### Item metrics For each campaign, you can check the best-performing items. They are available in the **Top products** section of the statistics. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recommendations-stats-top-items.png" class="large" alt="Top items for a campaign"><figcaption>Top items for a campaign</figcaption></figure> By using the **Metrics** dropdown list on the right, you can choose the condition by which the best items will be selected: | Metric name | Description | Required events | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | Generations | The number of recommendation frames which included this product | `recommendation.generated` | | Clicks | The number of times this product was clicked in a frame | - `recommendation.click`,<br> - `recommendation.generated` | | Charges | The number of transactions with this item which occurred within 24 hours of clicking the item. | - `recommendation.click`,<br> -`recommendation.generated` | | Revenue | The revenue generated by showing this item in a recommendation frame | - `recommendation.click`,<br> - `transaction.charge`,<br> - `recommendation.generated` | | Views | The number of times this item was shown after a recommendation was generated.<br> This is separate from generating a frame, because the frame might be displayed partially and items are only shown after scrolling or otherwise changing the view. | - `recommendation.view`,<br> - `recommendation.generated` | # A/B/X test statistics When the A/B/X tests has been running for long enough, you can analyze the statistics for each variant. If one of the variants performed exceptionally well, you can [export its settings](/docs/ai-hub/ai-search/configuring-ab-test) to the base variant. 1. To preview the A/B test statistics, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" >**AI Hub > (AI Search) A/B/X Tests**. 2. From the list, select the A/B/X test. 3. Click the **Statistics** tab. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ab-test-statistics.png" class="full" alt="The preview of A/B test statistics"> <figcaption>The preview of A/B test statistics</figcaption> </figure> | Data | Description | |----------------------|-----------------------------------------------------------------------------------------------| | Searches | The total number of searches performed through the index. | | CTR | (Click Through Rate) It is the ratio of the number of clicks in search results from an index to all searches within this index. | | Conversion | This metric shows the ratio of clicked search results that ended up with a purchase to those which were clicked. <br> A purchased item is bound to the search click event when the item is purchased in 5 or fewer days since clicking the search result. | | Avg. click position | It is the average placement of a clicked item on a list of search results. This position is indicated by ordinal ranking, with the higher numbers representing lower positions in the search results. This metric is calculated by dividing the sum of all positions to the number of all clicks on search results. | | Revenue per profile | It is the value of transactions made by a unique profile after clicking the product in the search results. | # Query suggestions Suggestions are recommended options or predictions that appear while you are typing a search query. These suggestions are meant to help you find what you are looking for more efficiently by providing relevant choices based on popular or similar searches. The appearance and relevance of these suggestions depend on the popularity of the search queries entered. This feature lets you create a suggestion index which can be a combination of several [suggestion types](#suggestion-types). The feature has in-built typo correction to ensure valid suggestions for queries with minor errors. ### Suggestion types You can use these suggestion types: 1. Suggestions generated directly from queries which meet requirements regarding popularity and relevance. 2. Suggestions generated from item attributes values, also grouped. 3. Suggestions defined manually. ### Features You can define the following settings for query suggestions: - Index of suggestions; it's built on the basis of the popularity of the searched queries and the results returned in response to these queries. The threshold of the popularity and query results is adjustable according to the customer's preferences as well as time range of the analyzed data. - Attributes a query suggestion is based on; it is possible to set up the suggestion index to be built on an attribute from one or more catalogs. The suggestions are returned based on the similarity of the attribute values that are typed by the customer into the search box. - Manual suggestion phrases; define a list of phrases and manually modify the popularity threshold to increase the probability of suggesting that phrase by the AI model. - Denylist of phrases which will never be returned as a query suggestion. - By means of [Query suggestion statistics](/docs/ai-hub/ai-search/query-suggestions-statistics), you can monitor user interaction with query suggestions, allowing teams to evaluate their effectiveness, optimize relevance, and uncover customer intent patterns. <!-- <div class="youtube-embed youtube-facade not-prose" data-youtube-id="f1gMcWiJuYw" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - What are Query Suggestions?"><img src="https://img.youtube.com/vi/f1gMcWiJuYw/hq720.jpg" alt="Synerise Academy - AI Search - What are Query Suggestions?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div> ---> ## Requirements --- [Create an index](/docs/ai-hub/ai-search/create-index). If you want the suggestions to include only available items: - Add the `availability` parameter with boolean values (`true`/`false`) to the feed used for creating an index. - In the [index settings](/docs/ai-hub/ai-search/define-language-and-separators), leave the **Include out of stock items** toggle disabled. If you will use more than one index for query suggestions, make sure all indexes meet the requirements above if you want the suggestions to include only available items. ## Configuration --- <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/query-suggestions.png" alt="Blank query suggestions settings" class="full"> <figcaption> Blank Query Suggestions settings </figcaption> </figure> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Suggestions**. 2. Click **New suggestion**. 3. Enter the name of the query suggestion. 4. To define the settings in the **Event-based suggestions**, click **Define**. 1. Click **Add index**. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> An index is a data structure based on the input of the selected catalog. A search engine refers to the index while looking for relevant results in response to a specific query. It's created on the basis of [catalogs](/docs/assets/catalogs). </div></div></div> 2. From the dropdown list, select the index. 3. Next to the selected index, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/arrow-down-icon.png" alt="Arrow down icon" class="icon" > icon. **Result**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/suggestions-index-settings.png" class="medium" alt="Index settings"><figcaption>Index settings</figcaption></figure> 4. In **Minimum searches**, enter the number of times a phrase must be searched before it is included in the suggestions. 5. In **Minimum number of query results**, enter the minimum number of search results that contain a given phrase before it is included in the suggestions. 6. To define the minimum number of characters of a query to be involved in the query suggestion index, switch the **Minimum number of letters in a phrase** toggle on and enter the number. This way you can prevent no-result searches. 7. To define the time range the search analyzes, switch the **Only recent history** toggle on. The time range covers the entered number of days backwards from today, including today (the filter is elastic and today is always a current date). When the toggle is switched off, it's lifetime. 8. To validate the queries against the product feed before the query suggestion index is built, switch the **Verify suggestions** toggle on. 9. In **Minimum number of phrase occurrences**, enter how many times a word must occur in the feed to be treated as verified. 8. Optionally, you can add more indices. To do so, repeat steps **a-h**. 9. Confirm the settings by clicking **Apply**. 5. To define the settings in the **Attribute suggestions** section, click **Define**. 1. To select a catalog from which the attributes are taken, click **Add another group**. 2. Next to **Group 1**, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/arrow-down-icon.png" alt="Arrow down icon" class="icon" > icon. 2. From the **Catalog** dropdown list, select a catalog. **Result**: A **Select attributes** button appears. **Result**: A pop-up appears. 3. On the pop-up select a group of attributes. - You can add several attributes in one group. Then the suggestions can include many variations of the attribute values (for example, for `color` and `category`, the suggestions could be: black shirt, green dress, red skirt, and so on). - You can add one attribute in one group. Then the suggestions will be displayed one at a time. 4. To add more attribute groups, click **Add another group**. Repeat steps b-d. 6. Confirm the settings by clicking **Apply**. 6. To define the settings in the **Manual suggestions** section, click **Define**. You can manually add phrases to suggest. The visibility of the suggested phrases is based on their popularity. In this section, you define a phrase or phrases you want to be suggested and define artificially boosting their popularity. 1. To add a phrase to the suggestion index, click **Add phrases**. **Result**: A pop-up appears. 2. In the **Phrase** text field, enter a phrase. 3. In the **Number of additional searches** field, enter the number of searches to add to the actual searches made with this phrase by customers. Thanks to manually adding search numbers, you can make sure that a phrase meets the minimum number of searches (set in **Event-based suggestions**) and increase the probability of suggesting the phrase by the AI model. 4. To add more phrases, click **Add phrase** and repeat step **b** and **c**. 6. Confirm the settings in the section by clicking **Apply**. 7. To add phrases that will never appear as suggestions, in the **Denylist** section, click **Define**. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> While testing suggestions in the **Preview** tab, you can add them to the deny list as well. </div></div></div> 1. To add the first phrase, click **Add phrases**. **Result**: A pop-up appears. 2. In the **Phrase** text field, enter the phrase. 3. From the **Matching type**, select the type of the phrase: - **Phrase** - the suggestion must match the whole pattern exactly. - **Full word** - any word of the suggestion must exactly match the pattern. - **Partial word** - any word of the suggestion must partially match the pattern. - **Regular expression** - the pattern is treated as a regular expression and must match the suggestion. 4. To add more phrases, click **Add phrase** and repeat step **b** and **c**. 6. Confirm the settings in the section by clicking **Apply**. 8. To activate the suggestions, click **Save**. ## Previewing suggestions --- The preview section enables you to test suggestions by entering a word in the search box and observing the displayed suggestions as you type your query. In this section, you will see a list of suggestions sorted by their relevance scores, with the highest scores shown first. You can review the score (a numerical value indicating the suggestion's relevance, maximum is 100) of a suggestion, identify the suggestion type, and optionally add the suggestion to the deny list. 1. Under the suggestion name, select the **Preview** tab. 2. In the search box, enter a phrase. **Result**: A dropdown list appears with the suggestions for the phrase. 3. If you want to prevent suggesting a result, click **Add to deny list**. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/suggestion-preview.png" alt="Preview of suggestions for a searched phrase" class="full"><figcaption> Preview of suggestions for a searched phrase </figcaption></figure> # Query suggestion statistics Suggestions indices are created to enhance the user search experience by providing real-time, relevant queries or query completions that guide users toward successful search results more efficiently. The main purpose of Suggestions Analytics is to enable detailed monitoring of user interaction with query suggestions, allowing teams to evaluate their effectiveness, optimize relevance, and uncover customer intent patterns. ## Requirements --- Your workspace needs the following events to be able to produce statistics results: - [`suggestion.search`](/docs/assets/events/event-reference/search#suggestionsearch) - [`suggestion.search.click`](/docs/assets/events/event-reference/search#suggestionsearchclick) ## KPI --- This section is dedicated to key performance indicators (KPI) for suggestions. You can preview the following metrics. | Metric | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------| | CTR (Click Through Rate) | The ratio of the number of clicks on query suggestions to all searches. | | Avg. click position | The average placement of a suggested item in a list of search results. Higher numbers mean lower positions. | | No results rate | The ratio of the number of search requests that returned no results to the total number of search queries. | ## Total --- You can compare the KPI results against the overall outcomes generated by your search. | Metric | Description | |-------------|--------------------------------------------------------| | Searches | The number of search queries. | | Clicks | The number of clicks on the search results. | | No results | The number of search queries with no results and no suggestions. | ## Top clicked suggestions --- The Top clicked suggestions section displays only the top 1,000 search suggestions that have the highest search volume, helping you understand user intent and optimize suggestions for better engagement. | Metric | Description | |--------------------|----------------------------------------------------------------------------------------------------------------------------------| | Searches | The number of search queries. | | Clicks | The number of clicks on the search results. | | Avg. click position | The average placement of a suggested item on a list of search results, indicated by ordinal ranking; higher numbers mean lower positions. | # AI Hub The AI Hub is your go-to place for using Synerise’s smart AI tools to improve customer experience and grow your business. In this section, you’ll find instructions for five key features: AI Recommendations, AI Search, AI Prediction, Promotions, and Personalized Promotions. With AI Search, customers find what they want faster through smart, real-time search suggestions and personalized results. AI Prediction helps you understand customer behavior without any coding, so you can predict actions like buying, leaving, or engaging. AI Recommendations show customers relevant product suggestions on your site, emails, and apps. Promotions let you create loyalty programs and reward your customers. Personalized Promotions use AI to offer special deals made just for each customer. Use this AI Hub to learn how to set up and get the most out of these powerful features with ease. ## Required user permissions See [AI Hub permissions](/docs/settings/identity-access-management/permissions/ai-hub-permissions) ## Contents # Managing promotions You can perform operations on existing promotions. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/promotions-list.png" alt="A fragment of the promotion list" class="full"><figcaption>A fragment of the promotion list</figcaption></figure> ## Editing promotions --- <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> - If you edit a promotion that is already in progress, the new data **does not** apply to customers who activated the promotion before your changes. - If you click **Finish later** while working on a published promotion, it returns to draft status. </div></div></div> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. On the list of promotions, find a promotion and click its name. 3. Edit the settings in the same way as when [creating a promotion](/docs/ai-hub/promotions/creating-promotions). ## Importing promotions --- See [Importing promotions](/docs/assets/imports/importing-promotions). ## Publishing promotions --- When you click the **Finish later** button while creating a promotion, the promotion becomes an unpublished draft. To let your customers activate the promotion, it must be published. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. On the list of promotions, find the promotion and click its name. 3. Ensure that the settings are correct. 4. In the upper-right corner of the screen, click **Publish**. **Result:** If the schedule was set to "Immediately", the promotion becomes visible after you click **Publish**. If it was scheduled for a date, it becomes visible at that date. ## Hiding promotions --- After a promotion is published, you can hide it from customer view without returning it to draft status. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. On the list of promotions, locate the promotion you want to hide. 3. Hover your mouse over the "Published" status icon. The icon becomes the **Hide promotion** button. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/promotions/_gfx/hide-promo-button.gif" alt="Enabling the Hide Promotion button" class="large"><figcaption>Enabling the <strong>Hide promotion</strong> button</figcaption></figure> 4. Click the **Hide promotion** button. **Result:** The promotion becomes invisible to the customers. ## Duplicating promotions --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. On the list of promotions, find the promotion and click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/meatball-menu-icon.png" alt="Three dots icon" class="icon">. 3. In the list that opens, click **Duplicate**. **Result:** An exact duplicate of the promotion is created. It has the same name as the original promotion. The code is generated automatically and unique. ## Filtering promotions --- You can use the following filter types: - Main filter - This filter lets you use all promotion attributes to build conditions for: - Finding a particular promotion or group of promotions on the list of promotions. - Saving the filter for reuse in the configuration of [personalized promotions](/docs/ai-hub/personalized-promotions/creating-ai-promotions). The filtered promotions will be used as content for personalized promotions. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/promotion-main-filter.png" class="medium" alt="Quick filters on the list of promotions on the left side of the screen"><figcaption>Quick filters on the list of promotions on the left side of the screen</figcaption></figure> - Quick filter - This filter lets you narrow down the list of promotions based on their status or [promotion tags](/docs/ai-hub/promotions/promotion-tags) assigned to them. - When you select multiple tags, the promotion must have all the selected tags. - When you select a status and/or tags from the quick filter, the main filter saves these conditions. You can edit them further by adding, modifying, or removing conditions. Tag names will be converted to their corresponding UUIDs within the filter conditions. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/promotion-quick-filters.png" class="medium" alt="Quick filters on the list of promotions on the left side of the screen"><figcaption>Quick filters on the list of promotions on the left side of the screen</figcaption></figure> You can combine filters and the search box to filter the list of promotions more efficiently. ### Saving filters This section contains instructions for saving the main filter conditions. The saved filter can be selected in the configuration of [personalized promotions](/docs/ai-hub/personalized-promotions/creating-ai-promotions#defining-limits-and-order-of-discounted-items) for including a specific set of promotions. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **> Regular Promotions** 2. On the right side of the screen, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/filter-on-list.png" alt="Filter icon" class="icon"> icon. **Result**: The icon changes into **Define filter** button. 3. Click **Define filter**. **Result**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/promotions-build-filter.png" class="medium" alt="Quick filters on the list of promotions on the left side of the screen"><figcaption>Quick filters on the list of promotions on the left side of the screen</figcaption></figure> 4. To define the conditions of the filter, click **Choose filter**. 5. From the dropdown list, select a predefined promotion parameter. 6. By using operators, you can define the type of the parameter value. **Result**: A text field shows up. 7. Enter the value of the parameter. 8. To add more conditions, click **Choose filter** and repeat steps from 5-7. 9. Define the dependency between the conditions by selecting one of logical operators (`AND` or `OR`). 10. To: - save the filter, click **Save filter**. 1. Enter the name of the filter. 2. Click **Save**. - save the filter and filter out promotions on the list: 1. Enter the name of the filter. 2. Click **Save and Apply**. **Result**: The filter is available in the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/filter-folder.png" alt="Filter folder icon" class="icon"> folder - filter out the items on the list of promotions, click **Apply**. ## Deleting promotions --- <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Deleting a promotion is irreversible. </div></div></div> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions**. 2. On the list of promotions, find the promotion and click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/meatball-menu-icon.png" alt="Three dots icon" class="icon">. 3. In the list that opens, click **Delete**. **Result:** The promotion is deleted from the system. # Distributing recommendations You can add recommendations to: - emails, - web push notifications, - in-app messages, - mobile push notifications, - the website, - a mobile application ## Methods of displaying recommendations You can decide which method you want to use to display the recommendations: ### API See [Recommendations API](/developers/api/recommendations) in the Developer Guide. ### Mobile SDK See [Displaying AI recommendations with documents and screen views](/developers/mobile-sdk/displaying-recommendations/documents) in the mobile SDK documentation. ### Using recommendations in communication templates You can display recommendations by referencing the ID of the recommendation through [Jinjava tags](/developers/inserts/recommendations-v2), it's most common to [use it in templates of messages](#embedding-a-recommendation-in-templates) to your customers such as email or dynamic content (which lets you display recommendations on your website). ## Requirements --- You must [create a recommendation](/docs/ai-hub/recommendations-v2/creating-recommendation-campaign) before. ## Distributing recommendations in Experience Hub --- You can display recommendations to your customers on your website through [dynamic content](/docs/campaign/dynamiccontent). Also, you can incorporate recommendations into various types of messages such as emails, web push and mobile push notifications, in-app messages. It can be done by [embedding a recommendation inserts in the message templates](#embedding-a-recommendation-in-templates). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can read more about recommendation inserts in [Inserting recommendations](/developers/inserts/recommendations-v2). </div></div></div> ### Embedding a recommendation in templates --- This section presents how to insert a recommendation in the templates of the following content types: - dynamic content, - email, - in-app messages - mobile push notifications - web push notifications You can insert the recommendation in the following ways: - [insert a code with a recommendation into the template](#insert-recommendation-code) - [add a variable that allows users to select a recommendation](#add-a-selector-with-recommendations) from the dropdown list in a Config tab while editing the template #### Insert recommendation code 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/experience-hub-icon.svg" alt="Experience Hub icon" class="icon" > **Experience Hub** 2. Select a communication type: - Dynamic content - Email - In-app messages - Mobile Push - Web Push 2. On the left pane, select **Templates**. 3. In the upper right corner, click **New template**. 4. If you selected Mobile Push, after clicking **New template**, you must select the notification type: - **Simple push** - Appear in the notification center when the screen is locked or they are visible in the top bar when the screen is unlocked. - **Silent push** - A hidden notification that is delivered to the app on a user's device. 4. If you selected dynamic content, email, in-app message or a mobile push as a communication type, select **Code editor**. If you selected web push, you will be redirected automatically to the template editor. 3. At the top of the view, click **Inserts**. 4. Select one of the categories: **AI Cart Recommendations** (for the Cart recommendation model) or **AI Suite** (for the remaining recommendation model types). 5. Click the name of the recommendation. **Result**: You get a code of the recommendation. 6. Click **Get HTML code**. 7. If necessary, you can make changes to the HTML code. 8. Click **Copy to clipboard**. 9. Close the HTML preview of the code. 10. Paste the code into the HTML editor. **Result**: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/recommendation-distribution.png" alt="Recommendation distribution" class="full"> <figcaption> HTML code of the recommendation in an email template </figcaption> </figure> <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can incorporate the recommendation in various communication channels or documents in the same way using [Inserts](/developers/inserts/recommendations-v2). </div></div></div> #### Add a selector with recommendations To make editing simple for non-programmer users, you can create a variable in the template. It will be available in the **Config** tab as a dropdown list with all recommendations available in the workspace. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This option is not available for web push notifications. </div></div></div> 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/experience-hub-icon.svg" alt="Experience Hub icon" class="icon" > **Experience Hub** 2. Select a communication type: - Dynamic content - Email - In-app messages - Mobile Push 2. On the left pane, select **Templates**. 3. In the upper right corner, click **New template**. 4. If you selected Mobile Push, after clicking **New template**, you must select the notification type: - **Simple push** - Appear in the notification center when the screen is locked or they are visible in the top bar when the screen is unlocked. - **Silent push** - A hidden notification that is delivered to the app on a user's device. 4. Select **Code editor**. 5. Select one of the following tabs: HTML, CSS, JavaScript, JSON (available only for mobile push notification templates). 6. In the upper-right corner, click **Variable**. **Result**: On the left side, a sidebar appears. 7. In the **Identifier** field, enter the ID of the variable. The first character of the ID can't be a number. 8. From the **Type** dropdown list, select **Synerise insert select**. 9. Optionally, fill the **Label** (which is the name of the field in the configuration form) and the **Description** (which is the description of the field in the configuration form) fields. 10. From the **Insert Type** dropdown list, select **AI Recommendations**. 11. At the top of the sidebar, click **Add**. **Result**: In the **Config** tab, a selector with recommendations appears. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/add-variable-reco.png" alt="Recommendation list" class="full"> <figcaption>The list of recommendations in the Config tab </figcaption> </figure> # Performance measurement In this article, you will find instructions how to: 1. Evaluate prediction performance through business and machine learning metrics. 2. Use dashboards to measure prediction performance. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can find instructions how to prepare an example dashboard [here](/use-cases/predictions-dashboard). </div></div></div> 3. Analyze performance. ## Performance evaluation methods --- In general, you can always analyze and evaluate prediction results viewed from two angles: business and machine learning. Both of them can be evaluated using Synerise. ### Dashboards and other analytical tools What really matters is whether a certain action brings uplift to your KPIs like conversion, or CTR rates. It makes sense to always evaluate predictions against the ground truth. For example, after creating a prediction that forecasts if a certain group of customers will make a transaction in the next days: 1. Wait several days. 2. Compare the number of purchases for those customers who were labeled as `high` and `low` to a randomly selected control group. This way, you can verify that the model predicts a phenomenon correctly. #### Dashboards in communication One of other alternatives for monitoring model performance in terms of business metrics is to use in-built campaign dashboards. 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/experience-hub-icon.svg" alt="Experience Hub icon" class="icon"> **Experience Hub**. 2. Select a channel. 3. From the list, choose a communication campaign that was built for the audience based on predictions outputs. 4. Change the tab with the statistics (for instance, in case of email channel it will be called **Email campaign**). <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/analytics/_gfx/predictions-performance-dashboard.png" alt="Dashboard in an email communication" class="full"> <figcaption>Dashboard in an email communication </figcaption> </figure> #### Workflow analytics If you use prediction results in Automation Hub, you can check results such as clickthrough rate, open rate, and more, in the [automation statistics](/docs/automation/automation-activity-tracking) view. ### Machine learning and synthetic measures A statistics tab for all prediction types shows estimated prediction performance together with direct call-to-action capabilities. On the predefined statistics dashboards, you can see predicted KPIs and additional metrics. In addition to that, it is also possible to: - from the model's statistics preview, you can create segments of customers depending on the prediction results (for example, a segment with customers who are most likely to buy, churning customers, the closest lookalikes, and so on) - add your own custom dashboards to the prediction statistics You can view the statistics only of active predictions. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/prediction-preview.png" class="full" alt="Prediction preview for Propensity"><figcaption>Prediction preview for Propensity</figcaption></figure> ## Propensity preview --- 1. To preview Propensity predictions, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon">**> (AI Predictions) Models**. 2. On the left pane, select **Propensity**. 3. From the Propensity prediction list, select the active prediction you want to preview. **Result**: You are redirected to the statistics. ### Statistics explanation --- #### Model card In this part of preview, you can get the basic information about the prediction and model results. - **Model type** - The type of prediction. - **Model quality** - The quality of the prediction. It can take five values: `Very low`, `Low`, `Medium`, `High`, and `Very high`. The quality of the prediction is estimated based on the data input. To increase the model quality, you may widen the segmentation of profiles for whom you prepare a prediction or extend the range of items for which the propensity prediction is calculated. - **Precision** - It evaluates the share of positive conversions that were correctly predicted. The result can take values from 0 (lowest precision) to 1. In the case of propensity, it can be interpreted to what extent we can be sure that predicted conversions will be correct. - **AUC** - *Area under the ROC Curve* is one of the most commonly used metrics for classification problems. It calculates the area underneath the entire ROC curve and ranges between 0 (lowest ROC) and 1. However, only results higher than 0.5 are considered better than random choice. - **Recalculation frequency** - It describes how often the prediction is recalculated. This was defined in the prediction settings when the prediction was created. - **Last calculation** - It is the time since the last recalculation of the prediction. - **Total number of generated predictions** - This is the number of all `snr.propensity.score` events generated since the first calculation of the prediction. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The `snr.propensity.score` event is available on the activity list of each Profile and includes that Profile's score. You can learn more about it [here](/docs/ai-hub/predictions/propensity#results). </div></div></div> #### Audience summary In this part of the preview, you can see the basic information about the segmentation for which the prediction was made. - **Audience** - The name of the segmentation for which the prediction was made. - **Audience size** - The number of profiles in the segmentation at the moment of the latest recalculation. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you open the segmentation in Decision Hub, it is calculated every time you preview its results. Segmentations are likely to often change in size as profiles start or stop meeting their conditions. </div></div></div> - **Profiles without generated predictions** - The number of profiles for whom the `snr.propensity.score` event could not be generated (due to the lack of interactions) during the latest recalculation. #### Distribution charts In this part of the preview, you can see the distribution of the profiles according to percentile and score they received. **Score label** The score can be presented using one of the following scales (depending on the option you selected in the prediction settings): 1. Two-point scale (Low, High) 2. Five-point scale (Very low, Low, Medium, High, Very high) On the right side of the chart, you can see the summary of each score label. Each column contains the following rows: - **Audience size** - The number of profiles who received this score label. - **Audience share** - How much (as a percentage) of the whole segmentation received this label. - **Estimated conversion rate** - Estimated conversion, based on historical performance data for this segment. - **Estimated number of transactions** - Estimated number of transactions for this segment, based on historical performance data. - **Gain** - Percentage of the target covered in each score label. - **Lift** - The gain percentage to the random percentage at a given score label level. #### Percentile On the right side of the chart, you can see the distribution of profiles in terms of percentiles. For each percentile range, you can check the following statistics: - **Estimated conversion rate** - Estimated conversion, based on historical performance data for this segment. - **Estimated no. of transactions** - Estimated number of transactions for this segment, based on historical performance data. - **Gain** - Expected number of positive responses (conversions) for a segment to overall expected number of positive responses (conversions). **Example**: 50% of Gain for a specific score label or a decile. Let’s assume you want to contact TOP 20% customers with the highest score, and Gain for this segment equals 50%. It would mean that 50% of overall expected positive responses (conversions) are expected to be realized just from contacting TOP 20% of customers. - **Lift** - Expected ratio of positive responses (conversion rate) for a segment to expected ratio of positive responses (conversion rate) for randomly picked customers. **Example**: Lift for a specific score or a decile equals 2,5x. It means that a conversion likelihood by contacting these customers is 2,5 times higher than by contacting a randomly picked group. ## Best Fit preview 1. To preview best fit predictions, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon">**> (AI Predictions) Models**. 2. On the left pane, select **Best Fit**. 3. From the best fit prediction list, select the active prediction you want to preview. **Result**: You are redirected to the statistics. ### Statistics explanation --- #### Model card In this part of preview, you can get the basic information about the prediction and model results. - **Model type** - The type of prediction. - **Model quality** - The quality of the prediction. It can take five values: `Very low`, `Low`, `Medium`, `High`, and `Very high`. The quality of the prediction is estimated based on the data input. To increase the model quality, you may widen the segmentation of profiles for whom you prepare a prediction or extend the range of items for which the propensity prediction is calculated. - **NDCG** - (Normalized Discounted Cumulative Gain) It evaluates how well items or attributes values are ordered, considering both relevance and position. Higher scores (0-1) indicate better rankings, with more relevant items placed higher in the list. - **HitRate@1** - A metric measuring the accuracy of top predictions. It indicates the proportion of times the single highest-ranked item or attribute value is relevant or chosen by the profile. Values range from 0 to 1, with higher scores indicating better performance. NDCG and HitRate@1 metrics are measured on the test dataset. - **Recalculation frequency** - It describes how often the prediction is recalculated. This was defined in the prediction settings when the prediction was created. - **Last calculation** - It is the time since the last recalculation of the prediction. - **Total number of generated predictions** - This is the number of all `snr.bestfit.score` events generated since the first calculation of the prediction. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The `snr.bestfit.score` event is available on the activity list of each Profile and includes that Profile's score. You can learn more about it [here](/docs/ai-hub/predictions/bestfit#results). </div></div></div> #### Audience summary In this part of the preview, you can see the basic information about the segmentation for which the prediction was made. - **Analyzed profiles** - The name of the segmentation for which the prediction was made. - **Profiles** - The number of profiles in the segmentation at the moment of the latest recalculation. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you open the segmentation in Decision Hub, it is calculated every time you preview its results. Segmentations are likely to often change in size as profiles start or stop meeting their conditions. </div></div></div> - **Profiles without generated predictions** - The number of profiles for whom the `snr.bestfit.score` event could not be generated (due to the lack of interactions) during the latest recalculation. #### Distribution charts In this part of the preview, you can see the distribution of the profiles according to percentile and score they received. #### Attribute values - **Attribute value** - This is the value of an item attribute which is most likely to be purchased by a group of profiles (the exact number of profiles in this group is available in the **Profiles** column). You choose which item attribute is analyzed by the model in the prediction settings. - **Estimated conversion rate** - This is the ratio of a number of transactions with a given product/products to product page views with a given product/products within 24 hours since viewing a product page; it is calculated for all profiles in the analyzed segmentation. - **Engagement rate** - The ratio of profiles who viewed a given product or products in the last 30 days to all profiles from the analyzed segmentation. - **Profiles** - The number of profiles who are assigned a given item attribute value. ## Lookalikes preview 1. To preview Lookalikes predictions, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon">**> (AI Predictions) Models**. 2. On the left pane, select **Lookalikes**. 3. From the Lookalikes prediction list, select the active prediction you want to preview. **Result**: You are redirected to the statistics. ### Statistics explanation --- #### Model card In this part of preview, you can get the basic information about the prediction and model results. - **Model type** - The type of prediction. - **Model quality** - The quality of the prediction. It can take five values: `Very low`, `Low`, `Medium`, `High`, and `Very high`. The quality of the prediction is estimated based on the data input. To increase the model quality, you may increase the number of profiles in the source segmentation, or extend the range of events in **Settings > AI Engine Configuration > Predictions**. - **Precision** - The share of positive conversions that were correctly predicted. The result can take values from 0 to 1. In the case of propensity, it can be interpreted to what extent we can be sure that predicted conversions will be correct. - **AUC** - *Area under the ROC Curve* is one of the most commonly used metrics for classification problems. It calculates the area underneath the entire ROC curve and ranges between 0 and 1. However, only results higher than 0.5 are considered better than random choice. - **Recalculation frequency** - It describes how often the prediction is recalculated. This was defined in the prediction settings when the prediction was created. - **Last calculation** - Time since the last recalculation of the prediction. - **Total number of generated predictions** - This is the number of all `snr.lookalike.score` events generated since the first calculation of the prediction. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The `snr.lookalike.score` event is available on the activity list of each Profile and includes that Profile's score. You can learn more about it [here](/docs/ai-hub/predictions/propensity#results). </div></div></div> #### Audience summary In this part of the preview, you can see the basic information about the segmentation for which the prediction was made. - **Audience** - The name of the segmentation for which the prediction was made. - **Audience size** - The number of profiles in the segmentation at the moment of the latest recalculation. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you open the segmentation in Decision Hub, it is calculated every time you preview its results. Segmentations are likely to often change in size as profiles start or stop meeting their conditions. </div></div></div> - **Profiles without generated predictions** - The number of profiles for whom the `snr.lookalike.score` event could not be generated (due to the lack of interactions) during the latest recalculation. #### Distribution charts In this part of the preview, you can see the distribution of the profiles according to percentile and score they received. **Score label** The score can be presented using one of the following scales (depending on the option you selected in the prediction settings): 1. Two-point scale (Low, High) 2. Five-point scale (Very low, Low, Medium, High, Very high) On the right side of the chart, you can see the summary of each score label. Each column contains the following rows: - **Audience size** - The number of profiles who received this score label. - **Audience share** - How much (as a percentage) of the whole segmentation received this label. - **Number of transactions (last 30 days)** - The number of transactions in the last 30 days for a group of profiles from the target segmentation who received this label. - **Historical conversion rate (last 30 days)** - The unique conversion rate from the last 30 days prior most recent calculation for a given decile. - **Average daily page visits per user** - Average number of page visits for profiles in the given decile per day. #### Percentile On the right side of the chart, you can see the distribution of profiles in terms of percentiles. For each percentile range, you can check the following statistics: - **Number of transactions (last 30 days)** - The number of transactions in the last 30 days for a group of profiles from the target segmentation who received this label. - **Historical conversion rate (last 30 days)** - The unique conversion rate from the last 30 days prior most recent calculation for a given decile. - **Average daily page visits per user** - Average number of page visits for profiles in the given decile per day. ## Custom preview 1. To preview Custom predictions, go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon">**> (AI Predictions) Models**. 2. On the left pane, select **Custom**. 3. From the Custom prediction list, select the active prediction you want to preview. **Result**: You are redirected to the statistics. ### Statistics explanation #### Model card In this part of the preview, you can get the basic information about the prediction and model results. - **Model type** - The type of prediction. - **Model quality** - The quality of the prediction. It can take five values: `Very low`, `Low`, `Medium`, `High`, and `Very high`. The quality of the prediction is estimated based on the data input. To increase the model quality, you may increase the number of profiles in the source segmentation, or extend the range of events in **Settings > AI Engine Configuration > Predictions**. - **Precision** - The share of positive conversions that were correctly predicted. The result can take values from 0 to 1. In the case of propensity, it can be interpreted to what extent we can be sure that predicted conversions will be correct. - **AUC** - *Area under the ROC Curve* is one of the most commonly used metrics for classification problems. It calculates the area underneath the entire ROC curve and ranges between 0 and 1. However, only results higher than 0.5 are considered better than random choice. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Precision and AUC are available only for the Classification model. </div></div></div> - **RMSE** - A measure of the differences between values predicted by a model and the actual values. Lower RMSE indicates better model performance, with 0 indicating a perfect fit to the data. - **R2** - Represents the percentage of the dependent variable's variance explained by the model. A higher R2 indicates better predictive accuracy - the maximum value is 1. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> RMSE and R2 are available only for the Regression model. </div></div></div> - **Recalculation frequency** - It describes how often the prediction is recalculated. This was defined in the prediction settings when the prediction was created. - **Last calculation** - Time since the last recalculation of the prediction. - **Total number of generated predictions** - This is the number of all `snr.prediction.score` events generated since the first calculation of the prediction. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The `snr.prediction.score` event is available on the activity list of each profile and includes that profile's score. You can learn more about it [here](/docs/ai-hub/predictions/custom#understanding-prediction-events). </div></div></div> #### Audience summary In this part of the preview, you can see the basic information about the segmentation for which the prediction was made. - **Audience** - The name of the segmentation for which the prediction was made. - **Audience size** - The number of profiles in the segmentation at the moment of the latest recalculation. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you open the segmentation in Decision Hub, it is calculated every time you preview its results. Segmentations are likely to often change in size as profiles start or stop meeting their conditions. </div></div></div> - **Profiles without generated predictions** - The number of profiles for whom the `snr.lookalike.score` event could not be generated (due to a lack of interactions) during the latest recalculation. #### Distribution charts In this part of the preview, you can see the distribution of the profiles according to percentile and score they received. **Score label** The score can be presented using one of the following scales (depending on the option you selected in the prediction settings): - Two-point scale (Low, High) - Five-point scale (Very low, Low, Medium, High, Very high) On the right side of the chart, you can see the summary of each score label. Each column contains the following rows: - **Profiles** - The number of profiles who received this score label. - **% of all profiles in the prediction** - How much (as a percentage) of the whole segmentation received this label. - **Lift** - Expected ratio of positive responses (conversion rate) for this segment to expected ratio of positive responses (conversion rate) for randomly picked customers. **Example**: When the lift value for a specific score or a decile equals 2.5x,it means that the conversion likelihood from contacting these customers is 2.5 times higher compared to a randomly picked group. - **Gain** - Expected number of positive responses (conversions) for this segment to overall expected number of positive responses (conversions). **Example**: Let’s assume you want to contact the top 20% customers with the highest score, and gain for this segment is 50%. It means that 50% of overall expected positive responses (conversions) are expected to be realized just from contacting these top 20% of customers. #### Percentile On the right side of the chart, you can see the distribution of profiles in terms of percentiles. For each percentile range, you can check the following statistics: - **Percentile** - Percentile is a score below which a specified percentage of customers from an analyzed group falls. For instance, the 50th percentile means that 50% of the customers have lower score than this one. - **Lift** - Expected ratio of positive responses (conversion rate) for this segment to expected ratio of positive responses (conversion rate) for randomly picked customers. **Example**: When the lift value for a specific score or a decile equals 2.5x,it means that the conversion likelihood from contacting these customers is 2.5 times higher compared to a randomly picked group. - **Gain** - Expected number of positive responses (conversions) for this segment to overall expected number of positive responses (conversions). **Example**: Let’s assume you want to contact the top 20% customers with the highest score, and gain for this segment is 50%. It means that 50% of overall expected positive responses (conversions) are expected to be realized just from contacting these top 20% of customers. ## Adding custom dashboards --- In the prediction statistics view, you can use the option that allows you to add your own dashboards, so you can maximize insights from prediction results. 6. Next to the **Overview** tab, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three-dot icon" class="icon"> icon. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/predictions-manage-dashboards.png" class="full" alt="Adding custom dashboards"><figcaption>Adding custom dashboards</figcaption></figure> 7. From the dropdown list, select **Manage dashboards**. 8. On the pop-up, in the text field, enter the name of the dashboard you want to add. 9. Confirm your choice by clicking **Add**. 10. Optionally, you can define the order of displaying dashboards by dragging and dropping them in the desired order. 11. Confirm the dashboard settings by clicking **Apply**. Additionally, you can add your own custom dashboards to the machine learning and synthetic statistics, so you can maximize insights from prediction results. 6. Next to the **Overview** tab, click the <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three-dot icon" class="icon"> icon. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/predictions-manage-dashboards.png" class="full" alt="Adding custom dashboards"><figcaption>Adding custom dashboards</figcaption></figure> 7. From the dropdown list, select **Manage dashboards**. 8. On the pop-up, in the text field, enter the name of the dashboard you want to add. 9. Confirm your choice by clicking **Add**. 10. Optionally, you can define the order of displaying dashboards by dragging and dropping them in the desired order. 11. Confirm the dashboard settings by clicking **Apply**. ## Performance analysis --- How to check whether your model is good? There is no one specific way to verify the overall quality of the prediction model, neither in machine learning nor business metrics. Nevertheless, there are standard procedures that can be helpful in determining your model efficiency. The most important thing is to always find a baseline to compare with. For example, it could be the performance of other most similar campaigns. The best way to do it is by performing an [ABx Test](/docs/automation/conditions/abx-split-node). # Managing Personalized Promotions You can perform operations on existing personalized promotions. ## Editing personalized promotions 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Personalized Promotions**. 2. In the list of personalized promotions, click the name of the personalized promotion that you want to edit. 3. Edit the settings in the same way as when [creating an AI promotion](/docs/ai-hub/personalized-promotions/creating-ai-promotions). ## Publishing personalized promotions 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Personalized Promotions**. 2. In the list of personalized promotions, click the name of the personalized promotion that you want to publish. 3. In the upper-right corner of the screen, click **Publish**. 4. In the pop-up that appears, click **Confirm**. **Result:** The AI promotions become available to the customers. The status of the personalized promotion changes to **ACTIVE**. ## Unpublishing personalized promotions 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Personalized Promotions**. 2. In the list of personalized promotions, click the name of the personalized promotion that you want to publish. 3. In the upper-right corner of the screen, click **Unpublish**. 4. In the pop-up that appears, click **Confirm**. **Result:** The AI promotions are no longer available to the customers. The status of the personalized promotion changes to **INACTIVE**. ## Duplicating personalized promotions 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Personalized Promotions**. 2. On the list of personalized promotions, find the personalized promotion that you want to duplicate and click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/campaign/_gfx/meatball-menu-icon.png" alt="Three dots icon" class="icon">. 3. In the list that opens, click **Duplicate**. **Result**: An exact duplicate of the personalized promotion is created. The name of the duplicate is `<original name> - copy` and its status is **DRAFT**. # Previewing AI Search results To evaluate search engine results or review specific outcomes for a customer, utilize the Preview feature within the AI Search Engine. Additionally, you have the option to compare results from two different indices. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-search-preview.png" alt="The Preview section of a selected index" class="large"> <figcaption> The Preview section of a selected index</figcaption> </figure> ## Requirements --- [Select the attributes for preview](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search#selecting-attributes-for-preview) in the AI engine configuration for the catalog you use for AI Search. ## Previewing search results --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. Select an index from the list. 3. Go to the **Preview** section. 2. In the search box, type any phrase to see the results you get from particular words. 3. To see the an item for a specific customer, in the upper-right corner, click **Additional setup**. **Result**: A pop-up appears. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/additional-setup-search-preview.png" alt="Pop-up that lets you select a customer for whom the search results will be generated and select a suggestion index" class="medium"><figcaption>Pop-up that lets you select a customer for whom the search results will be generated and select a suggestion index</figcaption></figure> 6. In the **Customer context** section, from the **Add customer** dropdown list, select the customer for whom the preview of search results will be generated. 7. Optionally, from the **Suggestion index** section, you can select index of suggestions which will be applied in the preview. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> [Suggestions](/docs/ai-hub/ai-search/query-suggestions) are created to enhance the user search experience by providing real-time, relevant queries or query completions that guide users toward successful search results more efficiently. </div></div></div> 8. Confirm by clicking **Apply**. ### Distinct filter At the bottom of the **Filters** panel on the left side of the preview, you can enable the **Distinct filter** toggle. When enabled, the search engine applies the [distinct attributes](/docs/ai-hub/ai-search/define-attributes#distinct-attributes) configured in the index settings to the preview results, increasing result variety or deduplicating item variants. Use this toggle to compare what the results look like with and without distinct filtering applied. If you select the `category` attribute in the **Filters** panel, additional actions are required. For more information, see [The category attribute](/docs/ai-hub/recommendations-v2/recommendation-filters#the-category-attribute). ## Previewing item details --- <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/item-details.gif" alt="A preview of item details returned in search results" class="medium"><figcaption>A preview of item details returned in search results</figcaption></figure> - You can set the preview attributes by clicking **Edit preview attributes**. By changing the preview attributes, you can control the attribute values that will appear in the preview. More information about attributes for preview is available [here](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search#selecting-attributes-for-preview). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This setting is mutual for the Recommendation preview as well as the AI Search Engine preview. </div></div></div> - **Item ranking statistics**: - **Item ranking position** - The place where an item appears in the list of search results, with 1 being the top position. - **Item score** - A numerical value that shows how well an item matches the search query, determining its relevance. - **Ranking sorting type** - The method used to order search results, such as by relevance, date, or popularity. ### Item score details tab --- This section provides an overview of how search relevance has been determined for an item. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/item-score-details.png" alt="A preview of item score details returned in search results" class="medium"><figcaption>A preview of item score details returned in search results</figcaption></figure> - **Textual relevance** - indicates how closely a user’s search term matches the text in item attributes such as the title, description, and other related fields. Higher scores are assigned to words that appear often, naturally, and meaningfully within these attributes. - **Main score factors** - you can see how each factor individually affects the score of the item shown in the search results. You can adjust the overall influence of these factors in the Ranking section of the index settings. - **Boosted attributes** - you can view the rules that caused the attribute’s score to increase, along with how much each rule boosted it. - **Dynamic re-ranker** - you can see a preview of how the [dynamic re-ranker](/docs/ai-hub/ai-search/dynamic-reranker) changed the score of the item shown in the search results. ### Searchable attributes match tab --- This section of the item preview displays the specific attributes that matched the user’s search query. It highlights the data segments recognized as *matches*, with underlined phrases indicating *synonyms*. This feature helps you understand why a particular item appeared in the search results and enhances transparency by revealing which attributes influenced the outcome. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/searchable-attributes-match.png" class="large" alt="Preview of a searched phrase"><figcaption>An example search phrase with highlighted matches and underlined synonyms</figcaption></figure> ## Comparing indices --- Comparing indices allows you to assess results they return. Before entering any search query, you can apply filters within each index. 1. Click **Compare results**. **Result**: A pop-up appears. 2. From the **Select index** dropdown list, select the index with which you want to compare the index you're previewing. 3. Confirm your choice by clicking **Apply**. **Result**: <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/compare-indices.png" alt="Comparing index 1 and index 2" class="large"> <figcaption> Comparing index 1 and index 2</figcaption> </figure> 4. In the search box, enter a query so you can compare the results produced by each index. ## Query and ranking details --- Query and ranking details extend the search preview with transparent insights into the generation of search results, including query transformations, applied rules, filters, sorting details. Its purpose is to improve satisfaction by making search results more explainable and transparent, helping you understand the mechanics of generating results. It aims to improve transparency and simplify debugging for you. Query and ranking details are available for all search methods (hybrid, keywords, semantic). ### Query details In the **Query details** section, which is available after performing a search request, you can review the modifications made to the original search phrase in a search query. Several factors contribute to these modifications: - [Rules](/docs/ai-hub/ai-search/query-rules) - [Synonyms](/docs/ai-hub/ai-search/add-synonyms) (two-way synonyms only) <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/query-details.png" class="full" alt="The query details option in the search preview"><figcaption>The query details option in the search preview</figcaption></figure> 1. **General overview** - This section provides an overview how the original search phrase has been changed due to rules, synonyms, and suggestions from the search engine, focusing specifically on numbers. - **Phrase typed by a user** - This is original search phrase entered by the user. - **Final searched phrase** - This is the final phrase for which the search request was made; it's changed as a result of applying rules, synonyms, and suggestions from the search engine. - **Query rules that have changed phrase** - This section shows how many [rules](/docs/ai-hub/ai-search/query-rules) have been applied to the original phrase. - **Used synonyms** - This section shows how many [synonyms](/docs/ai-hub/ai-search/add-synonyms) were searched and their results added to the search results. 2. **Query transformation** - This section shows a list of applied [rules](/docs/ai-hub/ai-search/query-rules) to the original searched phrase. The rules provide IF - THEN logic that lets you influence the search results. This way you can manage the behavior of the search engine by telling it to promote specific products, replace the query or a word in the query or remove a word from it in specific circumstances. - **The condition that has been met** - This column shows the rule condition met by the original query. - **Consequence** - This column shows what changes have been made to the original searched phrase. 3. **Used synonyms** - This section shows a list of applied two-way [synonyms](/docs/ai-hub/ai-search/add-synonyms) to the original searched phrase. Two-way synonyms work in two directions. For example, if “telephone”, “smartphone”, and “phablet” are two-way synonyms, searching for “smartphone” or “phablet” also shows the results for “telephone”. ### Ranking details In the ranking details section, you can check how the [rules](/docs/ai-hub/ai-search/query-rules), [sorting](/docs/ai-hub/ai-search/define-attributes#sortable-attributes) and [ranking](/docs/ai-hub/ai-search/define-item-ranking) settings have impacted the listing of search results. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ranking-details.png" class="full" alt="The ranking details option in the search preview"><figcaption>The ranking details option in the search preview</figcaption></figure> 1. General overview: - **Items found** - This section shows the total number of items that matched the query (including hidden items; an item can be hidden as a consequence of the applied [rules](/docs/ai-hub/ai-search/query-rules)). - **Hidden items** - This section shows the number of all items that are hidden as a result of the rules applied to the searched phrase. - **Promoted items** - This section shows the number of items promoted as a result of the rules applied to the searched phrase. - **Ranking sorting type** - This section shows the method of sorting search results. This value is definable in [Sortable attributes](/docs/ai-hub/ai-search/define-attributes#sortable-attributes) of the index settings. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ranking-details-overall.png" class="full" alt="The preview of Overall details"><figcaption>The preview of Overall details</figcaption></figure> 2. **Hidden items** - This section shows a list of items (name and item ID) hidden from the results. Items can be hidden due to query rules. 3. **Search results filters** - This section shows a list of rules whose consequence is **Filter query results**. The **Conditions** column shows the conditions of the rule and the **Consequences** column shows the changes that are made to the results. 4. **Boosted attributes** - This section shows a list of rules whose consequence is **Boost by attribute**. The **Conditions** column shows the conditions of the rule and the **Consequences** column shows the changes that are made to the results. # AI Search Enhance your customers' search experience using the Synerise AI Search Engine. The blazing fast search significantly shortens your customers' path to conversion, delivering real-time full-text, autocomplete or [query suggestion](/docs/ai-hub/ai-search/query-suggestions) results from the first keystroke. You can also use listing to make a personalized search request without a query phrase. Our [complete API](https://hub.synerise.com/api-reference/ai-search) facilitates quick and seamless integration into websites and mobile applications, capable of delivering several millions of personalized results daily in milliseconds. With the added power of hybrid search mode, users benefit from the combined strengths of keyword and **semantic search**, ensuring the most comprehensive and accurate results possible. All of this has been build on the top of the existing cutting edge recommendation engine allowing **personalization of search results** taking into account customers behavioral history. The integrated [A/B testing](/docs/ai-hub/ai-search/configuring-ab-test) and preview capabilities allow businesses to fine-tune their search configurations for optimal performance. Additionally, our search engine offers flexible business logic options. You can apply query rules to filter or **promote results** and use boosting to **reflect item popularity** or **highlight key attributes**. On top of that, [visual search](/docs/ai-hub/ai-search/visual-search) allows customers to find products using images or links, identifying visually similar items effortlessly. Before you publish your search configuration you can [preview search results](/docs/ai-hub/ai-search/previewing-search-engine-results) on the well-designed GUI to ensure optimal setup for your application or website. # Metadata catalog The metadata catalog is used to enrich the standard item feed or catalog for [Section page](/docs/ai-hub/recommendations-v2/recommendation-types#section-page) and [Attribute](/docs/ai-hub/recommendations-v2/recommendation-types#attribute) recommendation types. This catalog must contain the `itemId` column, which is the unique value of the attribute. For example, in a catalog that stores categories (category is an attribute), the values in the `itemId` may include "Hoodie", "Longsleeve", "T-shirt", and so on; you can then recommend those categories with an attribute recommendation campaign. Typically, the catalog contains at least an image that is used as the recommendation tile and the URL of the recommended attribute or category. It can also store data such as descriptions of the attribute ("This category includes the comfiest hoodies"), an alternative title that you want to show in the recommendation ("Comfy hoodies"), and any other data that your implementation requires. This catalog is usually uploaded as a CSV file. ## Metadata for attribute recommendations Attribute recommendations do not recommend items from the feed or catalog. Instead, they recommend attribute values. When you recommend attribute values, the catalog must contain at least the itemId (the attribute value) and an image link. ## Metadata for section recommendations Section page recommendations recommend both attribute values and items within those values. The metadata catalog enriches the sections that correspond to attribute values (for example brands or categories). <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> You can read [Personalization of the main banner on the homepage](/use-cases/banner-personalization-on-homepage) use case to see how metadata catalog is used for creating attribute and section page recommendations in a real-life example. </div></div></div> ### Example An attribute recommendation is used to recommend categories. Each category value (for example, "Hoodies") in the recommendation frame should be displayed with an image that illustrates it. The link to the image (such as a hoodie for the "Hoodie" category) must be provided in the metadata catalog so it can be shown in the recommendation. You can then use that image in the recommendation frame as a tile that links to the "Hoodie" category page. In the recommendation response, this is what a single recommended category could look like: <pre><code class="language-LANG">{ "itemId": "Hoodies", "image": "/yourcdn.com/hoodie.png" "link": "/yourstore?category=hoodies" ...// additional data from the metadata catalog, if you added some },</code></pre> ### Example An attribute recommendation is used to recommend brands: BRAND1, BRAND2, BRAND3. Each brand needs an image which represents it, and a link to that image is stored in the metadata catalog, where the brand name is the `itemId`. When you make a recommendation request and all three brands are recommended, the returned data will be similar to this: <pre><code class="language-json">{ "data": [ { "itemId": "BRAND1", "link": "/yourstore?brand=brand1", "image": "/yourcdn.com/brand1.png" ...// additional data from the metadata catalog, if you added some }, { "itemId": "BRAND2", "link": "/yourstore?brand=brand2", "image": "/yourcdn.com/brand2.png" ...// additional data from the metadata catalog, if you added some }, { "itemId": "BRAND3", "link": "/yourstore?brand=brand3", "image": "/yourcdn.com/brand3.png" ...// additional data from the metadata catalog, if you added some } ] }</code></pre> # AI Search Engine statistics The statistics module of the AI search engine allows you to break down the search results of the customers into data categories such as filter usage, popular searches, and so on. It also gives you an insight into the words and phrases the customers use. This article explains the way the statistics are counted. <div class="youtube-embed youtube-facade not-prose" data-youtube-id="aPQZU4BFgao" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to check Search Statistics?"><img src="https://img.youtube.com/vi/aPQZU4BFgao/hq720.jpg" alt="Synerise Academy - AI Search - How to check Search Statistics?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div> ## Benefits --- - You receive an idea about how product data should be structured. - You can get to know how to configure ranking and relevance. - You can check whether your products are properly described or represented. - It helps you to keep the number of products balanced (to avoid having too much or too less of some products). ## Requirements --- The table below shows events which must be sent to Synerise in order to make specific statistics work. The `item.search` events are generated automatically when search results are sent back from Synerise and they are used by all models. <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> In order to make the search statistics work properly and the results to be personalized, you have to send the customer's UUID with the search request. </div></div></div> | Event name: | `item.search.click` | `transaction.charge` | |-----------------------|---------------------------------------------|---------------------------------------------| | CTR | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | Conversion | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | Conversion rate | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | Revenue | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | Avg. click position | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | Avg. order value | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | | Searches | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | Clicks | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/check-s.svg" class="icon" alt="Green checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | Suggestions used | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | No results | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | | Most popular searches | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/close-s.svg" class="icon" alt= "Red checkmark"> | ## Statistics --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. Select an index from the list. 3. Select the **Statistics** tab. 4. From the **Search type** dropdown list, select the type of search which you want to see the statistics. You can select: - **All** - **Autocomplete** - **Full-text** - **Listing** <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> When setting up Synerise AI Search, you can use different endpoints. Each endpoint allows you to implement AI search in a different way: - With autocomplete, you can make requests while the user is typing. - With full-text, make the request when the user presses ENTER. - With listing, you can can make a search without a query phrase. You can find more information in the ["Implementation"](/docs/ai-hub/ai-search/introduction-to-ai-search#implementation) section of [Introduction to AI Search](/docs/ai-hub/ai-search/introduction-to-ai-search). </div></div></div> 5. By clicking the calendar icon, you can select the period from which you want to preview the statistics. ### Global --- By selecting **Global** in the **Statistics** tab, you can check general search statistics for the selected index. The interface displays metrics for a specific time period. The table below shows the description of the metrics. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/aisearchstats1.png" alt="Global statistics" class="full"> <figcaption> Global statistics </figcaption> </figure> | Metric name | Description | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CTR | (Click Through Rate) It is the ratio of the number of clicks in search results to all searches. | | Conversion Rate | It represents the ratio of the number of conversions to the total number of clicks on search results. | | Avg. Click Position | It is the average placement of a clicked item on a list of search results. This position is indicated by ordinal ranking, with the higher numbers representing lower positions in the search results. This metric is calculated by dividing the number of all positions to the number of all clicks on search results. | | Avg. Order Value | It is the average amount spent by customers on a single transaction. A higher value indicates that customers are making larger purchases per transaction. This metric is calculated by dividing the value of all transactions by the number of conversions. | | No Results rate | It is the ratio of number of search requests that returned no results to the number of all search queries. | | Average Revenue | It is the ratio of conversions to the number of customers using the search. | | Searches | It is the number of search queries. | | Clicks | It is the number of clicks on the search results. | | Suggestions Used | When a customer sends a search query that doesn't produce any results, an internal request for suggestions is made before showing the results.<br>This is the number of such requests. | | No Results | It is the number of search queries with no results and no suggestions. | | Conversions | It is the effectiveness indicator that shows how many times a unique product was bought after clicking it in the search results. A purchased item is bound to the search click event when the item is purchased in 5 or fewer days since clicking the search result. | | Revenue | It is the value of all transactions made after clicking the product in the search results. | ### Popular --- To view popular query statistics, choose the **Popular** option in the **Statistics** tab. You'll see a list of the most commonly used queries and how often they're used. The numbers in the columns represent the total for each metric during the chosen period. To see the metrics for each day, click the arrow on the left. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/aisearchstats2.png" alt="Popular searches" class="full"> <figcaption> Popular searches </figcaption> </figure> | Metric name | Description | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Clicks | It is the number of clicks on the query. | | CTR | (Click Through Rate) It is the ratio of the number of clicks in search results to all searches for this query. | | Conversion Rate | It represents the ratio of the number of conversions* to the total number of clicks on search results for this query. | | Revenue | It is the value of all transactions made after clicking the results of the query. | `*`Conversions- It is the effectiveness indicator that shows how many times a unique product was bought after clicking it in the search results. An item is counted as purchased if the time between clicking on the search result and completing the transaction is 5 days or fewer. ### No results --- By selecting **No results** in the **Statistics** tab, you can check the results on how many times a search query didn't find any results, with or without the visitor to the website applying search filters available on the interface. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/aisearchstats3.png" alt="No result searches" class="full"> <figcaption> No result searches </figcaption> </figure> 1. **Query** - This column contains the list of all popular queries searched in the chosen period that returned no results. 2. **Count** - This column shows the number of times a particular phrase was searched. ### Filters --- By selecting **Filters** in the **Statistics** tab, you can check how many times a particular item attribute and its value were used in the filters. Details for each attribute are accessible by clicking the arrow beside the item attribute name. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/aisearchstats4.png" alt="Filters" class="full"> <figcaption> Filters </figcaption> </figure> # AI Predictions # Regular Promotions Promotions allows you to introduce a system of awarding and spending loyalty points so your customers can use them and purchase your products. A great advantage of this tool is its flexibility - you can adjust all the options in a promotion according to your needs. ## Requirements --- - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise. - Import a list of stores to [Catalogs](/docs/assets/catalogs). # Personalized promotions The AI engine lets you generate highly-personalized sets of promotions for individual customers. ## Benefits - Promotions that match a customer's individual preferences - Improved customer loyalty and satisfaction - Increased revenue ## Requirements - Import a [product feed](/use-cases/import-product-feed-to-catalog) into Synerise. - Create handbill-type [promotions](/docs/ai-hub/promotions/creating-promotions). - Your transaction data history must be at least three months long. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The precision of the AI engine depends on the amount of transactional data it can learn from. The longer the history you have available, the better. </div></div></div> # Define language and separators In this section of the index settings, you can: - select the language of the search engine. - define how words are separated. - select the logical operator among multiple [query rules](/docs/ai-hub/ai-search/query-rules) which contain [Elastic and Static Filter](/docs/ai-hub/ai-search/query-rules#filters) in their consequences. <figure> <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-search-settings.png" class="full" alt="The configuration of settings in AI Search"> <figcaption>The configuration of settings in AI Search</figcaption> </figure> ## Configuration --- 1. Go to **AI Hub > Indexes**. 2. [Create](/docs/ai-hub/ai-search/create-index) or select the index on the list. 3. Go to the **Settings** tab. 4. On the **Settings** section, click **Define**. ### Selecting language --- To select the language of the search engine, go to **AI Hub > Indexes**. [Create](/docs/ai-hub/ai-search/create-index) an index or select an existing one from the list. Go to the **Settings** tab. In the **Settings** section, click **Define**. 1. From the dropdown list, select a language. 2. If you want to display unavailable items in the search results, enable the **Include out of stock items** option. ### Defining separators --- This option lets you define how words are separated in your attributes. The attribute values are divided into single searchable words (tokens). - The default separator is a space. - You can change to the **Standard characters** separator type. The full list of separators is available at [UAX #29: Unicode Text Segmentation](https://unicode.org/reports/tr29/). - You can also specify custom separators by adding them as [Java Regular Expressions](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html). All characters specified will be used as separators. #### Example If you want to divide attribute values into words (tokens) based on whitespace characters and the following three characters `. ,` and `/`, enter the following pattern in the **Custom separator** input field: ```regex [\s.,\/]+ ``` ### Defining dependency among filters in multiple query rules --- When two or more query rule conditions are met and their consequences include [filters](/docs/ai-hub/ai-search/query-rules#filters), you can choose the logical operator to combine those filters. - For static filters, select either **AND** or **OR** in the **Standard filters** section. - For elastic filters, select either **AND** or **OR** in the **Elastic filters** section. This flexibility lets you to tune how multiple filters in many query rules interact, enabling more precise targeting and improved control over the resulting data. # Dynamic re-ranker Search results can change quickly, because some meanings of a word can become more popular than others. To keep up with these changes, you can use a dynamic re-ranker. This tool **changes search rankings to match current trends automatically**, which is more convenient than manually changing search rules. This approach is more **scalable as it can handle a lot of changes**. The search engine learns from what people have been clicking on in the last 30 days, and then uses this information to make popular things show up higher in search results. For example, if users click nail polish results more often than nail remover when they search for `nail`, the nail polish will be shown higher in the results. Search rankings **get updated every 12 hours** to keep up with what users are looking for. This means you get search results that fit what users need, which can lead to more users taking action based on what they find. All of this happens without the need to make manual rules or add more filters to change how relevant the results are. ### Impact on relevance In the ["About search engine" section](/docs/ai-hub/ai-search/introduction-to-ai-search#about-search-engine) you can check at what stage of search engine operations re-ranker is applied if enabled. ## Requirements --- This feature can be enabled only if: - at least 100,000 [item.search.click events](/docs/assets/events/event-reference/search#itemsearchclick) are generated for [an index](/docs/ai-hub/ai-search/create-index); - `item.search.click` events must contain `itemId` which is an ID of the clicked item. Must be the same as the item's itemId in the item feed and sku in transaction events. ## Enabling dynamic re-ranker --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. From the list of indexes, click the one to which you want to apply the dynamic re-ranker. **Result**: The index statistics opens. 3. Select the **Settings** tab. 4. On the **Dynamic Re-reranker** section, click **Define**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/dynamic-reranker-default-state.png" class="large" alt="Default state of the dynamic re-ranker feature"><figcaption>Default state of the dynamic re-ranker feature</figcaption></figure> 5. Switch the toggle on. You can enable the dynamic re-ranker only if your index meets the [requirements](#requirements). ### Filtering items This step is optional. The engine prepares the ranking of promoted items every 12 hours. You can narrow down the scope of promoted items by applying filters. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/dynamic-reranker-enabled.png" class="large" alt="Dynamic re-ranker enabled"><figcaption>Dynamic re-ranker enabled</figcaption></figure> 2. Optionally, from the **Item filter** dropdown list, you can restrict promoted items in search results by selecting the item attributes. **Result**: A pop-up opens. 1. From the **Select value** dropdown list, select an item attribute. 2. From the **Operator** dropdown list, select a logical operator. You can find more information on Operators in the ["Describing conditions by operators" section](/docs/ai-hub/recommendations-v2/recommendation-filters#describing-conditions-by-operators). 3. From the **Select value** dropdown list, choose a value of the item attribute. This filter lets you only select [a value from the list](/docs/ai-hub/recommendations-v2/recommendation-filters#value-from-the-list) or [an array](/docs/ai-hub/recommendations-v2/recommendation-filters#array) , you can find more information in ["Defining the values of operators "](/docs/ai-hub/recommendations-v2/recommendation-filters#defining-the-values-of-operators). 4. To add more requirements to a condition, click **and where** and repeat steps a-c. 4. To add more conditions, click **Add filter** and repeat steps a-d. Then, you must define the condition chaining (AND/OR). <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/condition-chaining.png" class="medium" alt="Condition chaining"><figcaption>Condition chaining</figcaption></figure> 5. If you want to change the conditions from including to excluding items, click the **Matching** word in "Matching these conditions". <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/matching-not-matching.gif" class="full" alt="Enabling and disabling condition matching"><figcaption>Enabling and disabling condition matching</figcaption></figure> ### Selecting number of promoted items --- In this part of the process, define how many items in the search results will be promoted by the dynamic re-ranker. 1. In the **Number of items** field, select the number of items which will be promoted in the search results. You can promote maximum 50 items. 2. Confirm the settings in this section by clicking **Apply**. # Automatic Facets Facets let customers narrow down search results to items with common features, such as color or brand, and show how many items match each value. Unlike [filterable attributes](/docs/ai-hub/ai-search/define-attributes#filterable-attributes), facets do not simply include or exclude items — they expose attribute distributions alongside the results. Automatic Facets does not replace the [Facetable attributes](/docs/ai-hub/ai-search/define-attributes#facetable-attributes) configuration. It selects which of those pre-configured attributes to surface for each query. You must configure facetable attributes first, the algorithm draws exclusively from that pool. ## Prerequisites --- - An [AI Search index](/docs/ai-hub/ai-search/create-index) must already exist in your workspace. - The facetable attributes you want the algorithm to draw from must be configured in the **Facetable attributes** setting of the same index. For applicable limits, see [AI Search limits](/docs/ai-hub/ai-search/introduction-to-ai-search#limits). <div class="admonition admonition-warning"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The sum of distinct attribute values for filterable and facetable attributes combined cannot exceed the index limit. Attributes with many distinct values reduce the capacity available for other attributes. For details, see [Facetable attributes](/docs/ai-hub/ai-search/define-attributes#facetable-attributes). </div></div></div> ## Configuring Automatic Facets --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > AI Search > Indexes**. 2. Click the name of the index you want to configure. **Result**: The index detail page opens. 3. Click the **Settings** tab. 4. Scroll to the **Automatic Facets** section and click **Define**. **Result**: The Automatic Facets configuration panel expands. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/automatic-facets-disabled.png" class="medium" alt="Disabled Automatic Facets"><figcaption>Disabled Automatic Facets</figcaption></figure> 5. Toggle **Enabled** to turn the feature on or off. **Result**: <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/automatic-facets-enabled.png" class="medium" alt="Enabled Automatic Facets"><figcaption>Enabled Automatic Facets</figcaption></figure> 6. Under **Minimum coverage threshold**, drag the **Coverage threshold** slider to set the minimum percentage of results that must include an attribute before the facet is shown. The range is `1%` to `100%`. 7. From the **Objective** dropdown, select the goal the algorithm optimizes for when selecting facets: - **Coverage** — selects facets that appear across the widest share of results. - **Popularity** — selects facets based on how often customers use them to filter search results. This option is available in [private preview](/docs/log-in-and-navigate-synerise-platform#private-preview). 8. In the **Maximum number of facets** field, enter the maximum number of facets to display in the results. The maximum allowed value is `10`. 9. Click **Apply**. **Result**: The configuration is saved and the index applies the updated Automatic Facets settings. <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> To verify which facets the algorithm returns for a given query, use the search preview. See [Previewing AI Search results](/docs/ai-hub/ai-search/previewing-search-engine-results). </div></div></div> ## Automatic Facets settings explanation --- ### Enabled Activates or deactivates Automatic Facets for the index. When disabled, facets are controlled solely by the **Facetable attributes** configuration and any manual rules. ### Minimum Coverage Threshold Defines the minimum percentage of search results that must contain a given attribute before that attribute is shown as a facet. For example, a value of `20%` means a facet appears only if at least 20% of the results include that attribute. The slider range is `1%` to `100%`. Use a higher threshold to reduce the number of facets shown for broad queries. Use a lower threshold to surface more specific attributes for narrower result sets. ### Objective Defines the goal the algorithm optimizes for when selecting which facetable attributes to surface: - **Coverage** — prioritizes attributes that appear across the broadest share of results, maximizing how many items each facet can filter. - **Popularity** — prioritizes attributes that customers use most often to filter search results. <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The **Popularity** objective is available in [private preview](/docs/log-in-and-navigate-synerise-platform#private-preview) and accessible only on selected workspaces. To get access, contact your account manager or Synerise support. </div></div></div> ### Maximum Number of Facets Limits the total number of facets returned in the search results. The maximum allowed value is `10`. ### Facet Attributes The Automatic Facets algorithm selects from the attributes configured in the **Facetable attributes** setting of the index. To view or modify the attribute pool, click **Go to Facetable attributes** within the configuration panel, or navigate to the **Facetable attributes** card in the same **Settings** tab. ## Overriding Automatic Facets with rules --- You can manually control which facets are shown or hidden regardless of the algorithm's selection. Manual rules always take precedence over the Automatic Facets algorithm — a facet forced by a rule will appear even if it does not meet the coverage threshold, and a suppressed facet will not appear even if the algorithm selects it. To define manual rules, click **Go to rules** in the **Manual facet rules** section of the Automatic Facets panel. This opens the **Rules** tab. For instructions on creating rules, see [Create rules](/docs/ai-hub/ai-search/query-rules). <div class="admonition admonition-tip"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /></svg></div><div class="admonition-body"><div class="admonition-content"> Use manual facet rules when you need to guarantee that a specific facet always appears for certain queries, for example, always showing **availability** for any search. </div></div></div> # Predictive filtering Predictive filtering is a helpful tool that improves search results by showing items from the most relevant categories. This process is transparent for the end user. The AI engine determines the best item categories for your query based on past [item.search.click events](/docs/assets/events/event-reference/search#itemsearchclick). You can then make these results even more relevant by applying filters and boosting, depending on the AI's reliability level of the prognosis. For example, you can use an elastic filter to prioritize categories with high confidence levels, moving them to the top of the search results. Available filters: - **Static filter** - Only shows items from categories with the reliability level you define. - **Elastic filter** - Displays the category with a specific reliability level at the top of the search results. - **Boosting** - Increases the score of categories with the relability level you defined, affecting their position in the search results. Each search result with applied predictive filtering produces two events: - [item.search](/docs/assets/events/event-reference/search#itemsearch) - [item.search.classification](/docs/assets/events/event-reference/search#itemsearchclassification) In the ["About search engine"](/docs/ai-hub/ai-search/introduction-to-ai-search#about-search-engine) section you can check at what stage of search engine operations predictive filtering is applied if enabled. ## Requirements --- This feature can be enabled only if: - at least 100,000 [item.search.click events](/docs/assets/events/event-reference/search#itemsearchclick) are generated for [an index](/docs/ai-hub/ai-search/create-index) for the last year; - `item.search.click` events must contain `itemId` which is an ID of the clicked item. Must be the same as the item's itemId in the item feed and sku in transaction events. - the item feed must contain the [`category` attribute](/docs/ai-hub/item-feed/item-feed-in-catalog#category-attribute) - the `category` attribute is selected as one of the facetable attributes while [creating an index](/docs/ai-hub/ai-search/create-index) ## Enabling predictive filtering --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. From the list of indexes, click the one to which you want to apply the predictive filtering. **Result**: The index statistics opens. 3. Select the **Settings** tab. 4. On the **Predictive filtering** section, click **Define**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/predictive-filtering-default-state.png" class="large" alt="Default state of the predictive filtering feature"><figcaption>Default state of the predictive filtering feature</figcaption></figure> 5. Switch the toggle on. You can enable predictive filtering only if your index meets the [requirements](#requirements). ## Enabling filters and boosting --- You can define which filters will be applied when a predicted category reaches specific reliability level. You can apply the following filters: - **Static filter** - Only shows items from categories with the reliability level you define. - **Elastic filter** - Displays the category with a specific reliability level at the top of the search results. - **Boosting** - Increases the score of categories with the reliability level you defined, affecting their position in the search results. You can apply all filters at the same time. 1. To enable a filter, switch the toggle on. 2. To define the reliability level from which the filters will be applied to the predicted categories, use the slider next to the filter toggle. 3. To confirm the settings, click **Apply**. ### Example You configured the settings of the predictive filter to apply the following actions based on the reliability levels of the predicted categories: - Static filters will be applied to categories with a reliability level assessed as "certain" - Elastic filters will be applied to categories with a reliability level assessed as "very high" - Boosting will be applied to categories with a reliability level assessed as "high" <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/predictive-filter-example.png" class="medium" alt="Configuration of elastic, static filters and boosting"><figcaption>Configuration of elastic, static filters and boosting</figcaption></figure> When a user searches for an item using `XYZ` query, predictive filters will return the following results: | Category | Reliability level | |-----------------------------------------------------------------------------|-------------------| | `shoes` | certain | | `shoes > sport` | very high | | - `shoes > sport > running > women`; <br> - `shoes > sport > running > men` | high | This means that: - The search results will contain only items from the `shoes` category. - The items from the `sport` category and the `shoes` category will appear at the top of search results. - The items from the following categories will be boosted: `shoes`, `sport`, `running`, `women`, and `men`. ## Excluding phrases and categories <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/predictive-filtering-exclude.png" class="medium" alt="Excluding phrases and categories"><figcaption>Excluding phrases and categories</figcaption></figure> 1. To enable excluding phrases from predictive filtering, switch the **Exclude phrases** toggle on. 2. In the **Phrases** field, enter a phrase and confirm adding it by clicking **Add [phrase name]**. Repeat for each phrase you want to add. 3. After you completed adding phrases, on the right side of the text field, click **Add**. **Result**: A list of excluded phrases is added. 1. To enable excluding categories from predictive filtering, switch the **Exclude categories** toggle on. 2. To add categories to the list, click **Add categories**. **Result**: A pop-up with categories appears. 3. On the pop-up, you can select a root category (then categories which belong to the root categories will be selected as well) or you can expand the root category and select sub-categories. 4. Confirm your choice by clicking **Apply**. # Visual search <div class="youtube-embed youtube-facade not-prose" data-youtube-id="Tk883_T4kpA" role="button" tabindex="0" aria-label="Play Synerise Academy - AI Search - How to use Visual Search?"><img src="https://img.youtube.com/vi/Tk883_T4kpA/hq720.jpg" alt="Synerise Academy - AI Search - How to use Visual Search?" class="youtube-facade-thumb" loading="lazy" /><span class="youtube-facade-play" aria-hidden="true"><svg viewBox="0 0 68 48" width="68" height="48"><path d="M66.52 7.74c-.78-2.93-2.49-5.41-5.42-6.19C55.79.13 34 0 34 0S12.21.13 6.9 1.55c-2.93.78-4.64 3.26-5.42 6.19C.06 13.05 0 24 0 24s.06 10.95 1.48 16.26c.78 2.93 2.49 5.41 5.42 6.19C12.21 47.87 34 48 34 48s21.79-.13 27.1-1.55c2.93-.78 4.64-3.26 5.42-6.19C67.94 34.95 68 24 68 24s-.06-10.95-1.48-16.26z" fill="red"/><path d="M45 24 27 14v20" fill="white"/></svg></span></div> Visual search allows customers to find exactly what they search for by using an image instead of trying to describe the product in the right way. It significantly shortens the path to conversion and improves the customer experience. By uploading an image, or a link to an image, the customer can find visually similar items in your inventory. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> 1. The feature is additionally paid and available on request. Apart from that you will be charged for all item search events generated in response to visual search requests. 2. The following limits apply regarding number of requests for visual search: - 100 per minute - 5000 per day - 50,000 per month The search results guarantees 500 results. More is possible, but not guaranteed. </div></div></div> ## Enabling visual search --- Contact the Synerise support to enable visual search for a selected item catalog. <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> The item catalog can include up to 200 000 items and 1 000 000 images. </div></div></div> ## Endpoints dedicated to visual search --- For a list of endpoints, see the [API reference](https://hub.synerise.com/api-reference/ai-search#tag/Visual-Search). ## Image requirements --- Visual search performance is best when packshots are included in the item feed or catalog. To further enhance the performance, add more images that accurately represent the item to the item feed or catalog. To ensure good performance, it is recommended that the size of a single image is 640x480 pixels. Using smaller images may result in lower quality results. On the other hand, larger images can lead to higher latency without necessarily improving the results. ## Reindexing --- When you add or update an item, the change becomes visible in the search results after reindexing. Visual search reindexing occurs every 30 minutes to 2 hours and can't be started on demand. # Examples The list below contains example use cases concerning Predictions which you can implement in your business: - [Predict churn](/use-cases/churn-prediction) - [Predict customer lifetime value](/use-cases/ltv-prediction) - [Send email to customers with the high risk of churn](/use-cases/predictions-automation) - [Evaluate results of churn prediction](/use-cases/predictions-dashboard) - [Find customers for a new offline shop branch](/use-cases/discover-customers-for-new-shop-branch) - [Find best matching customers for an annual campaign](/use-cases/find-matching-customers-for-campaign) - [Predict propensity to buy items from specific brands](/use-cases/propensity-brand) - [Predict propensity to buy an item](/use-cases/propensity-product) - [Predict propensity to buy items with an attribute](/use-cases/propensity-attribute) # Importing promotions You can import the promotion created in external sources, so you can manage them in Synerise. The output of the import is a promotion added to the list of promotions in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions** ## Import methods Before you proceed to importing promotions to Synerise, decide on the method of import and then see [Requirements](#requirements) for the import method of your choice. - [Simple import wizard](#importing-in-simple-import-wizard) - This method allows you to upload only a `.csv` file from your device and map the columns contained in the file with the equivalent parameters in your [workspace](/docs/settings/workspace). **Recommended use**: Single import of `.csv` files. - [Automation Hub](#importing-in-automation) - This method allows you to import a file from a server or from your device. The supported file formats include: `.csv`, `.json`, `.jsonl`, and `.xml`. You will be redirected to a workflow template which you can adjust to your business assumptions. The template contains a [Data Transformation node](/docs/automation/operation/data-transformation-node) that allows you to select transformation rules if the imported data need modification before the import to Synerise to meet Synerise data standards. **Recommended use**: Imports of files stored in external servers (using HTTP and SFTP protocol), periodic imports; - Through API by using the [Create or update promotion method](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion). ## Requirements --- <details class="accordion"><summary>Click here to see Simple wizard import requirements</summary><div class="accordion-content"><ul> <li>You need <a href="/docs/settings/identity-access-management/permissions/">user permissions</a> that grant you access to Simple Imports or/and Automation Hub.</li> <li>Prepare a CSV file. It must contain the following parameters:<ul> <li>the ID of the promotion - it must be a string</li> <li>type of redemption; accepted values: `FULL`, `PARTIAL`</li> <li>the name of promotion that will be displayed on the list of promotions in Synerise UI (<img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> <strong>AI Hub > Regular Promotions</strong>)</li> <li>the name of the promotion visible to end-users</li> <li>promotion type; accepted values: `GENERAL`, `MEMBERS_ONLY`, `HANDBILL`, `CUSTOM`</li> </ul> </li> <li>The file must be smaller than 5 GB (5 000 000 000 bytes).</li> <li>In the <a href="https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion">Request body schema in the API Reference</a> you can find a complete list of promotion information you can include in the file. The left column contains the parameter names and the right column contains information about allowed values.</li> </ul></div></details> <details class="accordion"><summary>Click here to see Automation import requirements</summary><div class="accordion-content"><ul> <li>You need <a href="/docs/settings/identity-access-management/permissions/">user permissions</a> that grant you access to Simple Imports or/and Automation.</li> <li>The imported file with promotions must contain the parameters listed below. If the file uses different names or values for the required parameters, create a <a href="/docs/automation/data-transformation-and-imports/creating-data-transformation/">transformation rule</a> to align with Synerise requirements. This transformation rule will be used in Data Transformation node in the workflow which imports promotions.</li> </ul> <table> <thead> <tr> <th>Parameter</th> <th>Allowed values type</th> <th>Required parameter name</th> </tr> </thead> <tbody><tr> <td>The ID of the promotion</td> <td>any string</td> <td>`code`</td> </tr> <tr> <td>Type of redemption</td> <td>`FULL`; `PARTIAL`</td> <td>`redeemType`</td> </tr> <tr> <td>The name of the promotion displayed on the list of promotions in Synerise UI</td> <td>any string</td> <td>`headerName`</td> </tr> <tr> <td>The name of the promotion visible to end-users</td> <td>any string</td> <td>`name`</td> </tr> <tr> <td>The promotion type</td> <td>`GENERAL`; `MEMBERS_ONLY`; `HANDBILL`; `CUSTOM`</td> <td>`type`</td> </tr> </tbody></table> <ul> <li>You can add more promotion information, see the full list in the <a href="https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion">Request body schema in the API Reference</a>.</li> </ul></div></details> <details class="accordion"><summary>Click here to see requirements for importing promotions through API</summary><div class="accordion-content"><p>The requirements for importing through API are in <a href="https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion">Create or update promotion method</a> documentation.</p></div></details> ### Tips for preparing a file - We recommend importing promotions in JSON files (through [Automation Hub](#importing-in-automation)). - To include multiple values in one parameter, for example 3 colors in the `colors` parameter, do it in the following way: <pre><code class="language-json">"colors": [ "white", "green", "blue" ]</code></pre> - If you import a CSV file, these file metacharacters are recommended: - A character that marks the end of a column (delimiter): `,` - A character that is used to contain the text (quotation mark): `"` - A character (escape character) that changes the default interpretation of a sign or string followed by the escape character: `\` - To include multiple values in one column, for example, 3 colors in the `colors` column, do it in the following way: <pre><code class="language-plaintext">color.0,color.1,color.2 white,green,blue</code></pre> - For more details about parameters that can be defined for a promotion, you can check [the API Reference](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion). ## Importing in Simple import wizard --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/settings-icon.svg" alt="Settings icon" class="icon" > **Settings > Import > New import**. 2. As the data type for import, select **Promotions**. 3. As the import method, select **Import a local file**. 4. From the **Promotion parameters** column, select the Synerise counterparts for the columns from the imported file. This way, you will point which parameters in Synerise will contain the promotion information from the imported file. - If you are not sure of the purpose of a parameter from the **Promotion parameters** list, see the [Request schema body](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion), where you can find the description of all parameters from this list. - To toggle between including/excluding a parameter, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/import-column-icon.png" alt="Import column icon" class="icon" >/<img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/exclude-from-import.png" alt="Import column icon" class="icon" > icons. - During the mapping process, you can't add new columns to the imported file. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/assets/_gfx/promotion-mapping.png" class="full" alt="Mapping promotion parameters"><figcaption>Mapping promotion parameters</figcaption></figure> 5. When mapping is completed, click **Next**. **Result**: A summary of import mapping is displayed. 6. Verify the mapping summary. If it is correct, click **Run import**. **Result**: Promotions will be available on the list of promotions in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions** and the import logs will be available in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/data-modeling-hub-icon.svg" alt="Data Modeling Hub icon" class="icon"> **Data Modeling Hub > Imports**. ## Importing in Automation --- 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/settings-icon.svg" alt="Settings icon" class="icon" > **Settings > Import > New import**. 2. As the data type for import, select **Promotions**. 3. As the import method, select **Import in Automation**. 1. Select the method of delivering the file: - Local File - This option allows you to upload a file from your device. - SFTP protocol - This option allows you to fetch a file from a server using the SFTP protocol. - HTTPS protocol - This option allows you to fetch a file from a server using the HTTPS protocol. 2. Click **Go to import template**. **Result**: You are redirected to a workflow template for importing promotions. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/assets/_gfx/automation-template-import-promotions.png" class="full" alt="Workflow template for importing promotions"><figcaption>Workflow template for importing promotions</figcaption></figure> 3. Define the settings of the [Scheduled Run node](/docs/automation/triggers/scheduled-run). 4. Depending on the method of delivering the file, configure the settings of [Local File](/docs/automation/integration/http-integrations/http-get-file) or replace the node with the [Get File](/docs/automation/integration/http-integrations/http-get-file) node that uses HTTP protocol or the [Get File](/docs/automation/integration/sftp-integrations/sftp-get-file) node that uses SFTP protocol. 5. If the data requires modification, configure the settings of the [Data Transformation node](/docs/automation/operation/data-transformation-node). If you have prepared the transformation rules for the data structure of the imported file, select it from the dropdown list. If not, create it from scratch. If your data doesn't require transformation, you can remove this node. 6. The rest of the nodes in the default template don't require any further configuration. 7. If your workflow is ready, click **Save & Run**. **Result**: Promotions will be available on the list of promotions in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon"> **AI Hub > Regular Promotions** and the import logs will be available in <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/data-modeling-hub-icon.svg" alt="Data Modeling Hub icon" class="icon"> **Data Modeling Hub > Imports**. ## Importing through API --- To import promotions to Synerise through API, send a POST request to this [endpoint](https://hub.synerise.com/api-reference/loyalty-and-engagement#operation/CreateOrUpdateAPromotion). # Change index access settings By default, a search index can be managed by all [users](/docs/settings/identity-access-management/users) with the [required permissions](/docs/settings/identity-access-management/permissions/ai-hub-permissions). You can limit access per index to a selection of users or roles. ## Considerations for access settings - All users with "read" permissions to the module have at least read-only access to all indexes, regardless of per-index access settings. - The [PROFILE_ADMIN role](/docs/settings/identity-access-management/permissions#basic-roles) always has unlimited access, regardless of per-index access settings. - To edit [query rules](/docs/ai-hub/ai-search/query-rules) in an index, the **Analytics** > **Segmentations**: `read` permission is required. You must grant it separately. - If you configure different permissions for a user than for their roles, all granted permissions are combined. **For example**: 1. You grant only the "edit" permission to a user. 2. You grant only the "delete" permission to a role where this user belongs. 3. In result, the user has both "edit" and "delete" permissions. - Changing the access settings doesn't grant module permissions to users or roles. **For example**: 1. A user role only has "read" access to the AI search feature. 2. You edit the settings of an index to give "edit" permissions to that role. 3. In result, users with the role **can't** edit the index, because per-index access settings only restrict permissions - they don't grant permissions beyond what the role already has. ## Changing access settings To change the access settings: 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > Indexes**. 2. In the list of indexes, find the index you want to manage and click the padlock icon. **Result**: The access management panel opens. 3. From the **Permission in this object** dropdown list, select an option: - **Public**: everyone with the required permissions can access and manage the index. - **Read only**: everyone with module permissions can access the index, but only the creator and administrators can edit or delete it. - **Restricted**: you can manage edit and delete permissions separately for different users and roles. 4. If: - you selected **Public** or **Read only**, click **Apply** to save and start enforcing the settings. - you selected **Restricted**, proceed to [configuring the details (next step)](#restricted-config). 5. <span id="restricted-config"></span>Configure the settings for **Users** and **Roles**: 1. Expand the options and configure them: - For **Users**: 1. To add a user to the list of managed users, enter their name or email address in the search box and click their name. 2. Repeat to add more users. 3. Confirm by clicking **Add user**. 4. Use the checkboxes to set the permissions for each added user. 5. To remove a user from the list of permission settings, click <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/threedoticon.svg" alt="Three-dot icon" class="icon"> next to their name and click **Remove user**. - For **Roles**: 1. Expand the list. 2. Use the checkboxes to set the permissions for each role. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/settings/_gfx/object-permissions-roles.png" class="medium" alt="Selecting permissions for roles; an example with unsaved changes"><figcaption>Selecting permissions for roles; an example with unsaved changes</figcaption></figure> 6. To save and start enforcing the settings, click **Apply** in the lower-right corner. # Promotion tags [Tags](/docs/assets/tags) can help you organize and find promotions more easily. When you get promotions through an API (for example, from a cash register), tags let you filter the results. To use tags with promotions, you must store them in a folder or folders of the `promotion` type in **Data Modeling Hub > Tags**. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/tag-folder-type.png" class="medium" alt="In the tag folder settings, you can check the folder type; "><figcaption>In the tag folder settings you can check the folder type</figcaption></figure> To check the tag folder settings, go to **Data Modeling Hub > Tags**, on the left panel hover the mouse cursor over the tag folder and click the toolbox icon You can use tags from the `promotion` type tag folder for: - [filtering promotions](/docs/ai-hub/promotions/managing-promotions#filtering-promotions) on the promotion list - filtering promotions in API responses - [creating promotion filters](/docs/ai-hub/promotions/managing-promotions#saving-filters). # Synerise System Agent <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This feature is available in a private preview mode and accessible only on selected workspaces. To get access, contact your account manager or the Synerise support. </div></div></div> The Synerise System Agent is a conversational AI assistant built into the Synerise platform. Instead of navigating through menus and forms, you can describe what you want in plain language - get guidance on setting up a recommendation campaign, check why a search query returns no results, or ask how a metric trended last month — and the agent carries out the request or gets you most of the way there. The agent works across several product areas at once: recommendations, search, product feeds, catalogs, experiments, analytics, IQL, automation, the Synerise Help documentation, and Jinjava. You don't need to know which area of the platform owns a task - describe the outcome you want, and the agent routes the request to the right capability. ## Opening the agent <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/synerise-agent.png" class="medium" alt="Synerise Agent icon in the top navigation bar, with the chat panel open beside the workspace."><figcaption>Opening the Synerise Agent from the top navigation bar</figcaption></figure> Click **Synerise Agent** in the top navigation bar, available from anywhere in the workspace. This opens a chat panel where you can type your request. The panel stays open alongside the page you're working on, so you can keep an eye on the agent's response while you continue browsing the workspace. Each conversation keeps its context, so you can ask follow-up questions or refine a previous request without repeating details you already gave. Past conversations are listed and can be reopened at any time. ## How to talk to the agent Write requests the way you'd describe them to a colleague — there's no special syntax to learn. A few habits make the agent's answers more accurate: - **Name the object you mean** - If you know the campaign, search index, catalog, product, rule, or experiment name/ID, include it. If more than one object matches, I’ll show the options and ask you to choose. - **Include a time range for performance questions** - Phrases like “last 7 days,” “this month,” or exact dates work. If you don’t specify a range, I’ll use a sensible default and tell you what I assumed. - **Ask in steps when the task is complex** - You can refine my answer as we go, for example: “use the Personalized type instead,” “make it 12 items,” or “show that as a chart.” - **Be as specific as you can, but don’t worry if you’re unsure.** I can list resources, inspect configurations, preview results, or ask a follow-up question when something is ambiguous. ## What the agent can do | Area | You can ask it to | Learn more | |---|---|---| | [Recommendations](#recommendations) | Inspect and manage recommendation campaigns, configure the AI recommendation engine, analyze performance, and preview recommendations | [AI Recommendations](/docs/ai-hub/recommendations-v2) | | [Search](#search) | Inspect and manage indexes, analyze search behavior, tune relevance, manage synonyms and query rules | [AI Search](/docs/ai-hub/ai-search) | | [Product feed](#product-feed) | Inspect and manage item feed import configurations; look up products in item catalogs | [Item feed requirements](/docs/ai-hub/item-feed) | | [Catalogs](#catalogs) | Inspect and manage key-value data catalogs and records; export data where supported | [Introduction to catalogs](/docs/assets/catalogs/introduction-to-catalogs) | | [Experiments (A/B testing)](#experiments-ab-testing) | Inspect A/B/X tests and help prepare or manage experiment configurations for recommendations or search | [A/B/X testing](/docs/ai-hub/recommendations-v2/recommendation-abx-test) | | [Analyses](#analyses) | Create ad-hoc analyses such as reports, metrics, funnels, trends, and segmentations | [Introduction to reports](/docs/analytics/reports/introduction-to-reports) | | [IQL](#iql) | Build, validate, fix, and explain IQL filters | [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters) | | [Automation](#automation) | Draft automation workflows from a description for you to review and apply | [Introduction to Automation Hub](/docs/automation/introduction-to-automation) | | [Documentation](#documentation) | Get answers from Synerise Hub content | — | | [Jinjava](#jinjava) | Generate, validate, fix, and explain Jinjava code | [Inserts](/developers/inserts) | ## Recommendations Ask the agent to: - **Work with recommendation campaigns** — list and inspect campaigns without opening the campaign editor, and help prepare campaign changes. - **Inspect the AI recommendation engine** — check which recommendation types are available or configured for a feed, such as personalized, similar items, complementary recommendations, frequently bought together, and visual similarity. See [Recommendation types](/docs/ai-hub/recommendations-v2/recommendation-types). - **Get performance insights** — clicks, CTR, revenue, and conversions for one campaign or across all of them, including top-performing products. Results come back as a table, which you can ask the agent to turn into a trend chart. - **Preview live recommendations** — see what a campaign or recommendation type would return for a given product or customer before using it in production as described in [Previewing recommendations](/docs/ai-hub/recommendations-v2/previewing-recommendations). Example prompts: - "How is recommendation campaign X performing this month?" - "Show clicks, CTR, revenue, and conversions for recommendation campaign X from the last 30 days." - "Preview what campaign X would recommend for product 12345." - "Show personalized recommendations for customer UUID abc-123." - "Which products are most often recommended in campaign X?" ## Search Ask the agent to: - **Run searches against an index** — full-text, autocomplete, category listings, and visual image-based search. - **Inspect search indexes** — list indexes, check index state, and review searchable, filterable, facetable, and sortable attribute configuration. - **Get search analytics** — review query summaries, top queries, zero-result rates, filter usage, and rule effectiveness. - **Inspect query rules** — list and review rules that promote, hide, boost, filter, or otherwise modify results for specific queries. - **Inspect synonyms** — list and review synonym definitions configured for a search index. Example prompts: - "Search for sneakers in index X." - "Show the search query summary for index X." - "Show the zero-result rate for search index X." - "Show synonyms configured for index X." - "Check whether 'sneakers' and 'trainers' are already synonyms in index X." - "Show query rules configured for index X." - "Help me draft a rule to boost sale-tagged items for the query 'shoes'." ## Product feed Ask the agent to: - **Inspect item feeds** — check existing product import configurations for item catalogs and review available feed setup options, such as grouping or no grouping, where supported. - **Look up products** — search products in an item catalog by text or fetch them by ID. Results can be shown as visual product cards with image, title, and product details such as price when available. Example prompts: - "Look up product 12345" - "Show me products matching 'winter jacket'" - "Check the feed configuration and import status for catalog X" ## Catalogs Ask the agent to: - **Inspect catalogs** — list and inspect key-value data catalogs used to enrich events and support personalization, including catalog keys, usage, jobs, and event-enrichment mappings. See [Introduction to catalogs](/docs/assets/catalogs/introduction-to-catalogs). - **Work with catalog records** — list, count, and inspect records by ID or item key, and export catalog data as CSV where supported. Example prompts: - "List my data catalogs" - "Show the keys/columns in catalog ID 123" - "List records in catalog ID 123" - "Fetch record with item key 'gold' from catalog ID 123" - "Export catalog ID 123 to CSV" ## Experiments (A/B testing) Ask the agent to: - **Inspect A/B/X tests** — list existing experiments and review their configuration for recommendation or search tests. See [A/B/X testing](/docs/ai-hub/recommendations-v2/recommendation-abx-test) and [Configuring A/B/X tests](/docs/ai-hub/ai-search/configuring-ab-test). - **Review experiment setup and status** — check details such as variants, allocation, and lifecycle status where available. - **Support variant analysis** — help interpret experiment results when the required performance data is available. Example prompts: - "Help me plan an A/B test between two search configs" - "Review the setup of the homepage recommendation test" - "Help me interpret the variant results if I provide the metrics" ## Analyses Ask the Agent questions about your platform data in natural language. The agent can list, inspect, preview, and calculate analytics such as reports, metrics, trends, funnels, segmentations, histograms, aggregates, expressions, and sankeys, so you do not need to build every analysis manually in the interface. Example prompts: - "How many profiles bought a product from the Shoes category in the last 10 days?" - "Count transaction events daily for the last 30 days and show the result as a chart." - "Compare the purchase conversion rate last month vs. the month before, where conversion rate means purchases divided by visits." - "Compare saved funnel X for last month and the month before." - "Calculate saved conversion metric X for last month and the previous month." ## IQL You can ask the Agent to build an IQL filter from a plain-language description, validate or fix an existing filter, or explain what an existing IQL expression does. IQL is used in recommendation filters and other item-filtering contexts in the platform — see [Recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters) for recommendation-filter guidance. Example prompts: - "Build a filter for items priced under $50 that are in stock" - "What does this IQL expression do: `REQUIRED(profile.tags)`?" ## Automation Describe what you want to automate, or describe a use case, and the Agent drafts a workflow diagram for you to review and apply. See [Introduction to Automation Hub](/docs/automation/introduction-to-automation). Example prompts: - "Build a workflow that sends a discount email to customers who abandon their cart" - "I want to re-engage customers who haven't purchased in 90 days — draft a workflow for that" ## Documentation Ask questions about Synerise Help content — the User Guide and API Reference — and get answers sourced from the documentation, or ask the agent to list available use cases from [Use cases](/use-cases). Example prompts: - "What's the difference between similar and complementary recommendations?" - "How do I authenticate against the Synerise API?" - "What use cases are available for abandoned cart?" ## Jinjava Ask the Agent to generate Jinjava code — the templating language used in message templates and recommendation inserts — from a plain-language description, or to explain, validate, fix, and rewrite existing Jinjava snippets. See [Inserting recommendations](/developers/inserts/recommendations-v2). Example prompts: - "Write Jinjava code that refers to profile email attribute" - "Explain what this Jinjava snippet does" ## How the agent presents results The Agent adapts its output to the kind of question you ask: | Output | Used for | |---|---| | Chart (line, column, bar, area, pie) | Trends, comparisons, and metric visualizations, such as revenue or CTR over time | | Table | Lists of metrics, campaigns, analytics results, catalog records, or search/query results | | Product carousel | Product lookups, showing image, title, and product details such as price when available | | Guided form | Collecting structured input for setup, configuration, or multi-step tasks | | Action list | Rows of items, such as campaigns or catalogs, with available next actions | | Clickable follow-up suggestions | Related questions or next steps you can select instead of typing | ## Example scenarios | Prompt | What you get | |---|---| | "How is campaign X performing this month?" | A table of campaign performance metrics, which can be turned into a chart when suitable | | "Find sneakers in my catalog" | Product cards or a carousel, using the selected or default catalog | | "Help me draft a personalized recommendation campaign for my homepage" | Suggested campaign setup and configuration guidance | | "Preview what this campaign would recommend for product 12345" | A preview of recommended items for the selected campaign/product context | | "Help me plan an A/B test between two search configs" | Guidance for setting up the experiment manually | | "Count transaction events daily and plot the distribution over time" | A chart from the Analytics Agent, after verifying the event and time window | | "What's the difference between similar and complementary recommendations?" | An answer sourced from the documentation | ### Multi-step example: fixing a zero-result query Some requests take more than one turn, with the agent analyzing first and asking for your confirmation before any sensitive or destructive change. 1. **You ask:** "Show the search query summary for index X." The agent returns available search statistics, such as query volume and zero-result rate. 2. **You ask:** "Help me fix queries that return no results." The agent can help analyze the available data and suggest possible synonyms or query-rule changes. 3. **You review the suggestion.** If applying synonyms or query rules is not available through the agent, it gives you the proposed configuration to apply manually in Synerise. ## Related assistants The platform also includes narrower, embedded [Customer AI Assistant](/docs/ai-hub/ai-assistant) for specific surfaces. ## Things to know - The Synerise System Agent is available in Private Preview mode for selected workspaces on the Azure Europe environment, with usage limits applied. Visibility of the Agent in Private Preview can be controlled from the workspace selection panel. - The agent only knows about data and configuration that already exist in your workspace — it can't act on information it has no access to. - Always review a proposed action before confirming it, especially one that changes something live, such as pausing a campaign or removing catalog records. # Customer AI Assistant <div class="admonition admonition-important"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> This feature is available in a private preview mode and accessible only on selected workspaces. To get access, contact your account manager or the Synerise support. </div></div></div> This article explains how to configure an AI Shopping Assistant. The assistant is a conversational tool embedded in your store that lets customers describe what they are looking for in natural language and receive matching products straight away, without scrolling through long product lists. The assistant supports a range of capabilities: - **Profile context** - the assistant has access to the profile of the customer, so its responses can be personalized to that specific person. - **Conversation history** - customers can view their past conversations from up to two weeks back and pick up where they left off. - **Product page context** - the assistant is aware of the product page the customer is currently on, so it can answer contextual questions like "show me accessories that go with this product." - **Persona and tone of voice** - you can give the assistant a name, a motto, and a specific tone to match your brand identity. - **Engagement level** - you can control how inquisitive the assistant is, that is, how intensively it asks the customer follow-up questions to clarify their needs before responding. - **Recommendation models as tools** - you can connect [AI recommendation campaigns](/docs/ai-hub/recommendations-v2) to the assistant. Each campaign has its own filtering and boosting rules, which gives you control over what products the assistant shows. - **Brickworks schemas as tools** - you can attach a [Brickworks schema](/docs/assets/brickworks) as a tool. This allows the assistant to pull data from Synerise objects like [aggregates](/docs/crm/aggregates) or [expressions](/docs/crm/expressions), or from external services. - **MCP tools** - you can connect the assistant to any MCP (Model Context Protocol) server to give it access to external tools and data. - **Custom actions** - you can define a tool that returns a specific action payload during a conversation. Your frontend can then handle this action in any way you choose. ## Prerequisites 1. To configure Shopping Assistant you must be granted user permissions. 2. Upload and configure an item feed: - If you use Google Merchant feed, configure pulling it from an URL as described in [Configure AI engine for your item feed](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search). - If you want to use a Synerise catalog, through [API request](https://hub.synerise.com/api-reference/data-management#tag/Catalogs/operation/addItemsBatchAsync) or through [a workflow](/use-cases/import-product-feed-to-catalog) and then [configure the AI engine for your item feed](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search). 3. [Configure AI engine for your item feed](/docs/settings/configuration/ai-engine-configuration/engine-configuration-for-search). If you use Google Merchant Feed, in this step, you can launch pulling the feed from the URL. 4. Go to **AI Hub > AI Search** and [create an index](/docs/ai-hub/ai-search/create-index). In the configuration of the index, you must: - add the `category` attribute to facetable attributes. - set the [Matching words option](/docs/ai-hub/ai-search/define-search-method-and-ranking#matching-words) to **At least one word must match**. ## Configuration ### Creating an AI Assistant 1. Go to <img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/icons/ai-hub-icon.svg" alt="AI Hub icon" class="icon" > **AI Hub > AI Assistant > New AI Assistant**. **Result**: A configuration form with four sections displays. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/shopping-assistant-blank.png" class="medium" alt="The AI Assistant configuration form with the Brand, Assistant, Products, and Tools sections"><figcaption>The AI Assistant configuration form with four sections</figcaption></figure> ### Brand This section defines your brand identity. The assistant uses this information to understand the business context and adjust its responses accordingly. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/shopping-assistant-brand.png" class="medium" alt="The Brand section with Brand name and Business description fields"><figcaption>The Brand section</figcaption></figure> 1. In the **Brand** section, click **Define**. 2. In the **Brand name** field, enter the name of your brand or business. 3. In the **Business description** field, enter a description of your brand or business. This is used as additional context that affects the assistant's behavior. 4. Confirm the settings in this section by clicking **Apply**. ### Assistant This section defines the persona, tone of voice, and behavior of the assistant. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/shopping-assistant.png" class="medium" alt="The Assistant section with persona, tone of voice, and behavior fields"><figcaption>The Assistant section</figcaption></figure> 1. In the **Assistant** section, click **Define**. 2. In the **Persona name** field, enter the name the assistant uses to introduce itself to customers. 3. In the **Motto** field, enter a short tagline for the assistant. 4. In the **Tone of voice** field, describe how the assistant should sound in its responses, for example homely, enthusiastic, reactive, or friendly. 5. In the **Style Guide** field, enter guidelines for the assistant's communication style. 6. In the **Assistant job** field, describe the assistant's role and how it should help customers, for example recommending products or asking about their needs. 7. In the **Response words limit** field, enter the maximum length of the assistant's responses, in words. 8. Optional: Under **Suggestions**, click **Add suggestion** to add a quick prompt shown to the customer in the chat interface. You can add up to 10. 9. Confirm the settings in this section by clicking **Apply**. ### Products This section configures the product catalog the assistant uses to find and return items. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/shopping-assistant-products.png" class="medium" alt="The Products section with Search index and IQL Filter fields"><figcaption>The Products section</figcaption></figure> **Search index** Click **Select index** to choose which AI Search index the assistant will use. After selecting one, you can click **Change** to pick a different index or remove the current selection. Selecting an index unlocks the attribute mapping and filter options below. **Attribute mapping** After selecting a search index, map its attributes to the assistant's built-in product attributes so it knows which field to use for each one, for example, which field holds the price or the image link. The table has two columns: - **Source** - the fixed built-in attributes the assistant needs, for example `itemId`, `category`, `title`, `description`, `price`, `imageLink`, `link`. - **Target** - the corresponding attribute from the selected search index, chosen from the dropdown. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-assistant-mapping.png" class="large" alt="The Products section with attribute mapping"><figcaption>The Products section with attribute mapping</figcaption></figure> **IQL Filter** Click **Define filter** to add an [IQL](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query) expression that limits which products the assistant returns. This option is available only after you select a search index. ### Tools (optional) This section extends the assistant with additional capabilities. Click **Add tool** and select a type from the menu. You can add multiple tools. Each tool appears as a card with a delete and info icon. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/shopping-assistant-tools.png" class="medium" alt="The Tools section with the Add tool menu open, showing Recommendation, Brickworks schema, Custom action, and MCP Server options"><figcaption>The Tools section with the Add tool menu open</figcaption></figure> #### Recommendation Links an [AI recommendation campaign](/docs/ai-hub/recommendations-v2) to the assistant. The campaign can include its own filtering and boosting rules. 1. Click **Add tool** and select **Recommendation**. 2. In the **Tool name** field, enter a name for the tool. Maximum 100 characters. 3. In the **Instructions** field, describe when and how the assistant should use this tool. Maximum 2000 characters. 4. In the **Recommendation** field, select the recommendation campaign from the dropdown. 5. Confirm the settings in this section by clicking **Apply**. #### Brickworks schema Gives the assistant access to a [Brickworks schema](/docs/assets/brickworks). This allows it to pull data from Synerise objects like [aggregates](/docs/crm/aggregates) or [expressions](/docs/crm/expressions), or from external services. 1. Click **Add tool** and select **Brickworks schema**. 2. In the **Tool name** field, enter a name for the tool. Maximum 100 characters. 3. In the **Instructions** field, describe when and how the assistant should use this schema. Maximum 2000 characters. 4. In the **Brickworks schema** field, select the schema from the dropdown. 5. Confirm the settings in this section by clicking **Apply**. #### Custom action Returns a specific action payload during the conversation. Your frontend application can handle this action in any way you choose. 1. Click **Add tool** and select **Custom action**. 2. In the **Tool name** field, enter a name for the tool. Maximum 100 characters. 3. In the **Instructions** field, describe when and how the assistant should trigger this action. Maximum 2000 characters. 4. In the **Custom action name** field, enter the name of the action returned in the payload, which your frontend uses to identify it. Maximum 100 characters. 5. Confirm the settings in this section by clicking **Apply**. #### MCP Server Connects the assistant to an external MCP (Model Context Protocol) server so it can use external tools and data. 1. Click **Add tool** and select **MCP Server**. 2. In the **Tool name** field, enter a name for the tool. Maximum 100 characters. 3. In the **Instructions** field, describe when and how the assistant should use this MCP tool. Maximum 2000 characters. 4. In the **Connection** field, select the MCP connection from the list. This list loads the [connections](/docs/settings/tool/connections) defined in **Settings > Connections**. You can also create a new connection directly from this field: click **Select connection**, then **Add connection** in the list that appears. A connection created this way is automatically assigned to the **HTTPS** category. 5. In the **URL** field, enter the URL of the MCP server endpoint. Maximum 2000 characters. Example: `https://example.com/mcp`. 6. In the **MCP tool name** field, enter the name of the tool on the MCP server. Maximum 200 characters. 7. Confirm the settings in this section by clicking **Apply**. ### Saving your configuration In the upper-right corner, click **Save**. ### Testing the AI Assistant <div class="admonition admonition-note"><div class="admonition-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" /></svg></div><div class="admonition-body"><div class="admonition-content"> If you're creating a new assistant, the **Preview** tab appears only after you save the configuration for the first time. If you're editing an existing assistant, click **Save** in the upper-right corner again after making changes — the **Preview** tab only reflects your last saved configuration, not unsaved edits. </div></div></div> In the **Preview** tab, you can send test messages to see how the assistant responds. Check that it handles your queries correctly and adjust the configuration if needed before going live. <figure><img src="/api/docs/image/f8a57079df9dd82ae8b22dc747691385d7d51d29/docs/ai-hub/_gfx/ai-assistant-preview.png" class="medium" alt="Preview mode of the AI assistant"><figcaption>Preview mode of the AI assistant</figcaption></figure> # Item feed requirements