diff --git a/docs/content_management/block_reference.md b/docs/content_management/block_reference.md index 92dcb97b..19333ed1 100644 --- a/docs/content_management/block_reference.md +++ b/docs/content_management/block_reference.md @@ -10,18 +10,24 @@ The following blocks are provided with a clean installation of [[= product_name |Block|Description| |-----|-----------| |[Banner](#banner-block)|Displays an image content item with a URL attached to it.| +|[Bestsellers](#bestsellers-block)|Displays a list of products that were recently a bestseller.| |[Campaign](#campaign-block)|Displays a campaign selected from [[= product_name_engage =]].| |[Catalog](#catalog-block)|Displays products from a specific catalog to a selected customer group.| |[Code](#code-block)|Enables you to place content on your page, for example, text, links, or images, using custom HTML.| |[Collection](#collection-block)|Displays a set of content items you select manually from the content structure. | |[Content List](#content-list-block)|Displays content items of a chosen content type (or types) that are contained in a selected folder. | |[Content Scheduler](schedule_publishing.md#content-scheduler-block)|Displays content items at a pre-defined time. | +|[Dynamic targeting](#dynamic-targeting-block)|Embeds recommended items based on the [Segment](content_organization/classify_content.md#segments) the user belongs to. | |[Embed](#embed-block)|Embeds a content item of any content type on the page. | |[Form](#form-block)|Embeds a Form content item that you select from the content structure. | |[Gallery](#gallery-block)|Displays all images contained in a selected folder. | |[[[= product_name_connect =]]](#ibexa-connect-block)|Retrieves and displays data from an [[= product_name_connect =]] webhook. | +|[Last purchased](#last-purchased-block)|Displays a list of products that were recently purchased from PIM. | +|[Last viewed](#last-viewed-block)|Displays a list of products from PIM that were recently viewed. | |[Orders](#orders-block)|Displays a list of orders associated with a particular company or individual customer. | +|[Personalized](#personalized-block)|Displays a list of content items/products that are recommended to end users when specific scenarios are triggered. | |[Product collection](#product-collection-block)|Displays a list of specifically selected products.| +|[Recently added](#recently-added-block)|Displays a list of products that were recently added to PIM. | |[RSS](#rss-block)|Loads and displays news from RSS feeds (channels). | |[Sales representative](#sales-representative)|Loads and displays company's sales representative.| |[SeenThis!](#seenthis-block)|Displays video with exceeded standard video restrictions of 3.5MB.| @@ -29,15 +35,7 @@ The following blocks are provided with a clean installation of [[= product_name |[Text](#text-block)|Enables you to add to the page a Rich Text block. | |[Video](#video-block)|Embeds a video into the page with standard playback controls. | -Page Builder has two main views that you can use while creating a page: - -- **Page blocks** toolbox - consists of all available elements that you can use by dragging them and dropping on a drop zone. - -![Page blocks toolbox](img/page_blocks_toolbox.png) - -- **Structure view** toolbox - shows a structure of your page, including their division into zones and the blocks that they contain. - -![Structure view toolbox](img/structure_view.png) +[[= include_file('docs/content_management/create_edit_pages.md', 86, 96) =]] ## Block basics @@ -78,6 +76,18 @@ On the **Properties** tab, set values in the following fields: - **Image** — Click **Select content**, browse the available content, and choose an image for display. - **URL** — Enter a URL that opens when users click on the banner block. +## Bestsellers block + +Displays products that were recently top sellers, to help users discover popular items quickly. +On the **Properties** tab, set values in the following fields: + +- **Name** – Enter a name for the page block. +- **Personalization scenario** – Select "Bestsellers" to display popular products. +- **Product types to be displayed** – Select the type of products to be displayed on the list. +- **Limit** – Set the number of products to be displayed. + +On the **Design** tab, in the **View** field, select the layout to be used to present a list of products and submit your changes. + ## Campaign block Displays a campaign created and configured in [[[= product_name_engage =]]](../ibexa_engage/ibexa_engage.md). @@ -130,6 +140,22 @@ On the **Properties** tab, set values in the following fields: - **Limit** — Set the number of products to be displayed. - **Content types to be displayed** — Select content type(s) to be displayed. +## Dynamic targeting block + +Dynamic targeting block provides recommended items based on users related to the configured segments. + +On the **Properties** tab, set values in the following fields: + +- **Name** — Enter a name for the page block. +- **Select default scenario** — Select the default scenario for recommended items that should be rendered if the current user +is not assigned to any segment. +- **Setup segment and scenario matching priority rules** — Select a segment group, a segment identifier and Scenario that you want to display recommendations from. +- **Display limit** — Set the number of products to be displayed. + +The rules are checked in order, so when a user belongs to more than one segment, the first rule applies. + +![Dynamic targeting](img/page_builder_dynamic_targeting.png) + ## Embed block Place any content item directly on the page. This function works across all content types seamlessly. @@ -178,6 +204,28 @@ On the **Properties** tab, set values in the following fields: For more information about using [[= product_name_connect =]] scenario block, see [[[= product_name_connect =]] scenario block]([[= developer_doc =]]/content_management/pages/ibexa_connect_scenario_block/) in Developer Documentation. +## Last purchased block + +Showcases a list of recently purchased products from PIM. +Helps keep track of recent sales and improve product visibility. +On the **Properties** tab, set values in the following fields: + +- **Name** – Enter a name for the page block. +- **Personalization scenario** – Select "Last purchased" to display products that were recently purchased from PIM by any user, or "Last purchased by user" to display products that were recently purchased by the current user. +- **Product Types to be displayed** – Select the type of products to be displayed on the list. +- **Limit** – Set the number of products to be displayed. + +## Last viewed block + +Showcases a list of recently viewed products from PIM. +Helps track and show recent product interests for quick access and informed decisions. +On the **Properties** tab, set values in the following fields: + +- **Name** – Enter a name for the page block. +- **Personalization scenario** – Select "Last viewed" to display products that were recently viewed by any user, or "Last viewed by user" to display products that were recently viewed by the current user. +- **Product Types to be displayed** – Select the type of products to be displayed on the list. +- **Limit** – Set the number of products to be displayed. + ## Orders block Showcases a list of orders linked to a specific company or individual customer. @@ -190,6 +238,19 @@ On the **Properties** tab, set values in the following fields: - **Number of orders** — Set the number of orders to be displayed. - **Sort order** — Set the sort order for the displayed orders. +## Personalized block + +Showcases recommended content items or products triggered by specific scenarios for end users. +Enhances user experience by suggesting tailored options for various situations. +On the **Properties** tab, set values in the following fields: + +- **Name** – Enter a name for the page block. +- **Select a scenario** – Select "Landing page" or "Top clicked". +- **Select a content type to be displayed** – Select "Product". +- **Display limit** – Set the number of products to be displayed. + +On the **Design** tab, in the **View** field, change the layout to "Products" and submit your changes. + ## Product collection block Presents curated collections of items for easier exploration and discovery. @@ -202,6 +263,17 @@ On the **Properties** tab, set values in the following fields: Due to a technical limitation, content browser doesn't display product variants. +## Recently added block + +Highlights recently added products from PIM. +Quickly informs users about new additions for quicker distribution and popularizing added products. +On the **Properties** tab, set values in the following fields: + +- **Name** – Enter a name for the page block. +- **Personalization Scenario** – Select "Recently added items" to display products that were recently added to PIM. +- **Product Types to be displayed** – Select the type of products to be displayed on the list. +- **Limit** – Set the number of products to be displayed. + ## RSS block Imports and showcases news content from RSS feeds (channels), helping users stay informed with the latest updates and diverse news sources. @@ -289,4 +361,4 @@ On the **Properties** tab, set values in the following fields: - **Name** – Enter a name for the page block. - **Video** — Click **Select content**, browse the content, and select a video to display in the block. -On the **Properties** tab you can preview the selected video before adding it to the page. +On the **Properties** tab you can preview the selected video before adding it to the page. \ No newline at end of file diff --git a/docs/content_management/create_edit_pages.md b/docs/content_management/create_edit_pages.md index 8b4c26e6..902c4b2b 100644 --- a/docs/content_management/create_edit_pages.md +++ b/docs/content_management/create_edit_pages.md @@ -148,6 +148,8 @@ For a list of blocks available out of the box, see [Block reference](block_refer Before you add a block that involves products, product types, or product categories, make sure your that your [user role](../permission_management/permissions_and_users.md) has the `Product/View` and `Product type/View` permission. + Before you add a block that uses results derived from a [Personalization](../personalization/personalization.md) scenario, for example, [Dynamic targeting](block_reference.md#dynamic-targeting-block) or [Recently added block](block_reference.md#recently-added-block), make sure that the scenario is [properly configured](../personalization/configure_scenarios.md). + You can work with the block, for example, duplicate it, change its position, or delete it. Hover over the block and the toolbar appears. Click the three dots icon to see more options. diff --git a/docs/getting_started/dashboard/dashboard_block_reference.md b/docs/getting_started/dashboard/dashboard_block_reference.md index cf16d188..9a489f18 100644 --- a/docs/getting_started/dashboard/dashboard_block_reference.md +++ b/docs/getting_started/dashboard/dashboard_block_reference.md @@ -18,6 +18,7 @@ The following blocks are provided with a clean installation of [[= product_name |[Recent activity](#recent-activity-block)|Displays a list of recent activity of all or selected users.| |[Recent orders](#recent-orders-block)|Displays a table presenting recent orders and their status.| |[Review queue](#review-queue-block)|Displays a list of content items which user or user group can review.| +|[Top 10 clicked items](#top-10-clicked-items-block)|Displays a table presenting top 10 clicked items.| !!! note @@ -152,3 +153,19 @@ On the **Properties** tab, set values in the following fields: - **Name** - Enter a name for the block. On the **Design** tab, in the **View** field, select the layout to be used to present a list of content items for review and submit your changes. + +## Top 10 clicked items block [[% include 'snippets/experience_badge.md' %]] [[% include 'snippets/commerce_badge.md' %]] + +Requires [Ibexa Personalization](personalization.md) enabled. + +Displays a table presenting top 10 clicked items. + +Table contains following columns: Item clicked (including item name), Item type, Recommended (presenting number of recommendations of selected item), +Clicked (presenting total number of clicks on selected item). + +On the **Properties** tab, set values in the following fields: + +- **Name** - Enter a name for the block. +- **Customer ID** - Select customer ID whose top 10 clicks are displayed. + +On the **Design** tab, in the **View** field, select the layout to be used to present a list of content items for review and submit your changes. diff --git a/docs/persona_paths/explorer.md b/docs/persona_paths/explorer.md index e5260f25..d554aaa7 100644 --- a/docs/persona_paths/explorer.md +++ b/docs/persona_paths/explorer.md @@ -14,6 +14,8 @@ Whether you're a new or seasoned user of [[= product_name =]], feel free to brow "persona_paths/author_content", "persona_paths/organize_content", "content_management/taxonomy/taxonomy", + "personalization/personalization", + "personalization/configure_personalization", "search_engine_optimization/seo", "pim/products", "persona_paths/manage_products", diff --git a/docs/personalization/configure_models.md b/docs/personalization/configure_models.md new file mode 100644 index 00000000..60a09c93 --- /dev/null +++ b/docs/personalization/configure_models.md @@ -0,0 +1,63 @@ +--- +description: Configure models by setting up a timeframe, segments and other settings that define which content items are recommended. +--- + +# Configure models + +If your [user role](../permission_management/permissions_and_users.md) has the `Personalization/Edit` permission that includes your website, you can modify model settings according to your requirements. + +Go to **Personalization** > **Models** to see a page that lists all available [models](recommendation_models.md) and provides detailed information, such as the [scenarios](scenarios.md) that use each model, or when the model was last triggered. + +![Models page in the back office](img/dashboard_models.png "Models page") + +Here, you can click the **Edit** icon to access the model configuration screen and modify the settings, for example: + +- A timeframe over which the algorithm gathers [events](event_types.md) that are used in the calculation +- [Submodels](recommendation_models.md#submodels) that can narrow down the list of model results +- [Segments](segment_management.md#configure-segments) that allow getting personalized content suitable for particular user groups +- A list of items included or excluded from the model + +For more information and a list of model types, see [Recommendation models](recommendation_models.md). + +### Advanced model configuration + +Most of the models provide additional configuration parameters, which enable customization. + +The parameters supported by different model types are described in the table below. +Some models support [submodels](recommendation_models.md#submodels). +Additional differentiation criterion is the supported context. +If a model requires context, it can only be linked to scenarios that provide the necessary context. + +|Model type|Available parameters|Submodel support|Context| +|---|---|---|---| +|Popularity|Relevant event history defines the time period for which the statistics must be analyzed. Depending on the type of product, it can be between several months and several hours. Fast event aging can be used to weight newer events higher than older events.|yes
submodels based on category are enabled by default|not needed| +|Also clicked/purchased / Ultimately bought|Both also clicked and ultimately purchased models allow defining the relevant event history.|yes, manual|required (either context items or user data)| +|Recently added|This model requires the maximum age for the items that should be recommended by this model.|yes|not supported| +|History-based|The type of the history (CLICK-history or BUY-history) must be specified.|no|required (user data)| +|Editor-based|The list of recommendations must be created manually by the editor.|no|not supported| +|Blacklist|The list of items that should be excluded from the recommendations must be created manually by the editor.|no|not supported| + +Do not confuse event history age with item age. +History age is the age of the user's footprint (for example, "User clicked on the product A two weeks ago"). +Item age is the time over which the item is available in the web store ("How new is the item"). +The history is recorded automatically based on [event](event_types.md) tracking. +The item catalog must be filled separately as a result of [data import](content_import.md). + +### Trigger model build + +Models on the Personalization server side are configured to build at intervals, for example, every 24-hours. +For models which require computation (all [popularity](recommendation_models.md#popularity-models) and [collaborative models](recommendation_models.md#collaborative-models)), you can manually trigger the build, for example, after you modify model settings. + +To do this, go to **Personalization** > **Models**. +Click the edit icon next to the model name, make necessary changes, and click the **Trigger model build** button. +On the list of models, the model's status changes to `Build in progress`. +When the build comes out successful, the status changes to `Active`. + +![Model build status](img/models_edit.png "Model build status") + +Possible model statuses: + +- **Active** - model is successfully built +- **Not active** - new model which hasn’t been triggered or used yet, or model that is added to the scenario, calculated and then removed from the scenario +- **Build in progress** - model during the building process +- **Failed** - there is no data to build the model or some error occurred, building failed diff --git a/docs/personalization/configure_personalization.md b/docs/personalization/configure_personalization.md new file mode 100644 index 00000000..b57cff1c --- /dev/null +++ b/docs/personalization/configure_personalization.md @@ -0,0 +1,25 @@ +--- +description: Configure your Personalization service by setting up models and scenarios which define which content items are recommended. +--- + +# Configure personalization + +In the back office, you can you can review the configuration that controls the Personalization service. +If your [user role](../permission_management/permissions_and_users.md) has the `Personalization/Edit` permission that includes your website, you can modify the settings according to your requirements. +To do this, navigate to one of the pages mentioned below and edit the item that you want to modify. + +!!! note "Host multiple websites" + + If you have permissions to access several websites hosted on an [[= product_name =]] instance, you can use the selector field to switch between views for each of these websites. + +[[= cards([ + "personalization/configure_models", + "personalization/segment_management", + "personalization/recommendation_models", + "personalization/event_types", + "personalization/configure_scenarios", + "personalization/scenarios", + "personalization/content_types", + "personalization/filters", + "personalization/triggers" +]) =]] diff --git a/docs/personalization/configure_scenarios.md b/docs/personalization/configure_scenarios.md new file mode 100644 index 00000000..75f42c8d --- /dev/null +++ b/docs/personalization/configure_scenarios.md @@ -0,0 +1,102 @@ +--- +description: Configure models by setting up a timeframe, segments and other settings that define which content items are recommended. +--- + +# Configure scenarios + +If your [user role](../permission_management/permissions_and_users.md) includes the `Personalization/View` policy, you can go to **Personalization** > **Scenarios** and see a page that lists all available scenarios. +It also provides additional information, such as a description of each of the scenarios, [models](recommendation_models.md) that the scenario uses, or indication of whether the scenario is operational or not. + +![Scenarios page in the back office](img/dashboard_scenarios.png "Scenarios page") + +To modify the scenarios to suit your needs, you must have the `Personalization/Edit` policy. +You can then click the **Edit** icon next to the name of the scenario. + +!!! note + + You may have permissions to access several websites hosted on an [[= product_name =]], [with independent results returned for each of these websites](use_cases.md#multiple-website-hosting). + If this is the case, use the selector field to switch between views for each of these websites. + +In the scenario configuration screen, you can configure a number of settings, for example: + + - The [type of content](content_types.md) used as input data and recommended items + - A strategy consisting of primary, secondary and provisional models used to calculate results + - User profile-based settings, boost settings and other [filters](filters.md) that can be used to eliminate or promote specific results + +## Configure basic settings + +Provide a name and an identifier for the scenario. +Select a single input type and at least one output type. + +![Basic scenario configuration](img/scenario_configuration.png "Basic scenario configuration") + +## Configure strategy + +Modify the strategy by dragging model boxes between the **Models** area that lists all available models and the **Strategy** board. + +![Strategy configuration](img/scenario_configuration_strategy.png "Strategy configuration") + +You can arrange models within a scenario board by importance. +To make it possible, strategies have several levels. +Add several models to every strategy level to avoid empty or insufficient recommendation results. + +!!! note + + Models from each level are used in parallel and strategy results contain an equally distributed mixture of both model results. + If models from one level do not return enough results, models from the subsequent levels are used. + +From the **Data type** and **Context** drop-downs, select the required options to group items based on supported data types for the model. +You can choose between **Submodels** or **Segments** data types. + +If selected models support additional differentiators, you can apply them here. For more information about available model settings, see [Advanced model configuration](configure_models.md#advanced-model-configuration). + +!!! note + + By default, models doe not use submodels or segments. + Changes you make here apply only in the context of the current scenario. + +## Configure filters + +For every recommendation scenario, you can define a set of filters. +With filters you can eliminate, demote or promote specific recommendation results. + +![General filters](img/scenario_filters.png "General filters in a scenario") + +For a complete list of available general filter types and their meaning, see [General filters](filters.md#general-filters). + +## Configure category filters + +For each of the importance levels from the strategy configuration matrix, you can configure category filters. +Click the **Configure** icon next to an importance level name and make necessary changes. + +![Category path filters](img/categorypath_filter.png "Category path filters in strategy settings") + +For a detailed description, see [Category path filters](filters.md#category-path-filters). + +## Configure cross content type recommendations + +Cross content type option is used to combine best recommendation items from different [types of content](content_types.md). +It applies to scenarios which have more than one output type configured. + +To get multiple output types in the recommendation request, perform the following actions: + +1. Go to **Personalization** -> **Scenarios**. + +2. Click the **Edit** icon next to the scenario for which you want to set cross content type recommendations. + +3. In the **Output type** multiselect field, select the types for which you want to get recommendations in the request. + + It contains a list of all types of content exported for the specified customer ID. + +4. Click **Save and close**. + +## Preview scenario results + +To check the results of your changes, [preview the scenario results](preview_scenario_results.md). +You may need to provide additional information, for example, to test the cross content type recommendations, in the preview configuration screen, from the **Output type** drop-down, select **All**. + +!!! note + + The **All** option becomes available only after you select multiple types of content in the scenario settings. + +![Cross content type preview settings](img/perso_cross_content_type.png "Cross content type preview setting") diff --git a/docs/personalization/content_import.md b/docs/personalization/content_import.md new file mode 100644 index 00000000..ab707cd7 --- /dev/null +++ b/docs/personalization/content_import.md @@ -0,0 +1,40 @@ +--- +description: Importing existing data enables the Personalization service to provide better results for recommendations. +--- + +# Import source data + +Before the Personalization service can generate relevant recommendations, it must be fed with data that relates to [content](content_types.md) items/products that are monitored, and [event](event_types.md) tracking information. +Some [scenarios](scenarios.md) return better results if provided with user data. + +Data import operations are configured at the developer level, based on the arrangements that you make with [[= product_name_base =]]. +Content item import jobs fetch data from the recommendation client, which tracks events, to the Personalization service. +The Personalization service then processes the events and calculates the recommendations. + +!!! note "Host multiple websites" + + If your installation [hosts multiple websites](use_cases.md#multiple-website-hosting) and returns separate recommendations + For each of these websites, you must import data separately. + +## Content data import + +The Personalization service can accept data import in a several ways. +For example, one can load an exported file to the Personalization service from a specified location.  +This type of import is intended to upload big portions of information, and can be used to perform a weekly update of the whole product catalog. + +For detailed information about content data import, see [Export item information]([[= developer_doc =]]/personalization/enable_personalization/#export-item-information) and [Content API]([[= developer_doc =]]/personalization/api_reference/content_api/) in Developer Documentation. + +## User data import + +The Personalization service has little information about the users of the website. +Additional attributes, such as the user's age or home city, might help the service generate a successful recommendation, for example, by enabling the use of [boost filters](filters.md#boost-filters). +User attributes could be retrieved based on the external user ID. +However, it's rarely possible to combine the external user ID within the user's attribute set. + +For more information about user attribute import, see [User API]([[= developer_doc =]]/personalization/api_reference/user_api/) in Developer Documentation. + +## List of import operations + +In the back office, from the main menu, under **Personalization**, you can access the **Import** page that displays a list of historical import operations and their details, such as the number of imported content items/products, their type and language. + +![Import tab in the back office](img/dashboard_import.png "Import tab") diff --git a/docs/personalization/content_types.md b/docs/personalization/content_types.md new file mode 100644 index 00000000..6f2f045c --- /dev/null +++ b/docs/personalization/content_types.md @@ -0,0 +1,37 @@ +--- +description: Types of content in the Personalization service allow building different recommendations for different parts of our content model. +--- + +# Types of content + +With the Personalization service, you can build different recommendation domains. +You do this by splitting all the products into different types of content. +There are several possible use cases for types of content, for example: + +- A publisher can track articles, pictures and videos as three different types. +- A store can split all the products into food and non-food product groups. +- An owner of several web stores can use a single account for all of them. + +Based on the types of content concept, it's possible to make so-called cross content type recommendations (like "Users who watched this film also read this book" or "Users who bought these wallets also bought these belts"). + +Apart from the logical separation of the content domains, types of content provide another important advantage. +You can use them to adjust recommendation weight if different types of products/content items aren't equally popular but must be recommended equally often. +For example, on a content publisher's page, users watch videos less often than they read articles. +If the most popular products were requested without splitting the types of content, there would most likely be no videos in the recommendation result. +If articles and videos are split into different types of content, you can explicitly request popular videos and/or popular articles. + +Here is a comparison of different approaches that you can take when defining types of content: + +|Use case|Types of content solution (domain context)|Attribute based sub-models (group context)|Different Personalization service accounts| +|---|---|---|---| +|Cross-group recommendation requests are possible|yes|yes|no| +|Products must belong to one group|mandatory|optional|mandatory| +|Products can belong to multiple groups|no|yes|no| +|Single recommendation request can contain products from different groups|no|yes|no| +|Product can change the group it belongs to|no|yes|no| +|Different types of content share the scenario and model configuration|yes|yes|no| + +### Types of content and scenarios + +If multiple types of content are enabled in your configuration, for every scenario that should recommend a specific type, you must enable this output type. +For more information about scenario configuration, see [Configure scenarios](configure_scenarios.md). diff --git a/docs/personalization/enable_personalization.md b/docs/personalization/enable_personalization.md new file mode 100644 index 00000000..dd15a483 --- /dev/null +++ b/docs/personalization/enable_personalization.md @@ -0,0 +1,47 @@ +--- +description: Enabling the Personalization service requires an installation key provided by Ibexa. +--- + +# Enable personalization + +The Personalization service is based on a client-server architecture. +The recommendation client that is part of your installation must connect to the server that is run and maintained by [[= product_name_base =]]. +To use the service, you must make arrangements with [[= product_name_base =]] to define the initial configuration, and then get and set up authentication parameters. + +## Request access to the server + +After you get the initial configuration from [[= product_name_base =]], you must accept the terms and conditions of the Personalization service and create an account to get access to the server. + +### Create account + +First, you must accept the terms and conditions of the Personalization service. + +1\. Go to the back office. + +2\. On the left panel, go to **Personalization** > **Dashboard**. + +3\. On the welcome screen, provide the following details: + +- A full name of the person responsible for accepting the terms and conditions +- An email address to which you want the confirmation to be sent +- An installation key that can be found on the **Maintenance and Support agreement details** page in the service portal + +4\. Select the **I have read and agree to the Terms and Conditions** checkbox, and then click **Submit**. + +5\. Next, enter the project name or your brand name. + +![Create account](img/perso_create_account_1.png "Create account") + +6\. From the **Type** drop-down, select the account type (Commerce or Publisher). + +7\. To proceed, click **Next**. After a few moments, a screen with your ID and license key displays. + + +![Basic scenario configuration](img/perso_create_account_2.png "Account credentials") + +## Set up service parameters + +When you receive the credentials, ask your administrator to: + +- [add the credentials to your configuration]([[= developer_doc =]]/personalization/enable_personalization/#set-up-customer-credentials) +- [configure events that you wish to track]([[= developer_doc =]]/personalization/enable_personalization/#set-up-item-type-tracking) diff --git a/docs/personalization/event_types.md b/docs/personalization/event_types.md new file mode 100644 index 00000000..90315f0f --- /dev/null +++ b/docs/personalization/event_types.md @@ -0,0 +1,45 @@ +--- +description: Recommendations rely on tracking different events that describe users' behavior on the website. +--- + +# Events + +Before the Personalization service can generate implicit recommendations, it must collect events and calculate the results based on user behavior. +The most important events collected by the service are CLICK and BUY events. +They're enough for providing basic recommendations. +Additional events exist for creating more complex [scenarios](scenarios.md) and providing [statistics](review_perso_performance.md#statistical-information) about the acceptance of recommendations, such as conversion rate or revenue.  + +![Events in a purchase process](img/events_overview.png "Events in a purchase process") + +The table below lists all possible events that could be used in the system. + +|Event|Description| +|---|---| +|BASKET|Sent when the user adds the specified product to the shopping cart. Enables creating recommendations for products that customers are interested in but ultimately did not purchase.| +|BLACKLIST|Allows a user to suppress currently displayed recommendations. When the Personalization service receives this event, the product or item is no longer recommended to the specified user. By default, recommendations are suppressed for one year.| +|BUY|Sent if something was purchased.| +|CLICK|Sent to the Personalization service when a user opens a page on the website.| +|CLICKRECOMMENDED / FOLLOW|Sent when a user clicks the recommended product. Used in acceptance statistics.| +|CLICKTRIGGERED|Sent when a user clicks the link delivered in a trigger message to see the recommended item. Used in statistics.| +|CONSUME|Similar to the BUY event but without a payment. Designed for content publisher websites. Sent when an article or a web page is consumed (read or watched).| +|DELETEFROMBASKET|Sent when the end user removes items from their shopping cart. Helps eliminate recommendations for products that the customer is no longer planning to buy.| +|DELETEFROMWISHLIST|Sent when the end user removes items from their wishlist. Used to eliminate recommendations for products that the customer has either lost interest in or already purchased elsewhere.| +|OWNS|Same as BUY, but doesn't influence the statistics. Can be sent when a user already owns the product that was purchased somewhere else, to avoid recommending it again.| +|RATE|Additional [models](recommendation_models.md) can be created with this type of events. Allows building recommendations not only for implicit tracking events like CLICK or BUY, but also for events with explicit value like "rated" or "liked". These events need additional integration into the web page to allow the user to give an appropriate feedback. The event is triggered as a result of this user feedback.| +|RENDERED|Sent when a recommendation is shown on the web page. This information is used by [filters](filters.md) to suppress repeated recommendations of the same item.| +|TRANSFER / LOGIN|A special type of event to deal with user login after the user already surfed on the web page anonymously. Always sent when the identifier of the user changes. As a result, the anonymous history of the user is transferred to the new identifier. This happens automatically in the Personalization service.| +|TRIGGEROPENED|Sent when a user opens a [trigger message](triggers.md), for example, an email. Used in statistics.| +|WISHLIST|Sent when the user adds a product to their wishlist. Enables creating recommendations for products that the customer considers purchasing in the future.| + +All events require the current user ID and the ID of one or more context items. +Some events require additional information. +Sophisticated algorithms and result filtering require event types with additional parameters. +The table below provides a brief overview of additional parameter information. + +|Event|Additional information| +|---|---| +|CLICK|Category path of the product a customer clicked on can be attached to the event. It's an alternative way to provide this information for a product without having a catalogue/export. Ignored if an export is available to be fed into the Personalization service.| +|BUY|The price that a user paid for the product, an important parameter for the statistics. For revenue statistics, it must be sent together with a quantity of the products bought.| +|TRIGGEROPENED /CLICKTRIGGERED|An identifier of the trigger that the trigger and recommendations originate from.| +|FOLLOW / CLICKRECOMMENDED|The scenario which provided the recommendations must be sent in this event.| +|RATE|The rating (for example 1 to 5 stars) can be sent as an additional parameter.| diff --git a/docs/personalization/filters.md b/docs/personalization/filters.md new file mode 100644 index 00000000..d97584b1 --- /dev/null +++ b/docs/personalization/filters.md @@ -0,0 +1,129 @@ +--- +description: Filters enable you to fine-tune recommendation results by eliminating, demoting, or promoting specific results. +--- + +# Filters + +## General filters + +For every recommendation [scenario](scenarios.md), you can define a set of filters. +They're tools that you can use to eliminate, demote or promote specific recommendation results. +Filters are applied to all recommendations that come from [models](recommendation_models.md) selected in the strategy. + +### User profile-based filters + +User profile-based filters are applicable in both publishing and eCommerce use cases. + +|Filter|Requirements and restrictions| +|---|---| +|Do not recommend the item currently viewed|When you activate this filter, it removes the context items from the recommendation list. You might not want to use this filter if your strategy is based on the ["Ultimately bought"](recommendation_models.md#ultimately-bought) model.| +|Do not recommend items the user already consumed|The Personalization service stores the CONSUME events of every user for one year. When you activate this filter, the user doesn't get the recommendation for the consumed content again.| +|Max. repeated shows of identical recommendations per session|When you activate this filter and set a value, after a content item/product is recommended a certain number of times during the current user session, it's removed from all recommendation lists.| + +#### Boost filters + +User profile-based filters include a filter for moving certain items up on the list. +If enabled, boosting is triggered when values of a selected attribute from a user profile and the recommended item match. +For example, news from the user's home country can have higher priority than from the rest of the world. + +In the diagram below, every item has the `country` attribute and user profiles have the `country_of_origin` attribute. +You can configure the boost filter to promote recommendations for certain users: + +![Boost filter example](img/boost_example.png "Boost filter example") + +Item boosting requires that the Personalization service is fed with both item and user attribute data. +For more information about importing data, see [Import data](content_import.md). + +### Exclusions + +You can exclude categories from the recommendation response by providing fixed category paths or by context item category paths. + +!!! tip + + You can use both fixed category and context item category paths at the same time. + +|Exclusion name|Function| +|---|---| +|Exclude category of the context item|Excludes items in the recommendation response from the same categories as the context item in the recommendation request. Use this exclusion if you don't want to recommend items from the category of the currently rendered item. For example, if the customer is browsing items from the *TV* category, you can ensure that recommendation boxes don't display recommendations from this category. This is automatically defined from the context.| +|Exclude category|Defines lists of categories which should not be recommended in a scenario. Excludes the category that is last in the path. For example, in the following category path: *Furniture/Living room/Sofas*, all items from the *Sofas* category are excluded for this scenario. You can add many categories.| + +### Commerce-specific filters + +The following filters are only applicable in Commerce use cases. + +|Filter|Requirements and restrictions| +|---|---| +|No top-selling items|When you activate this filter, items that come from the top selling model (even if the model itself isn't linked to this scenario) aren't placed on the recommendations list. This way you can stop promoting products that are already popular. If you apply this filter to a top selling scenario it filters out all recommendations.| +|Item price should be equal or higher than the price of the context product|You can use this filter to filter out items that could be more attractive to the user from the recommendation list. It compares prices exported to the Personalization service with metadata of the currently viewed product.| +|Minimum price of the recommended product|You can use this filter to remove cheap and popular items from the recommendation list. For example, as an optometrist you might prefer showing the most popular designer frames on the home page and avoid promoting insurance subsidized cheap models or cleaning cloths. Again, this filter relies on product metadata and uses prices exported to the Personalization service.| +|Do not recommend if price unknown|If a product's price is unavailable then the product isn't recommended.| +|Do not recommend items the user already purchased|When you activate this filter, the user isn't recommended to purchase products again.| +|Do not recommend product variants| By default, this filter is deactivated: only [product variants](work_with_product_variants.md) are recommended and base products aren't recommended. When you activate this filter, a recommendation response includes base products, while product variants are excluded. The filter doesn't affect products that have no variants. | + +!!! note "Product variants support" + + The **Do not recommend product variants** checkbox is visible only if your version of [[= product_name =]] [supports product variants]([[= developer_doc =]]/release_notes/ibexa_dxp_v4.2/#product-variants). + Also, it's invisible before [data is imported](content_import.md) into the Personalization service, therefore you may need to revisit the [scenario configuration](configure_scenarios.md) page when data import completes. + +## Category path filters + +Apart from filters that you define at the scenario level, you can use category path filters to narrow down recommendation results returned by each of the priority levels in the scenario strategy. +When you activate a filter of this type, the service recommends only items from a specific item/product category. +The actual category used to filter on is taken from recommendation request parameters. + +There are two ways to specify a category path in a recommendation request: + +- When there are no context items, but the category is provided in the request:  + You might want to place such recommendation calls on category overview pages to display the most popular items/products of the currently viewed category (or "reference category"). +- When context items are provided and categories of all context items are used for the request:  + This approach is recommended only if it's technically impossible (or too complex) to provide the category information explicitly. + +Depending on how you configure category path filters, the Personalization service can take different paths to find the actual set of categories to recommend the items/products from. + +The following example shows the category structure (which basically corresponds to website navigation): + +![Example of a category path tree](img/categorypath_tree.png "Example of a category path tree") + +The table below lists all possible configurations and categories that recommended items/products are fetched from, based an assumption that the reference category passed in the request is "/Furniture/Desks&Tables/Tables". + +|Category path filter configuration|Categories to fetch recommended items from| +|---|---| +|"Recommend items from the whole site"|All categories ("Plants", "Furniture" and below).| +|"Recommend items from the same category"
"Also include the parent category and its subcategories" not selected|Category "Tables" and all the sub-categories below ("Garden tables" and "Living room tables").| +|"Recommend items from the same category"
"Also include the parent category and its subcategories" set to 1 level up|Category "Desks/Tables" and below including "Desks", "Tables" and all their sub-categories.| +|"Recommend items from the same category"
"Also include the parent category and its subcategories" set to 2 levels up|Category "Furniture" and below.| +|"Recommend items from the same main category and its subcategories" set to 1 category level and below|Category "Furniture" and below.| +|"Recommend items from the same main category and its subcategories" set to 2 category levels and below|Category "Desks/Tables" and below.| +|"Recommend items from the same main category and its subcategories" set to 3 category levels and below|Category "Tables" and below.| + +You can provide multiple reference categories (both in the request and by defining context items). +In such a case, the superset of the recommendations is returned, and the results are sorted based on a global weight of the recommendations. +Depending on the popularity of the categories, the more popular categories push the less popular categories out of the results. + +If the recommended item is located in more than one category, at least one category should be requested in the recommendation call. + +### Multiple category path dimensions for popularity models + +The category path parameter is a powerful tool. +A typical approach is to represent the default content in the navigation-based structure of a website. +If you need to represent available items of a website in different dimensions (taxonomies), you can do this out of the box, by enriching the `categorypath` information of an item. + +For example, in a store that sells furniture and plants, products can be structured based on website navigation. +Typically, customers would look for computer desks and get a list of recommendations of all computer desks in the store. +When necessary, the Personalization service can also use another dimension for filtering recommendations, for example, a "brand" dimension. +In this case, users would get recommendations for all items from the same "brand". + +With popularity-based recommendations, you can get the most popular products based on the main navigation tree (for example, the most popular desks) or based on the brand (for example, the most popular IKEA products). + +Here are the examples of common representation dimensions of items beyond the website navigation: + +|Business|Possible dimensions| +|---|---| +|eCommerce|manufacturer (for example, BOSCH or Renault)
season (for example, winter or spring)
price range (for example, entry, middle, or premium)
platform (for example, Mac, Windows, or Linux)| +|Book store|genre (for example, romance, action, or science)
design (for example, hardcover, paperback, or audiobook)
author (for example, George R. R. Martin or Steven Spielberg)| +|Content publishing|global subject (for example, politics, sports, or tech)
physical location (for example, France, Norway, or Berlin)
timeframe (for example, today, this week, or exact date)| + +You should avoid using category filtering with "Also clicked/purchased" and stereotype models. +These models usually contain similar items, and additional filtering might remove the best results from the list of possible recommendations. +The only exception could be coping with copyright or legal issues by removing unlicensed or adult content in certain markets or for certain customers. +However, this use case could be handled with equal or greater success using [submodels](recommendation_models.md#submodels) or [types of content](content_types.md). diff --git a/docs/personalization/img/attribute_example.png b/docs/personalization/img/attribute_example.png new file mode 100644 index 00000000..af881042 Binary files /dev/null and b/docs/personalization/img/attribute_example.png differ diff --git a/docs/personalization/img/boost_example.png b/docs/personalization/img/boost_example.png new file mode 100644 index 00000000..b0de3589 Binary files /dev/null and b/docs/personalization/img/boost_example.png differ diff --git a/docs/personalization/img/categorypath_filter.png b/docs/personalization/img/categorypath_filter.png new file mode 100644 index 00000000..81a433b0 Binary files /dev/null and b/docs/personalization/img/categorypath_filter.png differ diff --git a/docs/personalization/img/categorypath_tree.png b/docs/personalization/img/categorypath_tree.png new file mode 100644 index 00000000..c24e0378 Binary files /dev/null and b/docs/personalization/img/categorypath_tree.png differ diff --git a/docs/personalization/img/dashboard_import.png b/docs/personalization/img/dashboard_import.png new file mode 100644 index 00000000..08cd7a21 Binary files /dev/null and b/docs/personalization/img/dashboard_import.png differ diff --git a/docs/personalization/img/dashboard_models.png b/docs/personalization/img/dashboard_models.png new file mode 100644 index 00000000..035f6bf4 Binary files /dev/null and b/docs/personalization/img/dashboard_models.png differ diff --git a/docs/personalization/img/dashboard_scenarios.png b/docs/personalization/img/dashboard_scenarios.png new file mode 100644 index 00000000..39f07940 Binary files /dev/null and b/docs/personalization/img/dashboard_scenarios.png differ diff --git a/docs/personalization/img/dashboard_statistics.png b/docs/personalization/img/dashboard_statistics.png new file mode 100644 index 00000000..fb0c0d7d Binary files /dev/null and b/docs/personalization/img/dashboard_statistics.png differ diff --git a/docs/personalization/img/events_overview.png b/docs/personalization/img/events_overview.png new file mode 100644 index 00000000..d15d7232 Binary files /dev/null and b/docs/personalization/img/events_overview.png differ diff --git a/docs/personalization/img/models_edit.png b/docs/personalization/img/models_edit.png new file mode 100644 index 00000000..11083912 Binary files /dev/null and b/docs/personalization/img/models_edit.png differ diff --git a/docs/personalization/img/models_time_period.png b/docs/personalization/img/models_time_period.png new file mode 100644 index 00000000..8b99f82d Binary files /dev/null and b/docs/personalization/img/models_time_period.png differ diff --git a/docs/personalization/img/perso_create_account_1.png b/docs/personalization/img/perso_create_account_1.png new file mode 100644 index 00000000..f2ef7532 Binary files /dev/null and b/docs/personalization/img/perso_create_account_1.png differ diff --git a/docs/personalization/img/perso_create_account_2.png b/docs/personalization/img/perso_create_account_2.png new file mode 100644 index 00000000..b099aed5 Binary files /dev/null and b/docs/personalization/img/perso_create_account_2.png differ diff --git a/docs/personalization/img/perso_cross_content_type.png b/docs/personalization/img/perso_cross_content_type.png new file mode 100644 index 00000000..cf6c7470 Binary files /dev/null and b/docs/personalization/img/perso_cross_content_type.png differ diff --git a/docs/personalization/img/perso_segment_group_and_parent.png b/docs/personalization/img/perso_segment_group_and_parent.png new file mode 100644 index 00000000..58f51ac2 Binary files /dev/null and b/docs/personalization/img/perso_segment_group_and_parent.png differ diff --git a/docs/personalization/img/perso_segment_group_or.png b/docs/personalization/img/perso_segment_group_or.png new file mode 100644 index 00000000..272cf151 Binary files /dev/null and b/docs/personalization/img/perso_segment_group_or.png differ diff --git a/docs/personalization/img/perso_segment_group_sales_hunters.png b/docs/personalization/img/perso_segment_group_sales_hunters.png new file mode 100644 index 00000000..f9386319 Binary files /dev/null and b/docs/personalization/img/perso_segment_group_sales_hunters.png differ diff --git a/docs/personalization/img/recently_added_item_age.png b/docs/personalization/img/recently_added_item_age.png new file mode 100644 index 00000000..462e0428 Binary files /dev/null and b/docs/personalization/img/recently_added_item_age.png differ diff --git a/docs/personalization/img/scenario_configuration.png b/docs/personalization/img/scenario_configuration.png new file mode 100644 index 00000000..bfd42401 Binary files /dev/null and b/docs/personalization/img/scenario_configuration.png differ diff --git a/docs/personalization/img/scenario_configuration_strategy.png b/docs/personalization/img/scenario_configuration_strategy.png new file mode 100644 index 00000000..64a0fc1c Binary files /dev/null and b/docs/personalization/img/scenario_configuration_strategy.png differ diff --git a/docs/personalization/img/scenario_filters.png b/docs/personalization/img/scenario_filters.png new file mode 100644 index 00000000..681d4e3b Binary files /dev/null and b/docs/personalization/img/scenario_filters.png differ diff --git a/docs/personalization/img/scenario_preview_content_search.png b/docs/personalization/img/scenario_preview_content_search.png new file mode 100644 index 00000000..4c78f31b Binary files /dev/null and b/docs/personalization/img/scenario_preview_content_search.png differ diff --git a/docs/personalization/img/use_case_detail_page.png b/docs/personalization/img/use_case_detail_page.png new file mode 100644 index 00000000..1c5dea0b Binary files /dev/null and b/docs/personalization/img/use_case_detail_page.png differ diff --git a/docs/personalization/img/use_case_landing_page.png b/docs/personalization/img/use_case_landing_page.png new file mode 100644 index 00000000..0a5565de Binary files /dev/null and b/docs/personalization/img/use_case_landing_page.png differ diff --git a/docs/personalization/img/use_case_shopping_basket.png b/docs/personalization/img/use_case_shopping_basket.png new file mode 100644 index 00000000..8cbb901d Binary files /dev/null and b/docs/personalization/img/use_case_shopping_basket.png differ diff --git a/docs/personalization/integrate_scenario_results.md b/docs/personalization/integrate_scenario_results.md new file mode 100644 index 00000000..c0402271 --- /dev/null +++ b/docs/personalization/integrate_scenario_results.md @@ -0,0 +1,55 @@ +--- +description: Use the Personalized block to display recommendation results in your pages. +edition: experience +--- + +# Integrate scenario results + +When the Personalization service is [enabled](enable_personalization.md) and properly [configured](configure_personalization.md), as an editor, you can embed the recommendations that come from the service, to show them to the end users. +You can, for example, modify a page to include a block that shows what content items/products are recommended to end users when specific [scenarios](scenarios.md) are triggered. +One such example is the [Personalized block](../content_management/block_reference.md#personalized-block), where you can choose from a number of scenarios, but there are also other blocks that are tailored to display the results of scenarios of specific types, like [Recently added block](../content_management/block_reference.md#recently-added-block) or [Bestsellers block](../content_management/block_reference.md#bestsellers-block). +Depending on the scenario type, you may need to provide additional information to see the recommendation results. + +The blocks, the number, and selection of available scenarios within these blocks depend on the arrangements that your organization makes with [[= product_name_base =]] when defining the initial configuration. + +Follow these steps to add and configure the Personalized block to a Page: + +1. In [content tree](discover_ui.md#content-tree), navigate to the page in which you want to place a personalization block. + +1. From the **Page blocks** toolbox, drag and drop the **Personalized** block to a location on the page layout. + +1. Click the **Block settings** icon to modify the **Personalized** block: +  + 1. On the **Basic** tab, set values in the following fields: + - **Block name** – Optionally, enter a name for the page block, for example, "Bestsellers". + - **Select a scenario** – Select "Landing page" or "Top clicked". + - **Select a content type...** – Select "Product". + - **Display limit** – Set the number of products to be displayed, for example, 4. + + 1. On the **Design** tab, in the **View** field, change the layout to "Products" and submit your changes. + + The preview of the Page changes to display a list of products recommended by the Personalization service. + +1. Save your changes to the draft or publish the Page. + +For more information about collecting events and embedding recommendation results, see [Integrate recommendation service]([[= developer_doc =]]/personalization/integrate_recommendation_service/). + +## Use cross content type in Page Builder blocks + +When scenarios are configured to display [cross content type recommendations](configure_scenarios.md#configure-cross-content-type-recommendations), you can use them in the following Page Builder blocks: [Dynamic targeting](../content_management/block_reference.md#dynamic-targeting-block) and [Personalized](../content_management/block_reference.md#personalized-block). + +To get all output types in the Dynamic targeting block: + +1. In the block settings, set the scenario with configured cross content type output. +1. From the **Output type** drop-down, select **All**. +1. Next, set the rules according to your needs. +1. Click **Submit**. + +To get all output types in the Personalized block, in Page Builder, perform the following actions: + +1. In the block settings, set the scenario with configured cross content type output. +1. Next, from the drop-down **Select a content type to be displayed**, select **All**. +1. Increase the display limit to make sure all recommendations are shown. +1. Click **Submit**. + +For more information, see [Parameters]([[= developer_doc =]]/personalization/enable_personalization/#parameters) in Developer Documentation. diff --git a/docs/personalization/personalization.md b/docs/personalization/personalization.md new file mode 100644 index 00000000..7e93f7f7 --- /dev/null +++ b/docs/personalization/personalization.md @@ -0,0 +1,28 @@ +--- +description: Use the Personalization service to get recommendation for users based on their behavior and on the scenarios you configure. +--- + +# Personalization + +A cloud-based Personalization service leverages artificial intelligence and machine learning technologies to deliver optimized customer experience. +With Personalization, you capture [events](event_types.md) that represent preferences and interests of your users, apply [models](recommendation_models.md) to quantify these findings, and combine them with [scenarios](scenarios.md) to generate recommendations, which you can then [present](integrate_scenario_results.md) in a form of personalized content to visitors of one or more websites hosted by the [[= product_name =]] instance. + +Both event tracking and result publishing is done by users with administrator privileges, according to a procedure [described in Developer Documentation]([[= developer_doc =]]/personalization/integrate_recommendation_service/). + +There are different areas where you can apply recommendations. +The most common ones are [eCommerce and content publishing](use_cases.md). + +!!! note "eCommerce vs. content publishing" + + Documentation mentions eCommerce use cases more often, but provides a thorough understanding of the content publishing context as well. + + Both products and content items can be referred to as content and the BUY [event](event_types.md) can be understood as + the CONSUME event. + +Before you can use the Personalization service, you must [enable it](enable_personalization.md). +Then, for the service to generate relevant recommendations, you can [change the default configuration](configure_personalization.md). +Finally, you can [feed it with data](content_import.md), or wait until the service gathers enough information about the content and events. +On a website with more than 100 clicks per day, a day of collecting data should be sufficient for the first recommendations to be relevant. +Recommendations become better with time and the amount of data collected. + +For more information about Personalization, see [Ibexa blog](https://www.ibexa.co/blog/ibexa-dxp-v3.3-new-feature-preview-personalization-simplified-and-dxp-integrated) or a [downloadable eBook](https://www.ibexa.co/resources/ebooks-analyst-reports/the-basics-of-personalization). diff --git a/docs/personalization/preview_scenario_results.md b/docs/personalization/preview_scenario_results.md new file mode 100644 index 00000000..a4236e8a --- /dev/null +++ b/docs/personalization/preview_scenario_results.md @@ -0,0 +1,42 @@ +--- +description: In the back office you can preview what results are recommended by the Personalization service. +--- + +# Preview scenario results + +If your [user role](../permission_management/permissions_and_users.md) has the `Personalization/View` permission that includes your website, you can see what content items/products are recommended to the end user when specific [scenarios](scenarios.md) are triggered. +Depending on the scenario type, you might need to provide additional information to see the recommendation results. + +!!! note "Host multiple websites" + + If you have permissions to access several websites hosted on an [[= product_name =]] instance, you can use the selector field to switch between views for each of these websites. + +The number and selection of available scenarios depends on the arrangements that your organization makes with [[= product_name_base =]] when defining the initial configuration. + +1. Navigate to the **Personalization** > **Scenarios** tab, and then click the **Preview** icon next to a scenario that you want to preview. + +1. If your scenario is based on models of [popularity type](recommendation_models.md#popularity-models), for example, **Landing page** or **Top clicked**, skip to the last step. + + No further configuration is required. + +1. If your scenario is based on models of [collaborative type](recommendation_models.md#collaborative-models), for example, **Also clicked**, in the **Context items** area, in the **Set up items** field, and start typing content item/product name or ID. + + 1. From the search results select the respective content item/product. + 1. Click the **Add** button to confirm. + + ![Preview scenario](img/scenario_preview_content_search.png "Preview scenario") + +1. If your collaborative scenario has [category-path filtering](filters.md#category-path-filters) enabled, for example, **Also clicked - category**, in the **Category path filter** area: + 1. Click **Select path**, and go to the category to be used as a filter, and then click the **Confirm** button. + 1. If stored externally, in the **Path** field manually enter the path to the category, and then click the **Add** button. + +1. If your collaborative scenario uses the end user’s history as context, like, for example, **Also clicked - user**, enter an end user identifier in the **User id** field, for example, 500. + +1. If your scenario has the use of [submodels](recommendation_models.md#submodels) enabled, in the **Custom parameters** field, enter the phrase that defines a set of items based on a specific attribute, for example "material=wood", and then click the **Add** button. + +1. Click **Send request** to display the results. + +!!! note "Display response" + + You can preview the exact data object that is returned from the Personalization server and then used by the Personalization service to generate the response. + To see the data object, click **See response code**. diff --git a/docs/personalization/recommendation_models.md b/docs/personalization/recommendation_models.md new file mode 100644 index 00000000..420f52aa --- /dev/null +++ b/docs/personalization/recommendation_models.md @@ -0,0 +1,270 @@ +--- +description: Models are building blocks to recommendation scenarios. They let you define which criteria to take into account when calculating recommendations. +month_change: false +--- + +# Recommendation models + +Recommendations that are valuable in [real-life situations](use_cases.md) are generated using [scenario strategies](scenarios.md) that consist of algorithms (models). +Models are statistics-based and perform calculations based on information about [content](content_types.md), users, and [events](event_types.md) in which they're involved. +Calculations run in the background and the results are updated regularly to provide the most accurate recommendations. +Models come predefined with the service, based on the arrangements that your organization makes with [[= product_name_base =]] when defining the initial configuration. +You can request that a specific model is created by contacting customer support. + + +If your [user role](../permission_management/permissions_and_users.md) includes the `Personalization/Edit` policy, you can modify the models according to your requirements. +To do this, navigate to the **Models** tab and click the **Edit** icon next to a name of the model. + +You may have permissions to access several websites hosted on an [[= product_name =]], [with independent results returned for each of these websites](use_cases.md#multiple-website-hosting). +If this is the case, use the selector field to switch between views for each of these websites. + +## Model types + +There are several types of models available, however, the distinction between types isn't visible in the user interface. + +### Popularity models + +Basic popularity recommendations, such as "Top purchased", "Top consumed" or "Top clicked". +Models from this category return the most popular content items/products, based on a weighted overall usage history (recent events are more important) and category-based filtering (bestsellers in the selected category and/or subcategories). + +#### Predictive + +A predictive popularity model predicts users' purchase behavior and trends, and recommends items based on this behavior. +The model analyzes trends within a configured time period (for example, within a 30-day timeframe), predicts that a new item may have the same trend, and displays the predicted item in recommendations. + +### Collaborative models + +These models are more complex and require combining data from different sources. + +#### Also clicked / purchased + +This type of recommendation is often called "Collaborative filtering based on user data" and is a proven, powerful approach to calculating recommendations. +It recommends products that are usually clicked or purchased together. +It's straightforward to configure and needs no maintenance. + +#### Ultimately bought + +This model combines CLICK and BUY events. +It suggests alternative products, which customers purchased after they clicked the selected product. +It therefore provides a "matching factor" of searching and purchasing. +In contrast to the "Also purchased" model, it recommends products that are related, but not purchased together. +This model is the best choice to suggest alternative products for their search. +For example, when a user finds a book and the same book is being recommended on the product page, it means that other users with the same interest purchased this book (and not others), which hints that this book is the best choice. + +#### Frequently bought together / Bundle recommendations + +Products that were bought in a combination for a certain number of times can be recommended as a bundle. +This model can recommend other products that fit the one that the user is currently looking at. + +For example, when a user navigates to a product page with a certain smartphone, apart from the "Also clicked" recommendations, the Personalization service could recommend the *Smartphone + Cover + Headphones* bundle, because they were purchased together in exactly this combination several times. + +It's not guaranteed that there is a bundle available for every product. +Therefore, the rendering logic should display the recommendations if they're available, or leave the bundle box out completely. +The currently displayed product is always part of the bundle. + +#### Similar rated + +The "Similar rated" model provides recommendations based on user preferences. +It predicts articles that might suit the user's interests. +Recommendations for articles similar to their dislikes are suppressed. + +#### Best rated + +This model provides recommendations based on algorithms that include the ranking values and the amount of distinct ratings. +It's best suited for landing or category pages. + +## Editorial and other models + +#### Recently added + +This model returns a list of items from the recently added items in a configured time period. +For example, if you set item age to 10 days, the model returns items which were added to the database 10 days ago (recently added items). + +It allows injecting new items (products, articles, an so on), to the recommendation while the "History-based" models are yet unable to recommend products based on the statistics. +It's a simplified and unsophisticated alternative if no other information is available to calculate and provide recommendations. + +![Item age](img/recently_added_item_age.png "Item age") + +This model isn't based on historical records but relies on the imported product catalog. + +#### Editor-based + +This model returns products from a list that you manually create if you have `Personalization/Edit` policy. +This way you can replace automatically generated recommendations with ones from a predefined list. +It's best suited for cases when the store administrator wants to add special offers or sell older stock. +It could be referred to as "Static recommendations". + +#### Blacklist + +Items from this list aren't recommended in any scenario. +The model can be configured manually by a user. +You can use this model to exclude test products or products that are used for system monitoring. +An element added to this list is never recommended so it must be treated with care, because the blacklist model applies to all scenarios that exist in the system. + +#### History-based + +Pseudo recommendation model that shows the user products from their own history. +For example, the "You have just watched" box. + +#### Recurring purchase + +A recurring purchase model recognizes purchase patterns and returns recommendations for items where these patterns can occur. +This model is based on predictable purchase occurring at regular intervals going forward with a relatively high degree of certainty. +The model recommends items which are suitable for this pattern. Item recommendations are displayed 20% before the completion of estimated time pattern of repeating purchasing the product. + +It means, for example, that if the pattern covers 100 days, when the optimal time comes from day 80., the recommendation begins to display. When a user purchases the recommended item on day 92., the recommendation is no longer shown and the counter resets. + +!!! tip + + Minimum time period for this model is 4 days, but the model works better if you set a longer time period. + +### B2B model + +This model shows which items were recently clicked or bought for a particular segment group of a company. +B2B models work for a group of users, not for an individual user, and are considered [segment](segment_management.md) models. + +!!! note + + To get recommendations for the specified segment, in the request, pass the parameter only for this segment. + B2B requests are limited to only one segment ID. + + +#### Last events B2B models + +This model is built on the fly, and requires an access to the most recent events to work. +There are two types of B2B last models: + +- B2B last clicked - returns the actual recent items which were clicked by a user with the same `segment ID`. For example, two users from the same `segment ID` can see the last clicked items by anyone from the same `segment ID`. + +- B2B last purchased - works the same as last clicked, however, returns actual bought items. +The maximum time from which events can be fetched is 10 days. + +### B2B recurring purchase model + +This model is built on the fly. It anticipates and predicts purchase of products that were bought recursively within the same `segment ID`. +The item appears in this model for recommendation only when it was purchased at least twice by users from the same `segment ID` +in the configured timeframe. + +B2B recurring purchase models predict the date of the next purchase based on an average demand per day, extrapolated from BUY events. +The higher relevance of the item, the closer predicted date of the next purchase is. +The item starts to appear when the time interval is covered in 80% between the date of the last purchased and predicted date of the next purchase. + +For example, if the time interval is set to 10 days and the next purchase is predicted after these 10 days, recommendations are displayed two days before that date. + +## Submodels + +Statistics-based recommendations often have the disadvantage of providing recommendations limited to the most popular, most suitable to the user, or most similar products. +You might want to extend the set of available recommendations by defining a subset of items based on external criteria. + +Submodels give you the option to group products based on an attribute. +Recommendations can then be requested specifically for the selected group. +For example: + +- "Also bought clothing with similar colors" +- "Most popular toys for the predefined age" +- "Also bought presents with a predefined price" + +Submodels must be manually configured. +You do this in the property dialog of the recommendation model. +After you configure the submodel, the results are generated overnight and are available on the next day. + +Once configured, submodels are enabled for the model globally. +All the scenarios which use this model also use the submodel. +If you don't want to group recommendations based on a certain attribute, remove the attribute parameter from the request. +The submodel is then omitted. + +!!! note "Multiple submodels in recommendations" + + You can combine recommendations from two different submodels, regardless of their type, within a single recommendation call. + A response to such call contains only recommendations that come from both submodels at the same time. + For more information, see [Customizing the recommendation request]([[= developer_doc =]]/personalization/api_reference/recommendation_api/#submodel-parameters) in Developer Documentation. + +### Nominal attributes + +A nominal attribute-based submodel works when the number of values of an attribute is relatively small and there is a large group of products for every value. +A good example would be clothes colors in a clothing store, while authors in a book store would make a bad example (there are too many of them). + +When configuring submodels for a clothing store, you might want to get recommendations for a specific color, either predefined or a color of the context item. +Similar colors can be grouped together, as shown below: + +![Attribute example](img/attribute_example.png "Attribute grouping example") + +The following results are possible for the products shown in the diagram: + +|Attribute from the recommendation request|Result| +|---|---| +|color=lime|Value "lime" is found in the first group. There are products in this group. If a model has any of them, they're recommended.| +|color=sand|Value "sand" is found in the fourth group. There are no products in the group, therefore nothing is recommended by this model. The fallback model could be used if configured.| +|color=white|Value "white" can't be found in any of groups. The main model is used. Items from all submodel groups can appear in the result (as if the submodels weren't configured at all).| +|no attribute specified|The main model is used. The request is handled as if submodels weren't configured at all. Products from the whole store could appear in the recommendation list.| + + +### Numeric attributes + +In numeric attribute-based submodels you define subgroups by setting `from` and `to` limits for every group. + +The logic used for resolving a submodel is as follows: + +- The `from` value indicates the beginning of the range and is included in the subgroup. +- The `to` value indicates the end of the range end and is excluded from the subgroup. + The only exception is the last of the ranges, where the `to` value is also included. + +!!! note + + You can specify a single or multiple attributes with multiple values for requesting recommendations. + Recommendation are fetched from all the submodels and merged based on the weight (relevance). + If one of the submodels delivers recommendations with better relevance, the results of other models can disappear from the list. + +### Dynamic attributes + +Dynamic attribute submodels eliminate the need for manual grouping and simplify configuration. +They allow for simpler, faster, and less demanding recommendation models building using different attributes, because all you need to do is make one request and rebuild the model. + +They work best in straightforward cases when you filter by the value of the attribute. + +Dynamic attribute submodels: + +- operate only on [nominal attributes](#nominal-attributes) (numeric attributes are not supported) +- can be used for [popularity](#popularity-models) and [collaborative](#collaborative-models) types of models (as they support submodels) +- have limitation of max. 50 attribute values (if more, you need to follow the procedure of manual configuration by [[= product_name_base =]] Team) +- operate on scenarios with the selected `Submodels` data type option +- require sending a request and building a model +- are calculated for all new attribute values after import +- are always up-to-date with the imported items +- still add new values ​​when attributes are only partially grouped manually +- aren't added if all attributes are manually grouped (full manual intervention) +- cannot be calculated if there is any submodel manually configured for provided attribute +- don't operate on the values which are no longer present + +!!! note "Enable dynamic attribute" + + Dynamic attribute must be enabled by [[= product_name_base =]] Team. + To start using this functionality, contact customer support (support@ibexa.co). + +!!! caution "Unused attributes" + + If an attribute is not used for at least 5 days, all related submodels are removed. + +## Time-slot based models + +Time-slot based models consider only a particular range of time rather than the full day when calculating recommendations. +They can be used for [popularity](#popularity-models) and [collaborative](#collaborative-models) types of models. + +These models can be an optimum answer for customers who notice variable consumption of their content or products throughout the day, with different content being popular, for example, in the morning and afternoon. +Time-slot based models can cover these needs, as you can request to configure and set specific time slots. + +In these models, recommendations are created for both configured time slots and for the main model (for example, for the last 30 days). +However, time-slot based recommendations are shown as priority in the hours for which time slots are configured (if requested in a recommendation call). + +These time slots: + +- can cover any time frame, including minutes (for example, 11 A.M. - 3:30 P.M.), and don't necessarily have to start and end at full hour +- cannot overlap, for example, you cannot set slots 8 A.M. - 11 A.M. and 9 A.M. - 12 A.M. at once +- cannot span between two days, for example, you cannot set a slot to 11 P.M. - 3 A.M. + +To use time slot-based models, this feature must be enabled. + +!!! note "Enable time slots" + + Time slots must be enabled and configured by [[= product_name_base =]] Team. + To start using this functionality and request that a specific model is created, contact customer support (support@ibexa.co). diff --git a/docs/personalization/review_perso_performance.md b/docs/personalization/review_perso_performance.md new file mode 100644 index 00000000..ba489519 --- /dev/null +++ b/docs/personalization/review_perso_performance.md @@ -0,0 +1,46 @@ +--- +description: You can view the performance and statistical information about the Personalization service in the Personalization dashboard. +--- + +# Review performance + +You can review statistical information related to the functioning of the Personalization service, to help you fine-tune [models](recommendation_models.md) and [scenarios](scenarios.md) and, in consequence, achieve better financial results. +You can do this by visiting the dashboard, where you can monitor the performance of the Personalization service. + +The dashboard consists of several sections: + +- The top section contains tiles with the most important metrics, such as a number of recommendation calls, or number of successful recommendations. +- The diagrams section presents statistical information on how the Personalization service is used and how successful recommendations are, depending on key performance indicators. +- The bottom section is made up of tables with detailed information, such as the most popular items. + +!!! note "Host multiple websites" + + If you have [permissions](../permission_management/permissions_and_users.md) to access several websites hosted on an [[= product_name =]] instance, you can use the selector field to switch between dashboards for each of these websites. + +## Statistical information + +The diagram part consists of four main blocks: + +- Revenue: + The effectiveness of clicked recommendations in terms of revenue or the number of purchases. +- Recommendation calls: + The number of recommendation calls (total and per scenario). +- Conversion rate: + The absolute number of converted/sold recommendations. +- Collected events: + Input data CLICK, BUY, and other events that the Personalization service collects from the website. + For more information, see [Events](event_types.md). + +![Diagrams on the dashboard](img/dashboard_statistics.png "Performance diagrams on the dashboard") + +Revenue-through-recommendations is an additional monetary value that resulted from the clicked recommendations. +It's calculated by summing up the revenue coming from products that users have purchased within 30 minutes from clicking a recommendation. + +Purchased recommendations is the number of products sold, without any revenue/price information. + +Conversion (or click-through) rate is an indicator of the acceptance and, subsequently, the quality of recommendations.  +It's calculated by dividing the total number of clicked recommendations by the number of recommendation calls. +This statistic delivers reliable information if event tracking is implemented correctly. + +You can select a timeframe for the diagrams from a list of presets, or define a custom date range. +If necessary, you can download the statistical information in XLS format. diff --git a/docs/personalization/scenarios.md b/docs/personalization/scenarios.md new file mode 100644 index 00000000..46a3be41 --- /dev/null +++ b/docs/personalization/scenarios.md @@ -0,0 +1,41 @@ +--- +description: Scenarios define which recommendation results should be given in different situations. +--- + +# Scenarios + +A scenario is a configuration that is used to obtain recommendation results based on the results generated by [models](recommendation_models.md). + +It consists of: + +- A [type of content](content_types.md) to be returned as recommendation  +- A strategy (set of models) that is used for generating recommendations +- [Filter](filters.md) configuration + +For information about scenario configuration, see [Configure scenarios](configure_scenarios.md). + +## Types of content + +Scenarios support a single input type and multiple output types. +Every recommendation request can deliver content of one or all output types of content. +The output type is set during the recommendation request and must be covered by the list of the supported types of content in the requested scenario. + +### Cross content type recommendations + +You can use cross content type option to get combined recommendation items from different types of content. + +Cross content type option is used to combine best recommendation items from different types of content. +It applies to scenarios which have more than one output type configured. + + +## Strategy + +A strategy is a structure made up of models that are arranged by importance. +There are different levels of importance - a primary level and several fallback ones. +Models from each level are used in parallel and strategy results contain an equally distributed mixture of both model results. +If models from one level do not return enough results, models from the subsequent levels are used. + +## Filters + +Filters are tools that you can use to eliminate, demote or promote specific recommendation results. +They're applied to all recommendations that come from models selected in the strategy. diff --git a/docs/personalization/segment_management.md b/docs/personalization/segment_management.md new file mode 100644 index 00000000..31fbfdbc --- /dev/null +++ b/docs/personalization/segment_management.md @@ -0,0 +1,202 @@ +--- +description: Manage segments and combine segment groups to get personalized content targeted at your clients. +--- + +# Segment management + +Segments allow getting personalized content suitable for particular user groups. +They compute models based on the segment attribute factor. +Information about user segment is provided in each event which comes from the tracking script. + +## Configure segments + +With segment groups you can assign users to different recommendation groups based on data gathered, and deliver recommendations to these user groups. + +The **Segment** list displays only active segments and is generated from the events collected for relevant history (the actual data from recommendation engine, not what was added in the back office). + +The value of each segment is transferred to the event. + +Models are displayed only for a selected period of time. +If a group is inactive for a certain time, the segments get an `Inactive` status and can't be used. + +![Time period](img/models_time_period.png "Time period configuration") + +### Operators and segmentation logic + +Segmentation logic in segment groups allows you to divide target audience according into their specific traits, for example, demographic, behavior, or age, to provide narrowed and better tailored recommendations. +You can build complex segment groups using parent and nested (child) segments connected with operators which enable precise filtering. + +With operators you can establish filtering rules for recommendations based on segments, and create nested groups within parent groups. + +!!! tip + + You can add an unlimited number of children in one parent group. + +- **AND** - use when you want to intersect two or more values for a particular segment. All set conditions must be met. +- **OR** - use when you want to broaden results, one of the conditions must be fulfilled. + +Nested (child) segments can have different conditions from their parent. However, the relation between parent and child is always `AND`. +Use them to create sub-segment groups which narrow down filtering of recommendations to specific traits of your users. + +Segments available in the **Elements** sections are reusable. It means you can use the same segment in different segment groups. + +![Parent segment group](img/perso_segment_group_and_parent.png "Parent segment group") + +### Create segment group with AND logic condition + +The following example shows segment groups with `AND` operators linking nested elements: + +- women +- Poland +- sales hunters (as a type of customer) + +![AND segment group logic](img/perso_segment_group_sales_hunters.png "AND segment group logic") + +All three criteria are linked with and `AND` operator, so all conditions must be fulfilled. + +A recommendation call in a scenario that uses a model with segments contains requests to all specified segments with `AND` conditions: + +`https://reco.perso.ibexa.co/api/v2/41307/588/landing_page?numrecs=6&attribute=ses_name,title,ses_image,teaser_image&crosscontenttype=1&segments=7,11,14` + +Where segments ID correspond to segment groups: + +- women - `segment ID=7` +- Poland - `segment ID=11` +- sales hunters - `segment ID=14` + +As a result, a recommendation call returns two events which qualify for these segment groups requirements. +Two items with `ID=587` and `ID=588` are relevant for the following segment combinations, clicked by: + +- for women from Poland + +and + +- for sales hunters. + +??? "Recommendation call response" + + ```json hl_lines="5 28" + { + "contextItems": [], + recommendationItems: [ + { + itemId: 587, + itemType: 57, + relevance: 1, + links: { + clickRecommended: "//event.perso.ibexa.co/api/41307/clickrecommended/someuser/57/587?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=276a5930-dea3-11ed-8cdf-92a64ae30943", + rendered: "//event.perso.ibexa.co/api/41307/rendered/someuser/57/587?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=276a5930-dea3-11ed-8cdf-92a64ae30943" + }, + attributes: [ + { + key: "title", + values: [ + "Woods edge living room" + ] + }, + { + key: "teaser_image", + values: [ + "/var/site/storage/images/4/5/7/0/754-1-eng-GB/245d16d84164-living-room3.jpg" + ] + } + ] + }, + { + itemId: 588, + itemType: 57, + relevance: 1, + links: { + clickRecommended: "//event.perso.ibexa.co/api/41307/clickrecommended/someuser/57/588?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=276a5930-dea3-11ed-8cdf-92a64ae30943", + rendered: "//event.perso.ibexa.co/api/41307/rendered/someuser/57/588?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=276a5930-dea3-11ed-8cdf-92a64ae30943" + }, + attributes: [ + { + key: "title", + values: [ + "Minimalist luxury in a small and stylish bedroom" + ] + }, + { + key: "teaser_image", + values: [ + "/var/site/storage/images/0/0/7/0/700-1-eng-GB/de8a98767362-bedroom2.jpg" + ] + } + ] + } + ] + } + ``` + +### Create segment group with OR logic condition + +The following example shows segment groups with `OR` operator connecting nested elements: + +- women +- Poland +- 25–35 (age) +- Germany + +![OR segment group logic](img/perso_segment_group_or.png "OR segment group logic") + +In this case to get recommendations, only one condition must be met: women from Poland or women from Germany. + +`https://reco.perso.ibexa.co/api/v2/41307/someuser/landing_page?numrecs=6&attribute=ses_name,title,ses_image,teaser_image&crosscontenttype=1&segments=7,8,10,11` + +Where segments ID correspond to segment groups: + +- women - `segment ID=7` +- Poland - `segment ID=11` +- 25–35 - `segment ID=8` +- Germany - `segment ID=10` + +As a result, a recommendation call returns only one event which qualifies for these segment group requirements. +The item with `ID=587` is relevant for this segment combination, clicked by: + +- women from Poland at age 25–35 + +or + +- by women from Germany at age 25–35 + +??? "Recommendation call response" + + ```json hl_lines="5" + { + "contextItems": [], + recommendationItems: [ + { + itemId: 587, + itemType: 57, + relevance: 1, + links: { + clickRecommended: "//event.perso.ibexa.co/api/41307/clickrecommended/someuser/57/587?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=7ff8c8b0-e282-11ed-9a93-aefcc75529b6", + rendered: "//event.perso.ibexa.co/api/41307/rendered/someuser/57/587?scenario=landing_page&modelid=10316421&categorypath=&requestuuid=7ff8c8b0-e282-11ed-9a93-aefcc75529b6" + }, + attributes: [ + { + key: "ses_name", + "values": [] + }, + { + key: "title", + values: [ + "Woods edge living room" + ] + }, + { + key: "ses_image", + "values": [] + }, + { + key: "teaser_image", + values: [ + "/var/site/storage/images/4/5/7/0/754-1-eng-GB/245d16d84164-living-room3.jpg" + ] + } + ] + } + ] + } + ``` \ No newline at end of file diff --git a/docs/personalization/triggers.md b/docs/personalization/triggers.md new file mode 100644 index 00000000..f9b76735 --- /dev/null +++ b/docs/personalization/triggers.md @@ -0,0 +1,54 @@ +--- +description: Triggers enable sending recommendations as push messages to customers. +--- + +# Triggers + +Triggers are push messages delivered to end users, for example, through email. +With triggers, you can increase the engagement of your visitors and customers by delivering recommendations straight to their mailboxes. +As a store manager, you can expect bigger income, and improved fulfillment of customer needs. +All this while saving time and effort. + +## Trigger types + +[[= product_name =]] lets you use several triggers, including the following ones: + +- Abandoned basket trigger: Personalization engine monitors the user's cart and pushes a message when cart status remains unchanged for a set time. +The message contains items that have been abandoned in the cart. +The Personalization service monitors [events](event_types.md) to avoid recommending items that the end user has bought or removed from basket. + +- Reactivation aka. "We miss you" trigger: Personalization engine monitors the user's overall activity and pushes a message when they haven't returned to the site for a set time. +Recommendations are generated based on the user's purchasing and browsing history. + +- Price drop trigger: Personalization engine monitors the user's wishlist and pushes a message when a price of the product that has been put there decreases. + +- Post visit trigger: Personalization engine monitors the user's browsing activity and pushes a message with products that are similar to the ones the customer has looked at. + +## Trigger calculation frequency + +Personalization engine checks user context data against trigger conditions every night. +Trigger messages are automatically initiated when a specific user's action, inaction or pattern of actions meet certain conditions that are defined in the service. + +## Configuring triggers + +Trigger message calculations are done on a server that is run and maintained by [[= product_name_base =]]. +The server delivers a response with recommendations to an endpoint provided by your organization, for example, an [[= product_name_connect =]] [webhook](https://doc.ibexa.co/projects/connect/en/latest/tools/webhooks/). +You may then deliver the message to the end users using a method of your choice, for example, email. +Apart from a list of recommendations, the response can include an email address for routing a message to the recipient. + +To enable triggers for your organization, contact your administrator or development team about [preparing a webhook address and processing the response delivered to the webhook]([[= developer_doc =]]/personalization/integrate_recommendation_service/#send-messages-with-recommendations), and [[= product_name_base =]] about the configuration specifics. + +You can define one or more triggers of certain type, to support different use cases. +For each trigger type, you need to decide on several crucial parameters, for example: + +- one or more [types of content](content_types.md) +- [attributes](recommendation_models.md#nominal-attributes) to be included in the response +- time that must pass before messages start being sent +- number of repetitions +- message frequency +- number of recommended items +- what events set off the trigger +- what [recommendation models](recommendation_models.md), together with their context, are used to calculate the response. +"Also purchased", "Also clicked", and "Top purchased" are used by default. + +If you don't decide otherwise, trigger recipients are selected based on an analysis of BUY and TRANSFER events, except for the "Price drop" trigger, where the WISHLIST event is analyzed. diff --git a/docs/personalization/use_cases.md b/docs/personalization/use_cases.md new file mode 100644 index 00000000..d811f8b1 --- /dev/null +++ b/docs/personalization/use_cases.md @@ -0,0 +1,55 @@ +--- +description: The Personalization service can be used for content publishing and for ecommerce, taking into account both shop-related and content-related user behaviors. +--- + +# Use cases + +There are different areas where recommendations can prove valuable from a business point of view. +The most common ones are eCommerce and content publishing. + +## eCommerce + +In eCommerce, recommendations can help website visitors find the exact product that fulfils their expectations. +When a user is not sure about what to purchase, recommendations can suggest similar, alternative, or complementary products. +Some typical use cases are: + +- The bestseller list shown on a home page +- The "What other customers bought" and "Frequently bought together" lists on a product detail page +- The "Related to your shopping cart" list on the shopping cart page +- The "Bestsellers in the current category" list shown on the category's landing page +- A recommendation bar with recommendations based on the current user's profile +- An email with recommendations based on the contents of an abandoned shopping cart + +![Recommendations on a home page](img/use_case_landing_page.png "Recommendations on a home page") + +Each recommendation box in the graphics above and below represents a [scenario](scenarios.md). +Scenarios are configurations that define what kind of recommendations should be delivered. + +![Related products on a shopping cart page](img/use_case_shopping_basket.png "Related products on a shopping cart page") + +## Content publishing + +In publishing, recommendations bring indirect value by keeping users on the website. +Unlike in eCommerce, publishers often provide content for free and are financed from advertisements. +Increasing the click-through (or conversion) rate to increase profits from advertisements is one of the drivers here. + +Use cases in publishing can be the following: + +- A list of the most popular content shown on the home page +- The "Bestsellers in the current category" list shown on the category's landing page +- Related content shown on the content detail page + +![Similar products on a product detail page](img/use_case_detail_page.png "Similar products on a product detail page") + +## Multiple website hosting + +If your [[= product_name =]] instance hosts multiple websites, you can configure the Personalization service to provide independent recommendations for each of these websites. + +This can eliminate irrelevant recommendations when there are: + +- Multiple websites that belong to different customers +- Both eCommerce and content publishing websites +- Multiple localized versions of the same digital presence +- Several eCommerce websites operating under different brands + +To get independent results for different websites, you must [set up](enable_personalization.md) and [configure](configure_personalization.md) the service separately for each of these websites. diff --git a/mkdocs.yml b/mkdocs.yml index 4fc91d71..02c38d17 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -96,6 +96,28 @@ nav: - Discounts: - Discounts: commerce/discounts/discounts.md - Work with Discounts: commerce/discounts/work_with_discounts.md + - Personalization: + - Personalization: personalization/personalization.md + - Use cases: personalization/use_cases.md + - Enable personalization: personalization/enable_personalization.md + - Configure personalization: + - Configure personalization: personalization/configure_personalization.md + - Configure models: + - Configure models: personalization/configure_models.md + - Segment management: personalization/segment_management.md + - Recommendation models: + - Recommendation models: personalization/recommendation_models.md + - Events: personalization/event_types.md + - Configure scenarios: personalization/configure_scenarios.md + - Scenarios: + - Scenarios: personalization/scenarios.md + - Types of content: personalization/content_types.md + - Filters: personalization/filters.md + - Triggers: personalization/triggers.md + - Preview scenario results: personalization/preview_scenario_results.md + - Integrate scenario results: personalization/integrate_scenario_results.md + - Import source data: personalization/content_import.md + - Review performance: personalization/review_perso_performance.md - Ibexa Engage: - Ibexa Engage: ibexa_engage/ibexa_engage.md - DAM: diff --git a/plugins.yml b/plugins.yml index 23c69cca..0bc83bb2 100644 --- a/plugins.yml +++ b/plugins.yml @@ -35,28 +35,11 @@ plugins: 'shop_administration/customer_portal.md': 'customer_management/customer_portal.md' 'shop_administration/company_self_registration.md': 'customer_management/company_self_registration.md' 'search.md': 'search/search_for_content.md' - 'personalization/enabling_personalization.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide' - 'personalization/perso_configuration.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/previewing_scenario.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/integrating_results.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/dashboard.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/use_cases.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/enable_personalization.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/configure_personalization.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/configure_models.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/segment_management.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/recommendation_models.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/event_types.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/configure_scenarios.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/scenarios.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/content_types.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/personalization.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/filters.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/triggers.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/preview_scenario_results.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/integrate_scenario_results.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/content_import.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' - 'personalization/review_perso_performance.md': 'https://doc.ibexa.co/en/latest/recommendations/raptor_integration/raptor_connector_guide/' + 'personalization/enabling_personalization.md': 'personalization/enable_personalization.md' + 'personalization/perso_configuration.md': 'personalization/configure_personalization.md' + 'personalization/previewing_scenario.md': 'personalization/preview_scenario_results.md' + 'personalization/integrating_results.md': 'personalization/integrate_scenario_results.md' + 'personalization/dashboard.md': 'personalization/review_perso_performance.md' 'shop_administration/manage_users.md': 'customer_management/manage_customers.md' 'site_organization/site_factory.md': 'website_organization/work_with_sites.md' 'shop_administration/shop_administration.md': 'persona_paths/shop_manager.md'