diff --git a/docs/managing_shop_content/embed_product.md b/docs/managing_shop_content/embed_product.md new file mode 100644 index 00000000..b3b3f7e4 --- /dev/null +++ b/docs/managing_shop_content/embed_product.md @@ -0,0 +1,30 @@ +# Embed product + +You can embed products in a RichText Field using the Embed function. +The product is embedded in a box including an add to basket button and a product image. The text floats around the product box. + +![](img/embed_products.png) + +## Embed a product slider + +If you want to embed more than one product inside a RichText Field, use the Product card function: + +![](img/embed_product_slider.png) + +![](img/embed_input_fields.png) + +### Box type + +eZ Commerce offers the following types of box designs: + +- Slider + +![](img/embed_design_slider.png) + +- Box with add to basket + +![](img/embed_add_to_basket.png) + +### Slider title + +The title is used only if you choose "Type of product box" as "Slider". It is displayed as a tab. diff --git a/docs/managing_shop_content/img/bestsellers_categories.png b/docs/managing_shop_content/img/bestsellers_categories.png new file mode 100644 index 00000000..724a9d90 Binary files /dev/null and b/docs/managing_shop_content/img/bestsellers_categories.png differ diff --git a/docs/managing_shop_content/img/bestsellers_preview.png b/docs/managing_shop_content/img/bestsellers_preview.png new file mode 100644 index 00000000..7d6fa8ed Binary files /dev/null and b/docs/managing_shop_content/img/bestsellers_preview.png differ diff --git a/docs/managing_shop_content/img/bestsellers_slider.png b/docs/managing_shop_content/img/bestsellers_slider.png new file mode 100644 index 00000000..3cfee7a2 Binary files /dev/null and b/docs/managing_shop_content/img/bestsellers_slider.png differ diff --git a/docs/managing_shop_content/img/content_list.png b/docs/managing_shop_content/img/content_list.png new file mode 100644 index 00000000..4969d213 Binary files /dev/null and b/docs/managing_shop_content/img/content_list.png differ diff --git a/docs/managing_shop_content/img/content_list_blog.png b/docs/managing_shop_content/img/content_list_blog.png new file mode 100644 index 00000000..eec36140 Binary files /dev/null and b/docs/managing_shop_content/img/content_list_blog.png differ diff --git a/docs/managing_shop_content/img/embed_add_to_basket.png b/docs/managing_shop_content/img/embed_add_to_basket.png new file mode 100644 index 00000000..7ec39c5b Binary files /dev/null and b/docs/managing_shop_content/img/embed_add_to_basket.png differ diff --git a/docs/managing_shop_content/img/embed_design_slider.png b/docs/managing_shop_content/img/embed_design_slider.png new file mode 100644 index 00000000..cd6043b9 Binary files /dev/null and b/docs/managing_shop_content/img/embed_design_slider.png differ diff --git a/docs/managing_shop_content/img/embed_input_fields.png b/docs/managing_shop_content/img/embed_input_fields.png new file mode 100644 index 00000000..f96e56d8 Binary files /dev/null and b/docs/managing_shop_content/img/embed_input_fields.png differ diff --git a/docs/managing_shop_content/img/embed_product_slider.png b/docs/managing_shop_content/img/embed_product_slider.png new file mode 100644 index 00000000..0c2a88d0 Binary files /dev/null and b/docs/managing_shop_content/img/embed_product_slider.png differ diff --git a/docs/managing_shop_content/img/embed_products.png b/docs/managing_shop_content/img/embed_products.png new file mode 100644 index 00000000..91897cb1 Binary files /dev/null and b/docs/managing_shop_content/img/embed_products.png differ diff --git a/docs/managing_shop_content/img/gallery_block.png b/docs/managing_shop_content/img/gallery_block.png new file mode 100644 index 00000000..e10d098f Binary files /dev/null and b/docs/managing_shop_content/img/gallery_block.png differ diff --git a/docs/managing_shop_content/img/home_page.png b/docs/managing_shop_content/img/home_page.png new file mode 100644 index 00000000..102d1b98 Binary files /dev/null and b/docs/managing_shop_content/img/home_page.png differ diff --git a/docs/managing_shop_content/img/landing_page.png b/docs/managing_shop_content/img/landing_page.png new file mode 100644 index 00000000..11999fbd Binary files /dev/null and b/docs/managing_shop_content/img/landing_page.png differ diff --git a/docs/managing_shop_content/img/landingpage_tool.png b/docs/managing_shop_content/img/landingpage_tool.png new file mode 100644 index 00000000..90041467 Binary files /dev/null and b/docs/managing_shop_content/img/landingpage_tool.png differ diff --git a/docs/managing_shop_content/img/legal_checkout.png b/docs/managing_shop_content/img/legal_checkout.png new file mode 100644 index 00000000..6bfd7b99 Binary files /dev/null and b/docs/managing_shop_content/img/legal_checkout.png differ diff --git a/docs/managing_shop_content/img/legal_contact.png b/docs/managing_shop_content/img/legal_contact.png new file mode 100644 index 00000000..d65a135d Binary files /dev/null and b/docs/managing_shop_content/img/legal_contact.png differ diff --git a/docs/managing_shop_content/img/legal_controller.png b/docs/managing_shop_content/img/legal_controller.png new file mode 100644 index 00000000..a8817236 Binary files /dev/null and b/docs/managing_shop_content/img/legal_controller.png differ diff --git a/docs/managing_shop_content/img/legal_embed.png b/docs/managing_shop_content/img/legal_embed.png new file mode 100644 index 00000000..ced3941e Binary files /dev/null and b/docs/managing_shop_content/img/legal_embed.png differ diff --git a/docs/managing_shop_content/img/legal_footer.png b/docs/managing_shop_content/img/legal_footer.png new file mode 100644 index 00000000..1a42832d Binary files /dev/null and b/docs/managing_shop_content/img/legal_footer.png differ diff --git a/docs/managing_shop_content/img/legal_register.png b/docs/managing_shop_content/img/legal_register.png new file mode 100644 index 00000000..2d07b5c0 Binary files /dev/null and b/docs/managing_shop_content/img/legal_register.png differ diff --git a/docs/managing_shop_content/img/legal_service.png b/docs/managing_shop_content/img/legal_service.png new file mode 100644 index 00000000..7a5b84f4 Binary files /dev/null and b/docs/managing_shop_content/img/legal_service.png differ diff --git a/docs/managing_shop_content/img/legal_terms_and_conditions.png b/docs/managing_shop_content/img/legal_terms_and_conditions.png new file mode 100644 index 00000000..f3bdf930 Binary files /dev/null and b/docs/managing_shop_content/img/legal_terms_and_conditions.png differ diff --git a/docs/managing_shop_content/img/media.png b/docs/managing_shop_content/img/media.png new file mode 100644 index 00000000..b46163ef Binary files /dev/null and b/docs/managing_shop_content/img/media.png differ diff --git a/docs/managing_shop_content/img/media_uplodad_images.png b/docs/managing_shop_content/img/media_uplodad_images.png new file mode 100644 index 00000000..0ab5d211 Binary files /dev/null and b/docs/managing_shop_content/img/media_uplodad_images.png differ diff --git a/docs/managing_shop_content/img/navigation_content_structure.png b/docs/managing_shop_content/img/navigation_content_structure.png new file mode 100644 index 00000000..d70389d5 Binary files /dev/null and b/docs/managing_shop_content/img/navigation_content_structure.png differ diff --git a/docs/managing_shop_content/img/navigation_structure_menu.png b/docs/managing_shop_content/img/navigation_structure_menu.png new file mode 100644 index 00000000..3d4957b3 Binary files /dev/null and b/docs/managing_shop_content/img/navigation_structure_menu.png differ diff --git a/docs/managing_shop_content/img/product_slider.png b/docs/managing_shop_content/img/product_slider.png new file mode 100644 index 00000000..4df23bc0 Binary files /dev/null and b/docs/managing_shop_content/img/product_slider.png differ diff --git a/docs/managing_shop_content/img/product_slider_basic.png b/docs/managing_shop_content/img/product_slider_basic.png new file mode 100644 index 00000000..4af1fc43 Binary files /dev/null and b/docs/managing_shop_content/img/product_slider_basic.png differ diff --git a/docs/managing_shop_content/img/product_slider_preview.png b/docs/managing_shop_content/img/product_slider_preview.png new file mode 100644 index 00000000..089b7594 Binary files /dev/null and b/docs/managing_shop_content/img/product_slider_preview.png differ diff --git a/docs/managing_shop_content/img/select_image_folder.png b/docs/managing_shop_content/img/select_image_folder.png new file mode 100644 index 00000000..4beeabc3 Binary files /dev/null and b/docs/managing_shop_content/img/select_image_folder.png differ diff --git a/docs/managing_shop_content/img/silver_module.png b/docs/managing_shop_content/img/silver_module.png new file mode 100644 index 00000000..d120c9cf Binary files /dev/null and b/docs/managing_shop_content/img/silver_module.png differ diff --git a/docs/managing_shop_content/img/slider_block_view.png b/docs/managing_shop_content/img/slider_block_view.png new file mode 100644 index 00000000..a2cbcc28 Binary files /dev/null and b/docs/managing_shop_content/img/slider_block_view.png differ diff --git a/docs/managing_shop_content/img/slider_imgae_preview.png b/docs/managing_shop_content/img/slider_imgae_preview.png new file mode 100644 index 00000000..d22b304e Binary files /dev/null and b/docs/managing_shop_content/img/slider_imgae_preview.png differ diff --git a/docs/managing_shop_content/landingpages.md b/docs/managing_shop_content/landingpages.md new file mode 100644 index 00000000..52f81d6d --- /dev/null +++ b/docs/managing_shop_content/landingpages.md @@ -0,0 +1,47 @@ +# Pages in the shop + +eZ Commerce has at least one Landing Page which is the homepage. This document describes how to setup and modify Landing Pages. + +## Landing Page tool + +![](img/landingpage_tool.png) + +eZ Commerce adds the following blocks to the blocks available in eZ Platform: + +- Last viewed +- Bestsellers +- Product Slider + +## Product Slider + +The Product Slider block creates a product slider section with up to three different tabs. + +![](img/product_slider.png) + +Add up to three different tabs and fill them with the SKUs of the products (you can search for SKU, a product name or a part of a product name). + +![](img/product_slider_basic.png) + +Click **Submit** and you will see a preview of the slider. + +![](img/product_slider_preview.png) + +## Last viewed + +The Last viewed block displays a list of the last viewed products in a slider. + +![](img/slider_block_view.png) + +The block might not be visible in the edit mode but it will contain products in the frontend. + +## Bestsellers + +The Bestsellers block shows the bestselling products from a chosen category. This can be the whole product catalog or a subcategory. + +![](img/bestsellers_slider.png) + +To choose a category, click **Select content**. + +![](img/bestsellers_categories.png) + +![](img/bestsellers_preview.png) diff --git a/docs/managing_shop_content/legal_documents.md b/docs/managing_shop_content/legal_documents.md new file mode 100644 index 00000000..802f8051 --- /dev/null +++ b/docs/managing_shop_content/legal_documents.md @@ -0,0 +1,36 @@ +# Legal documents + +You can manage legal documents and forms for the shop in the "Service" folder. + +![](img/legal_service.png) + +You can link these legal documents in the footer: + +![](img/legal_footer.png) + +The legal documents are used at various places in the shop. The Terms and Conditions are shown as s full page or as a popup during the checkout process: + +![](img/legal_checkout.png) + +and in the register form: + +![](img/legal_register.png) + +The legal texts are linked in text modules that are used in various locations, e.g. the contact form. + +![](img/legal_contact.png) + +The cancellation policy text is added to the confirmation email from the shop. + +## Adding identifier to "Terms & Conditions" + +eZ Commerce extends the built-in Article Content Type with the Identifier Field. +With this identifier you can fetch the article and render the content using a controller. + +### Controller + +![](img/legal_controller.png) + +### Embed + +![](img/legal_embed.png) diff --git a/docs/managing_shop_content/navigation_structure.md b/docs/managing_shop_content/navigation_structure.md new file mode 100644 index 00000000..e4a4e928 --- /dev/null +++ b/docs/managing_shop_content/navigation_structure.md @@ -0,0 +1,22 @@ +# Navigation structure + +![](img/navigation_structure_menu.png) + +Click **Content** > **Content structure** to access the objects displayed in the top navigation + +![](img/navigation_content_structure.png) + +The following Content Types are supported: + +- Article +- Folder (including Folder for news, events and blog post) +- Landing page +- Product category +- Product +- Feature link + +!!! caution + + The main menu of the site displays elements only if the Priority is higher that 0. + +Elements with lower Priority are displayed first. diff --git a/docs/personalization/content_import.md b/docs/personalization/content_import.md new file mode 100644 index 00000000..cc5f65be --- /dev/null +++ b/docs/personalization/content_import.md @@ -0,0 +1,21 @@ +# 9. Content Import + +Basic recommendation algorithms are statistics-based and need only the product ID and user ID. This information is provided by the event tracking as described in chapter [4. Event Types](event_types.md). +There are several use cases where the recommendation engine requires additional information linked to the products. +The most important cases are: + +- Filtering results based on the category the product is located in ([Category Filter](filters.md#category-filter)) +- Filtering results based on price and product availability ([General Filters](filters.md#general-filters)) +- Sub-models based on custom attribute grouping ([Submodels](recommendation_models.md#submodels)) +- An additional export/import interface is designed to provide editor-based models ([6. Recommendation Models](recommendation_models.md)) + +There are four different ways to import data into the recommendation system: + +- **In-Event:** During the event tracking process, where related data is attached to a click event (e.g. categorypath information) +- **Push interface:** Classic HTTP POST-based import. It is suitable for uploading single content or editor lists +- **Pull interface:** The recommendation engine loads an exported file from the specified location in the background. It was designed to upload big portions of information, for example a weekly update of the whole product catalog +- **Trigger logic:** The recommendation engine triggers a transactional full import at the customer's system. Therefore some custom development or a plugin is needed.  + +!!! tip + + You can find Specification for Import interfaces in the developer guide under [Content API](https://doc.ezplatform.com/en/master/guide/personalization/content_api.md). diff --git a/docs/personalization/content_types.md b/docs/personalization/content_types.md new file mode 100644 index 00000000..66b9045f --- /dev/null +++ b/docs/personalization/content_types.md @@ -0,0 +1,33 @@ +# 5. Content Types + +In the **advanced** edition of the recommendation engine it is possible to build different recommendation domains. It can be achieved by splitting all the products into different content types. There are several possible use cases for content types. + +- A publisher tracks articles, pictures and videos as three different types. +- A supermarket splits all the products into food and non-food product groups. +- An owner of several web shops uses a single account for all of them + +The content types concept provides the possibility to make so-called cross domain recommendations (like "Users who watched this film also read this book" or "Users who read this article also liked these photos"). + +Additionally to the logical separation of the content domains the content types provide another important advantage. They play a role if different types of products are not equally popular but must be recommended equally often. For example, on a publisher's page users watch videos less often than they read articles. If the most popular products are requested without content type splitting, there will be most likely no videos in the result. If articles and videos are split into different content types, it is possible to explicitly request popular videos and/or popular articles. + +Below is a comparison for different ways of splitting content in the recommendation engine. + +|Use case|content types solution (domain context)|Attribute based sub-models (group context)|Different recommendation engine 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 content types share the scenario and model configuration|yes|yes|no| +|Required Recommender Edition|single advanced|-|multiple basic| + +#### Scenario configuration + +If multiple content types are enabled, one must enable this output type for every scenario that should recommend this type. + +![Scenario settings](img/scenario_configuration.png) + +Every scenario supports a single input type and multiple output types (see [8. Scenarios](scenarios.md)). Every recommendation request delivers only content of one output content type (even if multiple are selected in the interface above). The output type is set during the recommendation request and must be covered by the list of the supported content types in the requested scenario. + +You can find more information about fetching recommendations in developer documentation: [Recommendation API](https://doc.ezplatform.com/en/master/guide/personalization/recommendation_api.md) diff --git a/docs/personalization/dashboard.md b/docs/personalization/dashboard.md new file mode 100644 index 00000000..4b95b70b --- /dev/null +++ b/docs/personalization/dashboard.md @@ -0,0 +1,77 @@ +# 3. Dashboard + +The administration dashboard is the entry point to configure and control the Personalization Solution. It is split into two main sections: + +- The top section contains diagrams representing statistical information on how the recommendation engine is used and how successful - depending on the KPIs - recommendations are. +- The lower section is made up of many configuration tabs. It contains at least the Scenarios and Added revenue information. Depending on the license and registration information there is also a tab for A/B-Testing, Plugin, Content Import and Newsletter settings + +## Statistics + +![Dashboard statistics](img/dashboard_statistics.png) + +The diagram part consists of three main blocks: + +- Collected events: + The input data (clicks, buy, clickrecommended, ...) which is going into the recommendation engine for the customer website (see [4. Event Types](event_types.md) for more information). +- Recommendation calls: + The number of recommendation calls (total and per scenario) +- Clicked recommendations, Purchased recommendations and Revenue by recommendations: + The effectiveness of recommendations regarding clicked recommendations, revenue through recommendations and absolute number of converted/sold recommendations + +The conversion (or click-through) rate is an **indicator of the acceptance** and therefore the **quality of recommendations**. It is calculated as follows: The total number of clicked recommended products divided by the amount of recommendation calls. This statistic only delivers reliable information if the tracking is implemented correctly. + +The revenue-through-recommendations is a **monetary value** which was additionally created by recommendations. It is calculated as follows: If a user buys product A and has clicked on it as a recommendation within 30 minutes before we assume it was sold through a recommendation. + +Purchased recommendations is the **plain number of sold recommendations** without any revenue/price information. + +All statistical information can be downloaded in MS Excel format. The timeframes depend on the selection of the diagram period (day, week, month, 3 months and year) but can also be customized. + +## Configuration Settings + +### Revenue details + +This tab shows you when recommendations were bought and how much time passed between the click on the recommendation and the buying event. + +![Dashboard Added Revenue](img/dashboard_added_revenue.png) + +### Scenarios + +The scenario overview shows all available scenarios. Additional info like a description and the delivered recommendations in the selected timeframes are also presented. + +![Dashboard scenarios](img/dashboard_scenarios.png) + +Scenarios with green status bars indicate that all models can provide recommendations. Yellow bars indicate that only a part of the configured models can provide recommendations and red ones indicate that no recommendations can be delivered. See [8. Scenarios](scenarios.md). + +### Models + +This tab allows you to see all available models and configure them, see [6. Recommendation Models](recommendation_models.md)  + +![Dashboard models](img/dashboard_models.png) + +### Preview + +This tab shows you recommendation preview based on a Scenario. + +![Dashboard Preview](img/dashboard_preview.png) + +### A/B Testing + +This tab holds an overview of A/B Tests. Finished, currently running and scheduled tests are listed here. + +![Dashboard A/B Tests](img/dashboard_ab_tests.png) + +### Plugins + +If a plugin was used to register the service, specific settings can be configured under **Plugins**. + +![Dashboard Plugins](img/dashboard_plugins.png) + +### Import/Export + +Item import jobs are used to fetch data from a customer system. Data-mappings and schedule times are defined here. + +![Dashboard Item Import](img/dashboard_item_import.png) + +### Newsletter + +Newsletters are sent out if certain events happen, e.g. a user did not come back for a number of days or the shopping cart was abandoned. Style and conditions are configured in the **Newsletter** tab. diff --git a/docs/personalization/event_types.md b/docs/personalization/event_types.md new file mode 100644 index 00000000..65f0e929 --- /dev/null +++ b/docs/personalization/event_types.md @@ -0,0 +1,34 @@ +# 4. Event Types + +It was already mentioned that the recommendation engine collects events and computes recommendations based on user behavior. The most important events collected by the engine are click and buy events. They are enough for providing basic recommendations. There are some additional events for creating more complex scenarios and providing statistics about acceptance of recommendations, such as conversion rate or revenue.  + +![Overview of how events work](img/events_overview.png) + +All possible events used in the system are described in the following table. + +|Event|Description| +|---|---| +|CLICK|It should be sent to the recommendation engine if a user opens any detail page on the website.| +|BUY|It should be sent if something was bought.| +|CONSUME|Similar to the BUY event but without a payment. It is designed for publisher websites. This event is sent if an article or a web page is consumed (usually "read" or a "pre-listened" video).| +|RENDER|It should be sent if a recommendation is shown on the web page. This information is used by filters to suppress repeated recommendations of the same item.| +|FOLLOW / CLICKRECOMMENDED|If a user clicks on the recommended product the "clickrecommended" (sometimes called FOLLOW) event must be sent. It allows building acceptance statistics and enables A/B testing.| +|TRANSFER / LOGIN|A special type of event to deal with a user login after the user already surfed on the web page anonymously. It should always sent if the identifier of the user changed. As a result the anonymous history of the user will be transferred from the old identifier to the new one. This workflow is automatically done in the recommender engine.| + +#### Additional events for the advanced edition + +|Event|Description| +|---|---| +|BASKET|It should be sent when the user adds the specified product to the shopping cart. It allows creating recommendations for products the customer is interested in but which they finally did not buy for some reason.| +|BLACKLIST|Allows a user to suppress this recommendation. If the recommendation engine gets this event, the specified product or article won't be recommended anymore to the specified user. Default duration of suppression is one year.| +|OWNS|Same as BUY, but without influence on the statistics. It can be used if a user already owns the product, but bought it somewhere else, to avoid recommending it again.| +|RATE|Additional models can be created for the advanced edition, using this type of events. It allows building recommendations not only for implicit tracking events like "clicked" 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 should be triggered as a result of this user feedback.| + +All the events require the current user ID and the ID of one or more context items. Some events need additional information. For more sophisticated algorithms and result filtering event types with additional parameters are needed. In the table below is 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 is an alternative way to provide this information for a product without having a catalogue/export. This way is available for both basic and advanced editions. If an export is available to be fed into the recommendation engine, this information is ignored.| +|BUY|The price that a user paid for the product. This is an important parameter for the statistics and especially for A/B tests. Quantity of the products bought must be sent as well to be used in the revenue statistics.| +|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..33e2b9be --- /dev/null +++ b/docs/personalization/filters.md @@ -0,0 +1,114 @@ +# 7. Filters + +## Category Filter + +For every row in the scenario configuration you can define a category filter. If the filter is activated, only items from the specified category will be recommended. The actual category used to filter on is specified in the parameters of each recommendation request. + +There are two ways to specify a category in a recommendation request: + +- No context items, but the **category explicitly provided in the request**. This recommendation call is usually placed on the category overview page for getting most popular products of the selected, actual category (in the figure it is called "reference category"). +- **Context items are provided** and categories of all context items are used for the request. This approach is recommended only if it is technically impossible (or too complex) to provide the category information explicitly. + +Depending on configuration of the filter, the recommendation engine can take different approaches to finding the actual set of categories the products will be recommended from. + +The following example explains the different possibilities in more detail. + +Depicted below is the configuration dialog - available in the GUI on the right side of the model configuration tab in a scenario (see [Advanced Model Configuration](recommendation_models.md#advanced-model-configuration)) - and category structure which is basically the site navigation: + +![Category path screenshot](img/categorypath_filter.png) + +![Category path tree](img/categorypath_tree.png) + +The table below lists the possible configurations and categories that recommended items will be fetched from. + +In all examples we assume that the category received in the request is **"/Furniture/Desks&Tables/Tables"**. + +|category Path Filter configuration|Target categories to fetch recommended products from| +|---|---| +|Always recommend products from the whole shop. Do not use category path for filtering.|All categories ("Plants", "Furniture" and below).| +|Recommend only products from the same category ("also include..." is not checked).|Category "Tables" and all the sub-categories below ("Garden tables" and "Living room tables").| +|Recommend only products from the same category. "Also include parent category" is set to 1.|Category "Desks/Tables" and below including "Desks", "Tables" and all their sub-categories.| +|Recommend only products from the same category. "Also include parent category" is set to 2.|Category "Furniture" and below.| +|Recommend products from the same main category and its subcategories from level 1.|Category "Furniture" and below.| +|Recommend products from the same main category and its subcategories from level 2.|Category "Desks/Tables" and below.| +|Recommend products from the same main category and its subcategories from level 3.|Category "Tables" and below.| + +It is possible to provide multiple reference categories (both in the request and over the context item or items). In this case the superset of the recommendations will be returned. The results are sorted based of global weight of the recommendations. Depending on the popularity of the categories the more popular category will most probably push the less popular categories out of the results. + +If the recommended item is located in more than one category, it will be recommended if at least one category is requested in this recommendation call. + +### Multiple Categorypath dimensions for popularity models + +The categorypath parameter is very powerful in its usage. The default approach is to represent content in the navigation-based structure of a website which is used by default. If there is a need to represent available items of a website in different dimensions (taxonomies) it is possible to do this out-of-the box simply by enriching the categorypath information of an item, without changing any settings in the recommender engine. + +To make it a bit clearer let's take a look at the following example: In the above mentioned shop both furniture and plants are sold and they are structured based on site navigation. Typically customers would look for computer desks and get a list of recommendations of all computer desks in the shop. If desired, the recommendation engine could also use another dimension for filtering recommendations, for example a "brand" dimension. In this case the user would get recommendations for all items from the same "brand". + +In case of popularity based recommendations it will be possible to get most popular products based on the main navigate tree (most popular desk) or based on the brand (most popular IKEA item). + +Some examples of common representation dimensions of items beyond the site navigation: + +|Business|Possible dimensions| +|---|---| +|eCommerce|manufacturer (e.g. BOSCH, Renault, ...)
season (e.g. winter, spring, ...)
price range (e.g lowprice, midprice, highprice, ...)
platform (e.g. Mac, Windows, Linux ...)| +|Book store|genre (e.g. action, science, ...)
author (e.g. George R. R. Martin, ...)| +|Publisher site|global subject (e.g. politics, sports, ...)
physical location (e.g. Cologne, Munich, ...)
timeframe (time identifier like 2013-07-04)| + +You should avoid using category filtering with also-click/also-buy and stereotype models. These models usually contain only similar items. Additional filtering will probably remove the best results from the list of possible recommendations. The only exception to this rule could be copyright or legal issues like removing adult content. For the last use case sub-models and item types often provide better results. See the following chapters for more information: + +[5. Content Types](content_types.md) + +[Submodels](recommendation_models.md#submodels) + +To provide category filtering, the recommendation engine must know the categories the products belongs to. See the following chapters for more information: + +[4. Event Types](event_types.md) + +[9. Content Import](content_import.md) + +## General Filters + +For every recommendation scenario a set of filters can be defined. They are applied to all recommendations from every model linked to this scenario. In the edit dialogue of a scenario you can find the user interface to manage filters. + +![General filter settings](img/scenario_configuration_full.png) + +|Filter|Requirements and restrictions| +|---|---| +|Do not recommend items the user has already purchased|The recommendation engine stores the buy (e-commerce) and consume (publisher) events of every user for one year. When this filter is activated, the user won't get these products recommended again.| +|Max. repeated shows of identical recommendations per session|If this filter is activated, this content/product will be removed from all recommendation lists of the current user session after being recommended n times before.| +|Do not recommend the item currently viewed|Remove the context items from the recommendation list. Usually it makes sense to activate this filter except in the "Bundle" and "Ultimately bought" recommendation case ([6. Recommendation Models](recommendation_models.md)).| + +**Filters which are available only in the advanced solution** + +|Filter|Requirements and restrictions| +|---|---| +|No top-selling items|Removes products from the recommendation list which are recommended by the top selling model (even if the model itself is not linked to this scenario). It is another way to remove very popular products from the recommendation list if you are not interested in showing them again. It makes no sense to apply this filter to a top selling scenario as it will filter out every recommendation.| +|Item price should be higher than the specified value|This filter could be used to remove very cheap but popular items from the recommendation list. For example an optometrist wants to show the most popular designer glasses on the home page to avoid displaying insurance subsidized cheap models and glass cleaning cloths. This filter relies on product metadata and uses [prices exported to the recommendation engine](content_import.md).| +|Item price should be equal or higher than the price of the context product|Like the filter above it compares prices exported to the recommendation engine against the product which is currently shown.| +|Do not recommend if price is unknown|If a product's price is not available then it will not be recommended.| + +**Special and always enabled filters (advanced edition only)** + +|Filter|Requirements and restrictions| +|---|---| +|Editor blacklisted products.|Advanced edition gets several editor-based models ([6. Recommendation Models](recommendation_models.md)). One of them is an editor blacklist. The products from the blacklist will always be removed from every list of recommendations. You can use this feature to remove some standard products which users will buy in any case without recommendation (bread, butter, milk) or non-existing test products which are only used by a robot to check if the shop software is working properly.| +|Customer blacklisted products|In addition to the standard set the website can send blacklist events for selected products and users. It can be implemented as e.g. a button "I do not like this product". If a user added a product to their blacklist, it will not be recommended to them anymore.| +|Product validity interval|Additional product information [can be exported to the recommendation engine](content_import.md). If the product information is available and contains a validity time interval (for example the product is available only until 24 December 2014), it will be used to remove invalid products from the recommendation list.| + +## Boost-Filters + +In addition to general filters, which remove specified elements from recommendations, the boost filter allows shifting (boosting) selected recommended items to the top positions of the recommendation response. This may happen if a selected attribute of the customer has the same value as the selected attribute of the recommended item. For example, we can show the news from the user's home country with higher priority than the rest. + +Assuming every item in the picture below has the attribute "country" and the user has the attribute "country\_of\_origin", the boost filter can be configured in **Filter settings** like this: + +![Boost filter settings](img/boost_filters.png) + +...which leads to boost recommendations for certain users: + +![Boost filter example](img/boost_example.png) + +This type of filter needs both item import and user attribute import. + +See developer guide for more information on item and user attributes import: + +- [Insert XML Content](https://doc.ezplatform.com/en/master/guide/personalization/content_api.md#insert-xml-content) +- [User API](https://doc.ezplatform.com/en/master/guide/personalization/user_api.md) diff --git a/docs/personalization/img/attribute_config.png b/docs/personalization/img/attribute_config.png new file mode 100644 index 00000000..05a5f2b0 Binary files /dev/null and b/docs/personalization/img/attribute_config.png differ 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..631f5e73 Binary files /dev/null and b/docs/personalization/img/boost_example.png differ diff --git a/docs/personalization/img/boost_filters.png b/docs/personalization/img/boost_filters.png new file mode 100644 index 00000000..70378fcb Binary files /dev/null and b/docs/personalization/img/boost_filters.png differ diff --git a/docs/personalization/img/categorypath_filter.png b/docs/personalization/img/categorypath_filter.png new file mode 100644 index 00000000..5e0fccd7 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..469e2a9e Binary files /dev/null and b/docs/personalization/img/categorypath_tree.png differ diff --git a/docs/personalization/img/dashboard_ab_tests.png b/docs/personalization/img/dashboard_ab_tests.png new file mode 100644 index 00000000..52aaabf0 Binary files /dev/null and b/docs/personalization/img/dashboard_ab_tests.png differ diff --git a/docs/personalization/img/dashboard_added_revenue.png b/docs/personalization/img/dashboard_added_revenue.png new file mode 100644 index 00000000..e88d7f82 Binary files /dev/null and b/docs/personalization/img/dashboard_added_revenue.png differ diff --git a/docs/personalization/img/dashboard_item_import.png b/docs/personalization/img/dashboard_item_import.png new file mode 100644 index 00000000..127efa78 Binary files /dev/null and b/docs/personalization/img/dashboard_item_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..e0e9610f Binary files /dev/null and b/docs/personalization/img/dashboard_models.png differ diff --git a/docs/personalization/img/dashboard_plugins.png b/docs/personalization/img/dashboard_plugins.png new file mode 100644 index 00000000..139fabd2 Binary files /dev/null and b/docs/personalization/img/dashboard_plugins.png differ diff --git a/docs/personalization/img/dashboard_preview.png b/docs/personalization/img/dashboard_preview.png new file mode 100644 index 00000000..12557bc9 Binary files /dev/null and b/docs/personalization/img/dashboard_preview.png differ diff --git a/docs/personalization/img/dashboard_scenarios.png b/docs/personalization/img/dashboard_scenarios.png new file mode 100644 index 00000000..74bdc86c 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..4830b73d 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/model_config_details.png b/docs/personalization/img/model_config_details.png new file mode 100644 index 00000000..416ece38 Binary files /dev/null and b/docs/personalization/img/model_config_details.png differ diff --git a/docs/personalization/img/model_config_editor.png b/docs/personalization/img/model_config_editor.png new file mode 100644 index 00000000..544cb8de Binary files /dev/null and b/docs/personalization/img/model_config_editor.png differ diff --git a/docs/personalization/img/model_config_editorial_list.png b/docs/personalization/img/model_config_editorial_list.png new file mode 100644 index 00000000..b479de8f Binary files /dev/null and b/docs/personalization/img/model_config_editorial_list.png differ diff --git a/docs/personalization/img/model_config_in_dashboard.png b/docs/personalization/img/model_config_in_dashboard.png new file mode 100644 index 00000000..29b68a69 Binary files /dev/null and b/docs/personalization/img/model_config_in_dashboard.png differ diff --git a/docs/personalization/img/scenario_configuration.png b/docs/personalization/img/scenario_configuration.png new file mode 100644 index 00000000..dc0cac23 Binary files /dev/null and b/docs/personalization/img/scenario_configuration.png differ diff --git a/docs/personalization/img/scenario_configuration_full.png b/docs/personalization/img/scenario_configuration_full.png new file mode 100644 index 00000000..ada1ea29 Binary files /dev/null and b/docs/personalization/img/scenario_configuration_full.png differ diff --git a/docs/personalization/img/scenario_matrix.png b/docs/personalization/img/scenario_matrix.png new file mode 100644 index 00000000..1eb76b4b Binary files /dev/null and b/docs/personalization/img/scenario_matrix.png differ diff --git a/docs/personalization/img/scenario_preview.png b/docs/personalization/img/scenario_preview.png new file mode 100644 index 00000000..b7e92a50 Binary files /dev/null and b/docs/personalization/img/scenario_preview.png differ diff --git a/docs/personalization/img/submodel_config.png b/docs/personalization/img/submodel_config.png new file mode 100644 index 00000000..76fcec1b Binary files /dev/null and b/docs/personalization/img/submodel_config.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..37aff8b5 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..b7e46b31 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..4e7c7c2d Binary files /dev/null and b/docs/personalization/img/use_case_shopping_basket.png differ diff --git a/docs/personalization/personalization.md b/docs/personalization/personalization.md new file mode 100644 index 00000000..08e69146 --- /dev/null +++ b/docs/personalization/personalization.md @@ -0,0 +1,7 @@ +# 1. Personalization + +!!! note "E-Commerce vs. Publisher Wording" + + This guide's wording is more related to the E-Commerce Personalization Solution but can be used for a thorough understanding of a Publisher Personalization Solution as well. + + Keep in mind that a product or item can be referred to as content and the buy event for non-paid publisher content is replaced by the consume event. diff --git a/docs/personalization/recommendation_models.md b/docs/personalization/recommendation_models.md new file mode 100644 index 00000000..e12ea1dd --- /dev/null +++ b/docs/personalization/recommendation_models.md @@ -0,0 +1,151 @@ +# 6. Recommendation Models + +Chapter [2. Use Cases](use_cases) describes where recommendations can be used in real-world situations. They are based on algorithms and the calculated result of an algorithm is called a model. The models work in the background and are updated regularly to provide recommendations. There are several types of models available: + +### Models available for both basic and advanced edition + +#### Popularity + +Classic popularity recommendation. The model can be customized using time-dependent weights (recent events are more important) and category based filtering (bestsellers in selected category and/or subcategories). + +#### Also clicked/purchased + +This type of recommendation is often called "Collaborative Filtering based on user data" and is a proven approach to calculating recommendations. It recommends products which are usually clicked or purchased together. It is very simple to configure, needs no maintenance and it is a very powerful model. + +#### Ultimately bought + +This model combines click and buy events. In human readable form it could be something like "Users who looked for that kind of product finally bought this". It therefore provides a "matching factor" of searching and buying. This model suggests alternative products which customers bought after they clicked on the selected product. In contrast to the "also-bought" 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, a user searches for a book which explains how to cut trees. If they finds a book and on the book page this exact same book is being recommended, it means that several users interested in cutting trees bought this book (and not others), which hints that this book is the very best choice. + +#### History based + +Pseudo recommendation model to show the user products from his own history. Like "you have just watched" box. + +### Additional models are available for advanced editions + +#### Frequently bought together / Bundle recommendations + +Products that were bought in this combination for at least n times can be treated as bundles and recommended as a "package". Based on the product which is currently shown, this model can recommend other products that fit exactly the one the user is currently looking at. An example could be: + +A user wants to buy a smartphone and browses on the detail page of smartphone X. Additionally to the "Also Clicked" recommendations, the Recommender Engine would recommend the bundle *Smartphone X + Smartphone X Cover + Headphones* as they were  bought together in exactly this combination for at least five times. + +It is not guaranteed that there's a bundle available for every product. Therefore a rendering logic should display a box of bundle recommendations only if they are available, otherwise the box can be left out. Remember that the currently displayed product is always included in the bundle. + +#### Content Based (by attributes) + +The content based algorithm calculates the similarity scores among products based on given attributes. This algorithm depends on expert knowledge because you should be able to define the most important attributes of the product catalog. An example could be the price, the producer or the location of a product. In the news domain, this may be the story location the article is talking about, the author or the category. The distinct attributes should be limited in their range (a nominal set) because it does not make sense to build similarities based on attributes that are different for each product (e.g. a timestamp or EAN-Code). There is also a need to assign weights to these attributes since they are used to compute the importance weight of each attribute for the similarity. + +#### Content Based (by semantic full text analysis) + +This model provides similarities based on free text analysis and indexing. This is a very powerful model publishers can use to get similar articles based on their content without the need of manual maintenance of related articles by e.g. editors. The full text analysis algorithm uses a search engine in the background. + +#### Similar Rated + +The similar rated algorithm provides recommendations based on user preferences. It predicts similar articles which the user will probably like and that will suit their interests. Recommendations for articles similar to their dislikes are suppressed. + +#### Best Rated + +The best rated model provides recommendations based on algorithms that include the ranking values and the amount of distinct ratings. It is best suited for landing or category pages. + +#### Random + +Semi-random products from the most recent ones. It allows injecting new products to the recommendation while the history based models are not yet able to recommend products based on the statistics. It is a really simplified and unsophisticated alternative if no other information is available to calculate and provide recommendations. + +This model is not built based on the history footprints but based on the imported product catalog. + +#### Editor based + +Products that are manually selected by a human. A customer can replace an automatically generated recommendation with a predefined list. It is best suited when the store administrator wants to add special offers or sell stock remains. It could also be called "static recommendations". + +#### Blacklist + +Products on this list will never be recommended in any scenario. Usually test products or products that are used for system monitoring are placed on this list. Be careful to use this model in any scenario config, it works globally! + +## Advanced Model Configuration + +Most of the models provide additional configuration parameters for customization. Here is an example: + +Open a model configuration in the Dashboard and enter the model configuration of a Collaborative-Filtering model + +![Model configuration in the Dashboard](img/model_config_in_dashboard.png) + +![Model configuration details](img/model_config_details.png) + +or an Editor-Based model + +![Model configuration - Editor-Based model](img/model_config_editor.png) + +![Model configuration - Editorial list](img/model_config_editorial_list.png) + +The parameters supported by the different types of models are described in the table below. Some models support submodels, see chapter [Submodels](#submodels) for more information. Additional differentiation criteria 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. Dependent on the product type 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/bought / Ultimately bought|Both also clicked and ultimately bought models allow to define the relevant event history.|yes, manual|required (either context items or user data)| +|Random|This model requires the maximum age for the items that should be recommended by this model.|no|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 "they clicked on the product A two weeks ago"). Item age is the time over which the item is available in the shop - so to say "how new is the item". The history is filled automatically over event tracking (see [4. Event Types](event_types.md)). The item catalog must be filled separately over an item import. + +## Submodels + +Statistics-based recommendations often have the disadvantage of providing recommendations limited to the "most"-popular, "most"-suitable to you or "most"-similar products. Often it is needed to extend the set of available recommendations by defining a subset of most-"something" items based on some external criteria. For example: + +- most popular products for the predefined age (searching for a toy) +- also bought products with the same color (for clothes) +- also bought products with a predefined price (searching for a birthday present) + +Submodels provide the possibility to group all the products based on an attribute. Recommendations can then be requested especially for the selected group. + +#### Nominal Attributes + +If the possible values of some attribute are a limited set of values, we talk about a nominal attribute submodel, for example the number of possible colors. The set of possible values is usually limited and every product has a single color attached to it. + +Submodels must be manually configured. Therefore it works only if the number of possible values is relatively small and there is a large group of products for every value. Good examples would be "color" for clothing store, "genre" for a book store or "city district" for a newspaper. Bad examples would be ~~street name~~ (there are too many of them), ~~book author~~ (there are too many of them as well) or EAN-Code (they are unique and therefore hard to group). + +Coming back to the color example. We are configuring submodels for a clothing store and want to get recommendations for some color (it can be a predefined color or a color of the context item). Every manufacturer has its own color classification. Similar colors can be grouped together as shown in the picture below: + +![Attribute example](img/attribute_example.png) + +The configuration is done using the property dialog of the recommendation model. + +![Attribute configuration](img/attribute_config.png) + +After the submodel is configured and built (happens automatically during the nightly build process) there are several cases for recommendations. Based on the example above the following are possible: + +|Attribute example in the recommendation request|Result| +|---|---| +|color=lime|Value "lime" is found in the green-ish group (Group 1). There are products in this group. If a model has some of them, they will be recommended.| +|color=sand|Value "indigo" is found in the blue-ish group. There are no products in the group. Nothing will be recommended by this model. The fallback model (if configured) will be used.| +|color=white|Value "white" was not found in any of groups. The main model will be used. Items from all submodel groups can appear in the result (as if the submodels were not configured at all.).| +|no attribute specified|The main (full) model will be used, means the request is handled as if submodels were not configured at all. Products from the whole shop could appear in the recommendation list.| + +#### Numeric Attributes + +Similar to the nominal submodels, the configuration is about the definition of subgroups. +It is done by selecting limits for every group. + +![Submodel configuration](img/submodel_config.png) + +There are two values used for setting the limits — `from` and `to`. + +The logic behind it is as follows: + +- The `from` value indicates the beginning of the range of the subgroup and belongs to it. +- The `to` value indicates only the range end and does not belong to the subgroup. +- The **only exception** is the last of the defined subgroups. +In its case, the `to` value indicates the range end and also belongs to it. + +!!! note + + 1. Both numeric and nominal attribute can have multiple values. Such a product will be placed in multiple submodel groups. + 1. Submodel results are not available immediately after the submodel is configured. In contrary to category filters and general filters, submodels must be (re)built during the nightly building process. The results are usually available on the next day. + 1. It is possible to specify a single or multiple attributes with multiple values for requesting recommendations. In this case the recommendation will be fetched from all the submodels and merged based on the weight (aka relevance). If one of the submodels delivers recommendations with better relevance (which is very often the case) it is possible that the results of other models will be removed from the list. + +!!! tip + + Once configured, submodels are enabled for the model globally. All the scenarios which use this model will be aware of it. If it is not intended to activate the recommendation grouping in some cases, do not provide the attribute parameter in the request. The submodel is not used then. + + See [Recommendation API](https://doc.ezplatform.com/en/master/guide/personalization/recommendation_api.md) in the developer documentation for more information. diff --git a/docs/personalization/scenarios.md b/docs/personalization/scenarios.md new file mode 100644 index 00000000..e17a6765 --- /dev/null +++ b/docs/personalization/scenarios.md @@ -0,0 +1,23 @@ +# 8. Scenarios + +A scenario is a configuration for getting recommendations. It consists of: + +1. a content type to be returned as recommendation,  +1. a filter configuration, +1. a set of models to be used for generating recommendations. + +![Scenario configuration](img/scenario_configuration_full.png) + +We strongly encourage adding several models to a scenario in order to avoid empty recommendation boxes. In the configuration interface there is a matrix provided for the configuration. You can drag available models from the left side into the scenario matrix on the right side. + +![Scenario configuration matrix](img/scenario_matrix.png) + +The scenario configuration field has several rows. Models located in the same row will be used in parallel and the result will contain an equally distributed mixture of all used model results (horizontal configuration). Models located on the second and third row will be used only if models from the row above return no or not enough results (vertical configuration). + +Following the example in the images, the first recommendations that will be displayed to the user will come from "Also purchased". If there are no or not enough recommendations available, the "Also clicked" model will be requested. If there are still not enough products in the result set, the "Top purchased" products from the Fail-safe row (not visible in the example image) will be added according to the number of requested recommendations. On the right side of the first rows there is a button to configure Category Filter usage in the recommendation request. This is described in detail in [Category Filter](filters.md#category-filter). + +In contrast to the model configuration described in the chapter [6. Recommendation Models](recommendation_models.md), the configuration performed in this step is applied only to the selected scenario. + +The **Preview** tab can be used to simulate a recommendations request performed by the system. One only needs to add the required parameters and click 'Send' (in the upper right corner). + +![Scenario preview](img/scenario_preview.png) diff --git a/docs/personalization/use_cases.md b/docs/personalization/use_cases.md new file mode 100644 index 00000000..9844260b --- /dev/null +++ b/docs/personalization/use_cases.md @@ -0,0 +1,29 @@ +# 2. Use Cases + +There are many different use cases where recommendations can be used. The most common ones are located in the e-commerce and publishing industries. + +## E-commerce + +E-commerce recommendations can be very powerful to help customers find what they're looking for. If a user is not sure about what to buy, recommendations can be used to show similar, alternative or complementary products. Some typical use cases are: + +- On the landing page the current bestsellers ('Hot Sellers') are shown to every customer. +- A detail page displays the products that were bought by others ('What other customers bought') or have been frequently bought together (e.g. this TV and a HDMI cable). +- The shopping cart page shows recommendations ('Related to your shopping cart') matching the products in the cart. +- On a category page, bestsellers of the current category are shown. +- Additionally on the landing page and on the detail page a recommendation bar could be placed to show **personalized recommendation** (based on their latest profile information) for the current user. + +![Landing page](img/use_case_landing_page.png "Landing page") + +![Detail page](img/use_case_detail_page.png "Detail page") + +![Shopping basket](img/use_case_shopping_basket.png "Shopping basket") + +In the pictures above each recommendation box presents a scenario. Scenarios are configurations that define what kind of recommendations should be delivered. More can be read under [8. Scenarios](scenarios.md) + +## Publishing + +Recommendation and Personalization in the publishing business provide indirect value by keeping users on the website. Unlike in the e-commerce business, publishers often do not sell content, it is provided for free and cross-financed by advertisement. Increasing the CTR (click-through-rate) and adding value generated by advertisement is one of the drivers in the publishing business. Use cases for placing recommendations are straightforward: + +- On the landing page, the most read content is presented. +- On every category page, the most popular content in the current category is shown. +- On every content page, the related content is shown. diff --git a/docs/personalization/user_data_import.md b/docs/personalization/user_data_import.md new file mode 100644 index 00000000..8ccce55a --- /dev/null +++ b/docs/personalization/user_data_import.md @@ -0,0 +1,15 @@ +# 10. User Data Import + +By default the recommendation engine has very little information about the user visiting the website, especially first-time visitors. The only information provided in the event tracking and recommendation request is the customer ID of the website owner and an external user ID (usually an anonymous session ID). This external user ID is again anonymized in the recommendation engine by a hashing algorithm. + +Sometimes it is helpful to store additional attributes for every user, for example age or home city. It is possible to retrieve the stored information based on the external user ID, but due to the hashing step mentioned above, it is not possible to get the external user ID within the user's attribute set (unless the external ID is not explicitly stored as an attribute of course). + +How user attributes are imported and what they can be used for is described in the [User API](https://doc.ezplatform.com/en/master/guide/personalization/user_api.md). + +Usage of the user attribute in the recommendation process is quite straightforward and explained in detail in the [Recommendation API](https://doc.ezplatform.com/en/master/guide/personalization/recommendation_api.md). + +!!! tip + + An example of how user attributes can be used in the recommendation engine:[Boost-Filters](filters.md#boost-filters) + + Information on the import format can be found in the developer guide:[User API](https://doc.ezplatform.com/en/master/guide/personalization/user_api.md) diff --git a/docs/shop_administration/chat_tool_olark.md b/docs/shop_administration/chat_tool_olark.md new file mode 100644 index 00000000..9b9d8b00 --- /dev/null +++ b/docs/shop_administration/chat_tool_olark.md @@ -0,0 +1,127 @@ +# Olark chat tool + +Olark is a third-party chat tool that you can enable as a plugin. + +![](img/olark_addon.png) + +![](img/olark_chat.png) + +![](img/olark_info.png) + +The shop can forward the name of a user (if logged in) to the service employee. +Besides a chat functionality the service employee can assist the customer e.g. in pointing them to the correct place in the shop. + +If no support employee is available, the conversion is sent by email. + +!!! note + + Some features are available with a special contract only. + See [Olark plans](https://www.olark.com/pricing) for more information. + +### Online/Offline + +The chat windows indicates whether a salesperson is available or not. + +If a salesperson is online, the chat indicates this and it is possible to display an icon or an image of the salesperson. + +![](img/olark_online_offline.png) + +### Change the text inside the chat + +You can change and translate all texts and labels used in the chat. + +### Using the chat for sales + +Olark offers a web interface where chats can be handled. + +In addition, local chat clients can be used as well, e.g.: + +- iChat +- XMMP Clients +- mobile apps + +### Restrict access for chat + +You can restrict the chat tool to: + +- specific products +- specific customers or customer group +- from a given basked amount +- given countries + +The chat can be displayed after the user has been on a page for a given time. + +### Information about the user + +Depending on your privacy rules, information about the user can be displayed in the chat, such as: + +- Geo information +- Visited pages +- Name and company if logged in +- Amount of the basket +- Customer number + +### Design of the chat tool + +You can modify the design of the plugin in Olark backend. + +### Groups of salespersons + +A chat can be assigned to a group of users as well. + +### Alerts and options for employees + +![](img/olark_alerts.png) + +You can set up alerts such as sounds or desktop notifications. Olark can be connected to internal tools such as Jabber. + +A user can set their status to online / away. + +### Co-browsing + +Olark supports [co-browsing](https://www.olark.com/help/cobrowsing) if a customer needs support. + +Co-browsing is supported by IE8+, Firefox, Safari, Chrome, and Opera, as well as Safari for iOS devices. + +### Chat commands + +Olark supports multiple chat functions. For a complete list see [Olark documentation.](https://www.olark.com/help/commands) + +Important commands: + +- `tag` - tags a chat to label conversations +- `transfer` - transfers a conversation to another operator +- `push` - sends a visitor to a different website URL +- `name` - gives a website user a name +- `case` - pushes the transcript for your chat into your CRM +- `send` - enables you to forward a chat transcript by email during a chat +- `feedback` - enables you to send a Chat Rating to the visitor + +## Configuration + +Create an account on [www.olark.com.](http://www.olark.com) You can choose a free version or another option as required. +We recommend the paid version since it offers support features such as co-browsing. + +Configure Olark in the **Customer** section of configuration settings: + +![](img/olark_customer.png) + +Change the following settings: + +- Enable the service +- Enter the Olark Account ID + +You can find the Olark Account ID in the "Installation" section. + +![](img/olark_installation.png) + +After storing the configuration you should see a chat tool at the bottom of your page. + +In the settings section on [www.olark.com](http://www.olark.com) you can also configure: + +- the location where the chat should appear +- translations +- color +- a photo of the support employee + +See [Olark documentation](https://www.olark.com/api) for more details. diff --git a/docs/shop_administration/cockpit.md b/docs/shop_administration/cockpit.md new file mode 100644 index 00000000..cdae5f8c --- /dev/null +++ b/docs/shop_administration/cockpit.md @@ -0,0 +1,61 @@ +# Cockpit + +The Cockpit shows the most important information for the shop owner referring to the installation. + +![](img/commerce_cockpit.png) + +## Overview + +Currently, available sections: + +- Technical subsection + - HDD usage + - Server load + - ERP Status +- Active shopping carts (in last 30 minutes) +- Number of customers +- Number of products (The number of products only respects the content model data provider. +The number of products in the eContent is displayed in **Control Center** / **Manage eContent**.) + +## Data per shop + +The data in the next section refers to a specific shop. +If there is more than one shop in the installation, the shop owner can choose shop and currency. + +Currently available data: + +- Sales - shows orders value in time +- Orders - shows number of orders + +You can select a specific date range or one of predefined date ranges. + +You can also compare the chosen date range with the a range of the same length in the past. +For example, if you choose last week, you can compare it with the week before. + +## Products and sales + +Product and sales section shows data in tables such as: + +- Bestsellers (Top 20) +- Last orders (Last 365) +- Best clients (Top 20) + +You can refresh this panel separately from the whole page with the icon in the top right corner on the section's title bar. + +Tabs **Last orders** and **Best clients** are only visible for users who have the Siso policy / Read customers and orders Policy. See [Permissions](permissions.md) for more information. + +## Search + +The search section offers the following statistics: + +1\. Top search terms + +Lists top 50 search terms including how often they are searched for and how many hits (average) they have. + +2\. Last search terms + +The latest 50 search terms ordered by date. + +3\. Most searched terms with less hits + +This table shows search terms which did not lead to a result and the number of times they were searched for. diff --git a/docs/shop_administration/components.md b/docs/shop_administration/components.md new file mode 100644 index 00000000..686a54cc --- /dev/null +++ b/docs/shop_administration/components.md @@ -0,0 +1,12 @@ +# Components + +**eCommerce** > **Components**. contains two sections: eCommerce Configuration settings and text modules. + +Do not edit the "silver.eShop Configuration settings" Content item manually. +It is updated by the changes from the configuration settings. + +![](img/components_menu.png) + +![](img/components_items.png) + +For more information about text modules, see [Translations](translations.md). diff --git a/docs/shop_administration/configuration_settings.md b/docs/shop_administration/configuration_settings.md new file mode 100644 index 00000000..33779595 --- /dev/null +++ b/docs/shop_administration/configuration_settings.md @@ -0,0 +1,161 @@ +# Configuration settings + +To change configuration settings for the shop, go to **eCommerce** > **Configuration settings**. + +![](img/configuration_settings.png) + +!!! caution + + Settings defined in the Back Office always override the configuration in YAML files. + +## Catalog + +The catalog section defines details for structure and layout of the catalog. + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Layout product category page|siso_core.default.category_view: product_list|product_list|Changes the layout for the product category page. `category` shows category boxes only, `product_list` shows products only, `both` shows both categories and products. HTTP cache has to be cleared to make changes visible.| +|Last viewed product limit|silver_eshop.default.last_viewed_products_in_session_limit: 10|10|The maximum number of products to be stored per user for last viewed products.| +|Product description character limit|silver_eshop.default.catalog_description_limit: 50|50|The number of characters for product description in the list views / search results. When the limit is reached, the description will be truncated.| + +## Price + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Last currency rate change||empty|When the conversion rate has last changed.| +|Automatic currency conversion||False|If no price is set up for this currency, the shop can calculate the price using a conversion rate from the configuration.| +|Currency conversion rate|||The conversion rate between currencies.| +|Default currency|siso_core.default.standard_price_factory.fallback_currency: EUR|EUR|Used as currency for the shop (e.g. per SiteAccess).| +|Base currency|siso_core.default.standard_price_factory.base_currency: EUR|EUR|Base currency of the shop in general (used for the fields "product unit price" and "fallback shipping price". The base currency is used for the automatic currency conversion).| +|Price providers for product listing page|siso_price.default.price_service_chain.product_list:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Price calculation engines used for generating prices and stock information. `siso_price.price_provider.shop` indicates the price engine in the shop, `siso_price.price_provider.remote` indicates ERP. This configuration works as a chain, so if the first engine fails, the second one is used as a fallback (e.g. if ERP is not available). Price calculations in ERP systems may cause slower responses from the system, depending on the specific complexity.| +|Price providers for product detail page|siso_price.default.price_service_chain.product_detail:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for product sliders|siso_price.default.price_service_chain.slider.product_detail:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for basket|siso_price.default.price_service_chain.basket:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for editing variants|siso_price.default.price_service_chain.basket_variant:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for stored baskets lists|siso_price.default.price_service_chain.stored_basket:
- siso_price.price_provider.remote
- siso_price.price_provider.shop|shop|Shop or remote.| +|Price providers for whishlist|siso_price.default.price_service_chain.wish_list:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for quickorder (click on update)|siso_price.default.price_service_chain.quick_order:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for quickorder (product preview via Ajax)|siso_price.default.price_service_chain.quick_order_line_preview:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| +|Price providers for comparison lists|siso_price.default.price_service_chain.comparison:
- siso_price.price_provider.remote
- siso_price.price_provider.shop|shop|Shop or remote.| +|Price providers for search lists|siso_price.default.price_service_chain.search_list:
- siso_price.price_provider.remote
- siso_price.price_provider.shop|shop|Shop or remote.| +|Price provider for bestseller list|siso_price.default.price_service_chain.bestseller_list:
- siso_price.price_provider.shop
- siso_price.price_provider.remote|shop|Shop or remote.| + + +## Advanced Catalog Features + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Disable ordering for discontinued products|siso_basket.default.discontinued_products_listener_active: true|True|If enabled, discontinued and out-of-stock products cannot be ordered.| +|Check packaging units and adjust quantity of discontinued products|siso_basket.default.discontinued_products_listener_consider_packaging_unit: true|True|If enabled, the shop modifies the quantity of discontinued products ordered by a user automatically to the next packaging unit.| + +## Customer + +!!! note + + The Olark chat tool requires an account with this third party provider. + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Enable Olark Chat|siso_core.default.marketing.olark_chat.activated: false|True|Check www.olark.com for more information.| +|Please enter the Account ID from www.olark.com here|siso_core.default.marketing.olark_chat.id: '6295-386-10-7457'||Olark account ID| + +## Mail and Newsletter + +!!! note + + Newsletter2go requires the activation of a separate plugin and an account with Newsletter2go. + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Email address of a sales person|siso_eshop.default.orderconfirmation_sales_email_address:||This person gets a CC of an order confirmation email (for all orders generated in the shop)| + +### Newsletter + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Activate Newsletter2go|siso_newsletter.default.newsletter_active: false|False|You need to create an account on www.newsletter2go.com| +|Unsubscribe from all newsletters|siso_newsletter.default.unsubscribe_globally: true|True|Unsubscribe options. If true, shop users can unsubscribe from all newsletters in one step.| +|Newsletter only for logged in users|siso_newsletter.default.display_newsletter_box_for_logged_in_users: true|True|If enabled, only logged-in users see the newsletter box.| +|Newsletter2go username|siso_newsletter.default.newsletter2go_username: ''|-|See newsletter2go account| +|Newsletter2go password|siso_newsletter.default.newsletter2go_password: ''|-|See newsletter2go account| +|Newsletter2go authentication key|siso_newsletter.default.newsletter2go_auth_key: ''|-|This key is available in your newsletter2go account| + +## Basket + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Duration of storing anonymous baskets|ses_basket.default.validHours: 120|120|How many hours anonymous baskets are stored for.| +|Update product data after this time|ses_basket.default.refreshCatalogElementAfter: '1 hours'|1 hours|Th time product data is cached in the basket for. Use a "1 hour" syntax.| +|Display stock as a column|ses_basket.default.stock_in_column: true|True|True - display in column, False - display inline (in product name column).| +|Description character limit|ses_basket.default.description_limit: 50|50|Number of characters that are visible in the description field.| +|Enable additional comment line for basket|ses_basket.default.additional_text_for_basket_line: false|False|If enabled, the customer can add a comment to each line in the basket or quick order.| +|Max. chars for the additional comment line|ses_basket.default.additional_text_for_basket_line_input_limit: 30|30|ERP often has a restriction and may not support long comments. This can lead to errors during the ordering process.| + +## Stored basket + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Display stock as a column|ses_stored_basket.default.stock_in_column: true|True|True - display in column, False - display inline (inside product name column).| +|Description character limit|ses_stored_basket.default.description_limit: 50|50|Number of characters that are visible in the description field.| + +## Wishlist + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Description character limit|ses_wishlist.default.description_limit: 50|50|Number of characters that are visible in the description field| + +## ERP + +Defines the details of data exchange and processes between your shop and your ERP. +ERP integration requires a Web.Connector license or another webservice interface between ERP and the shop. + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Default Country for Template Debitor|siso_core.default.template_debitor_country: DE|DE|Which country is used as a default. Use the country code such as "DE" for Germany.| +|Login with Customer Number|siso_core.default.enable_customer_number_login: false|False|Whether the login process includes a field for providing customer number.| +|Use a template debitor number for this shop|siso_core.default.use_template_debitor_customer_number: true|True|A template debitor customer number is used if a customer does not have a customer number from the ERP. Template debitor customer numbers can be defined for each country.| +|Use a template contact number for this shop|siso_core.default.use_template_debitor_contact_number: true|True|A template contact number is used if a customer does not have a customer and contact number from the ERP. Template contact numbers can be defined for each country.| +|price_requests_without_customer_number/config|siso_core.default.price_requests_without_customer_number: true|True|Whether a price request is sent to the ERP without customer number. A template debitor is used to calculate prices.| +|Recalculate prices using the ERP after|ses_basket.default.recalculatePricesAfter: '3 hours'|True|Information from the ERP is cached to reduce the traffic towards the ERP. Use a "1 hour" syntax.| +|Variants handling in the ERP|silver_eshop.default.erp.variant_handling: SKU_ONLY|SKU_ONLY|Handling of variant products SKU_ONLY - if the ERP system uses different SKUs per variant. SKU_AND_VARIANT - if the ERP system uses a combination of SKU and variant code for variants.| +|URL of the Web-Connector|siso_erp.default.web_connector.service_location:|-|The URL points to the Web.Connector installed by the ERP system. Use an HTTPS connection and make sure that the shop can access this IP and port only.| +|User name (configured per Web-Connector)|silver_eshop.default.webconnector.username: admin|admin|User name for communication with the Web.Connector service.| +|Password (configured per Web-Connector)|silver_eshop.default.webconnector.password: passwo|passwo|Password for communication with the Web.Connector service.| +|SOAP Web-Service timeout in seconds|silver_eshop.default.webconnector.soapTimeout: 5|5|Timeout (web service) for communication with the Web.Connector in seconds.| +|Timeout towards the ERP-System in seconds|silver_eshop.default.webconnector.erpTimeout: 5|5|Timeout (ERP) for communication with the Web.Connector in seconds.| + +## Miscellaneous + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Number of bestsellers displayed on bestseller page|siso_core.default.bestseller_limit_on_bestseller_page: 6|6|The limit of bestsellers that are displayed.| +|Number of bestsellers displayed on catalog pages|siso_core.default.bestseller_limit_on_catalog_page: 6|6|The limit of bestsellers that are displayed.| +|Number of bestsellers displayed in a slider|siso_core.default.bestseller_limit_in_silver_module: 6|6|The limit of bestsellers that are displayed.| +|Threshold bestseller|siso_core.default.bestseller_threshold: 1|1|How often a product has to be bought to count as a bestseller.| + +## Checkout + +Configure your payment and shipping methods. Paypal requires an account. + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Payment method "PayPal"|siso_checkout.default.payment_method.paypal_express_checkout: true|True|Enables PayPal in checkout.| +|Payment method "invoice"|siso_checkout.default.payment_method.invoice: true|True|Enables invoice in checkout.| +|Shipping method "standard"|siso_checkout.default.shipping_method.standard: true|True|Enables shipping method standard in checkout.| +|Shipping method "express"|siso_checkout.default.shipping_method.express_delivery: true|True|Enables shipping method express in checkout.| + +## Fallback configuration for price engine + +Fallback configuration for price engine. It is used, if no shipping costs are set in [price and stock management](manage_prices_and_stock.md). + +|Name|Stored Configuration File|Default|Description| +|--- |--- |--- |--- | +|Fallback costs for shipping|siso_local_order_management.default.shipping_cost: ''|-|Shipping cost in shop currency if free shipping limit is not reached.| +|No shipping costs for orders from amount|siso_local_order_management.default.shipping_free: ''|-|Free shipping limit in shop currency.| +|Fallback VAT Code for shipping costs|siso_core.default.shipping_vat_code: '19'|19|Used for calculating the VAT part for shipping.| + +## Configuration for countries/site accesses + +For some settings the shop requires a country-specific configuration. + +![](img/configuration_settings_EN.jpg) diff --git a/docs/shop_administration/img/backend_menu.png b/docs/shop_administration/img/backend_menu.png new file mode 100644 index 00000000..8d038fb9 Binary files /dev/null and b/docs/shop_administration/img/backend_menu.png differ diff --git a/docs/shop_administration/img/backend_menu_center.png b/docs/shop_administration/img/backend_menu_center.png new file mode 100644 index 00000000..efe1834c Binary files /dev/null and b/docs/shop_administration/img/backend_menu_center.png differ diff --git a/docs/shop_administration/img/browse_content.png b/docs/shop_administration/img/browse_content.png new file mode 100644 index 00000000..55a2c4af Binary files /dev/null and b/docs/shop_administration/img/browse_content.png differ diff --git a/docs/shop_administration/img/browse_products.png b/docs/shop_administration/img/browse_products.png new file mode 100644 index 00000000..5caf44a8 Binary files /dev/null and b/docs/shop_administration/img/browse_products.png differ diff --git a/docs/shop_administration/img/commerce_cockpit.png b/docs/shop_administration/img/commerce_cockpit.png new file mode 100644 index 00000000..6c2953f9 Binary files /dev/null and b/docs/shop_administration/img/commerce_cockpit.png differ diff --git a/docs/shop_administration/img/components_items.png b/docs/shop_administration/img/components_items.png new file mode 100644 index 00000000..18914c59 Binary files /dev/null and b/docs/shop_administration/img/components_items.png differ diff --git a/docs/shop_administration/img/components_menu.png b/docs/shop_administration/img/components_menu.png new file mode 100644 index 00000000..e4af4f22 Binary files /dev/null and b/docs/shop_administration/img/components_menu.png differ diff --git a/docs/shop_administration/img/configuration_settings.png b/docs/shop_administration/img/configuration_settings.png new file mode 100644 index 00000000..7490e48c Binary files /dev/null and b/docs/shop_administration/img/configuration_settings.png differ diff --git a/docs/shop_administration/img/configuration_settings_EN.jpg b/docs/shop_administration/img/configuration_settings_EN.jpg new file mode 100644 index 00000000..c7da36e7 Binary files /dev/null and b/docs/shop_administration/img/configuration_settings_EN.jpg differ diff --git a/docs/shop_administration/img/customer_center.png b/docs/shop_administration/img/customer_center.png new file mode 100644 index 00000000..2d2ff588 Binary files /dev/null and b/docs/shop_administration/img/customer_center.png differ diff --git a/docs/shop_administration/img/customer_center_approval.png b/docs/shop_administration/img/customer_center_approval.png new file mode 100644 index 00000000..82d182d3 Binary files /dev/null and b/docs/shop_administration/img/customer_center_approval.png differ diff --git a/docs/shop_administration/img/ecommerce_jobs.png b/docs/shop_administration/img/ecommerce_jobs.png new file mode 100644 index 00000000..3ad12197 Binary files /dev/null and b/docs/shop_administration/img/ecommerce_jobs.png differ diff --git a/docs/shop_administration/img/econtent.png b/docs/shop_administration/img/econtent.png new file mode 100644 index 00000000..7f4d0342 Binary files /dev/null and b/docs/shop_administration/img/econtent.png differ diff --git a/docs/shop_administration/img/econtent_types.png b/docs/shop_administration/img/econtent_types.png new file mode 100644 index 00000000..f4cce9d5 Binary files /dev/null and b/docs/shop_administration/img/econtent_types.png differ diff --git a/docs/shop_administration/img/email_archive.png b/docs/shop_administration/img/email_archive.png new file mode 100644 index 00000000..4414efcd Binary files /dev/null and b/docs/shop_administration/img/email_archive.png differ diff --git a/docs/shop_administration/img/erp_performance.png b/docs/shop_administration/img/erp_performance.png new file mode 100644 index 00000000..9b5f0233 Binary files /dev/null and b/docs/shop_administration/img/erp_performance.png differ diff --git a/docs/shop_administration/img/erprequest_log.png b/docs/shop_administration/img/erprequest_log.png new file mode 100644 index 00000000..c0dc13f2 Binary files /dev/null and b/docs/shop_administration/img/erprequest_log.png differ diff --git a/docs/shop_administration/img/failed_order_email_admin.png b/docs/shop_administration/img/failed_order_email_admin.png new file mode 100644 index 00000000..0b2c0bc7 Binary files /dev/null and b/docs/shop_administration/img/failed_order_email_admin.png differ diff --git a/docs/shop_administration/img/flexible_categories.png b/docs/shop_administration/img/flexible_categories.png new file mode 100644 index 00000000..cfa18e05 Binary files /dev/null and b/docs/shop_administration/img/flexible_categories.png differ diff --git a/docs/shop_administration/img/import_export_prices.png b/docs/shop_administration/img/import_export_prices.png new file mode 100644 index 00000000..ace33eb1 Binary files /dev/null and b/docs/shop_administration/img/import_export_prices.png differ diff --git a/docs/shop_administration/img/lost_order_details.png b/docs/shop_administration/img/lost_order_details.png new file mode 100644 index 00000000..f397ef5a Binary files /dev/null and b/docs/shop_administration/img/lost_order_details.png differ diff --git a/docs/shop_administration/img/manage_prices_menu.png b/docs/shop_administration/img/manage_prices_menu.png new file mode 100644 index 00000000..e4e157ec Binary files /dev/null and b/docs/shop_administration/img/manage_prices_menu.png differ diff --git a/docs/shop_administration/img/olark_addon.png b/docs/shop_administration/img/olark_addon.png new file mode 100644 index 00000000..a808c086 Binary files /dev/null and b/docs/shop_administration/img/olark_addon.png differ diff --git a/docs/shop_administration/img/olark_alerts.png b/docs/shop_administration/img/olark_alerts.png new file mode 100644 index 00000000..6a544fbf Binary files /dev/null and b/docs/shop_administration/img/olark_alerts.png differ diff --git a/docs/shop_administration/img/olark_chat.png b/docs/shop_administration/img/olark_chat.png new file mode 100644 index 00000000..58075172 Binary files /dev/null and b/docs/shop_administration/img/olark_chat.png differ diff --git a/docs/shop_administration/img/olark_customer.png b/docs/shop_administration/img/olark_customer.png new file mode 100644 index 00000000..ff2c8324 Binary files /dev/null and b/docs/shop_administration/img/olark_customer.png differ diff --git a/docs/shop_administration/img/olark_info.png b/docs/shop_administration/img/olark_info.png new file mode 100644 index 00000000..7e094a0f Binary files /dev/null and b/docs/shop_administration/img/olark_info.png differ diff --git a/docs/shop_administration/img/olark_installation.png b/docs/shop_administration/img/olark_installation.png new file mode 100644 index 00000000..a4818986 Binary files /dev/null and b/docs/shop_administration/img/olark_installation.png differ diff --git a/docs/shop_administration/img/olark_online_offline.png b/docs/shop_administration/img/olark_online_offline.png new file mode 100644 index 00000000..30f91a31 Binary files /dev/null and b/docs/shop_administration/img/olark_online_offline.png differ diff --git a/docs/shop_administration/img/order_management1.png b/docs/shop_administration/img/order_management1.png new file mode 100644 index 00000000..72804ee0 Binary files /dev/null and b/docs/shop_administration/img/order_management1.png differ diff --git a/docs/shop_administration/img/order_management_filter.png b/docs/shop_administration/img/order_management_filter.png new file mode 100644 index 00000000..b7309fb9 Binary files /dev/null and b/docs/shop_administration/img/order_management_filter.png differ diff --git a/docs/shop_administration/img/order_management_filter_1.png b/docs/shop_administration/img/order_management_filter_1.png new file mode 100644 index 00000000..1d701466 Binary files /dev/null and b/docs/shop_administration/img/order_management_filter_1.png differ diff --git a/docs/shop_administration/img/order_management_lost_order.png b/docs/shop_administration/img/order_management_lost_order.png new file mode 100644 index 00000000..edda5f92 Binary files /dev/null and b/docs/shop_administration/img/order_management_lost_order.png differ diff --git a/docs/shop_administration/img/price_management_prices.png b/docs/shop_administration/img/price_management_prices.png new file mode 100644 index 00000000..d6d74704 Binary files /dev/null and b/docs/shop_administration/img/price_management_prices.png differ diff --git a/docs/shop_administration/img/product_assets.png b/docs/shop_administration/img/product_assets.png new file mode 100644 index 00000000..961c580b Binary files /dev/null and b/docs/shop_administration/img/product_assets.png differ diff --git a/docs/shop_administration/img/product_catalog.png b/docs/shop_administration/img/product_catalog.png new file mode 100644 index 00000000..737ed0c5 Binary files /dev/null and b/docs/shop_administration/img/product_catalog.png differ diff --git a/docs/shop_administration/img/product_stock.png b/docs/shop_administration/img/product_stock.png new file mode 100644 index 00000000..69b63e4e Binary files /dev/null and b/docs/shop_administration/img/product_stock.png differ diff --git a/docs/shop_administration/img/product_text.png b/docs/shop_administration/img/product_text.png new file mode 100644 index 00000000..c00200ba Binary files /dev/null and b/docs/shop_administration/img/product_text.png differ diff --git a/docs/shop_administration/img/product_variants.png b/docs/shop_administration/img/product_variants.png new file mode 100644 index 00000000..caf43df5 Binary files /dev/null and b/docs/shop_administration/img/product_variants.png differ diff --git a/docs/shop_administration/img/rating_review.png b/docs/shop_administration/img/rating_review.png new file mode 100644 index 00000000..a4de5cfe Binary files /dev/null and b/docs/shop_administration/img/rating_review.png differ diff --git a/docs/shop_administration/img/roles_dashboard_view.png b/docs/shop_administration/img/roles_dashboard_view.png new file mode 100644 index 00000000..7cf8cecc Binary files /dev/null and b/docs/shop_administration/img/roles_dashboard_view.png differ diff --git a/docs/shop_administration/img/roles_dashboard_view2.png b/docs/shop_administration/img/roles_dashboard_view2.png new file mode 100644 index 00000000..4de17e9b Binary files /dev/null and b/docs/shop_administration/img/roles_dashboard_view2.png differ diff --git a/docs/shop_administration/img/shipping_costs.png b/docs/shop_administration/img/shipping_costs.png new file mode 100644 index 00000000..3e0fc44d Binary files /dev/null and b/docs/shop_administration/img/shipping_costs.png differ diff --git a/docs/shop_administration/img/stock_management.png b/docs/shop_administration/img/stock_management.png new file mode 100644 index 00000000..12a7cce3 Binary files /dev/null and b/docs/shop_administration/img/stock_management.png differ diff --git a/docs/shop_administration/img/sub_categories.png b/docs/shop_administration/img/sub_categories.png new file mode 100644 index 00000000..10009000 Binary files /dev/null and b/docs/shop_administration/img/sub_categories.png differ diff --git a/docs/shop_administration/img/textmodules.png b/docs/shop_administration/img/textmodules.png new file mode 100644 index 00000000..59ac289a Binary files /dev/null and b/docs/shop_administration/img/textmodules.png differ diff --git a/docs/shop_administration/img/textmodules_1.png b/docs/shop_administration/img/textmodules_1.png new file mode 100644 index 00000000..9d71a0a3 Binary files /dev/null and b/docs/shop_administration/img/textmodules_1.png differ diff --git a/docs/shop_administration/img/textmodules_2.png b/docs/shop_administration/img/textmodules_2.png new file mode 100644 index 00000000..c654a304 Binary files /dev/null and b/docs/shop_administration/img/textmodules_2.png differ diff --git a/docs/shop_administration/img/textmodules_footer.png b/docs/shop_administration/img/textmodules_footer.png new file mode 100644 index 00000000..53e39c19 Binary files /dev/null and b/docs/shop_administration/img/textmodules_footer.png differ diff --git a/docs/shop_administration/img/translate_edit_content.png b/docs/shop_administration/img/translate_edit_content.png new file mode 100644 index 00000000..2aa36bd3 Binary files /dev/null and b/docs/shop_administration/img/translate_edit_content.png differ diff --git a/docs/shop_administration/img/user_account_status.png b/docs/shop_administration/img/user_account_status.png new file mode 100644 index 00000000..105c38cc Binary files /dev/null and b/docs/shop_administration/img/user_account_status.png differ diff --git a/docs/shop_administration/img/user_detaild_view.png b/docs/shop_administration/img/user_detaild_view.png new file mode 100644 index 00000000..089dfe2a Binary files /dev/null and b/docs/shop_administration/img/user_detaild_view.png differ diff --git a/docs/shop_administration/img/user_edit.png b/docs/shop_administration/img/user_edit.png new file mode 100644 index 00000000..0f6fe91a Binary files /dev/null and b/docs/shop_administration/img/user_edit.png differ diff --git a/docs/shop_administration/img/user_group.png b/docs/shop_administration/img/user_group.png new file mode 100644 index 00000000..1fe73062 Binary files /dev/null and b/docs/shop_administration/img/user_group.png differ diff --git a/docs/shop_administration/img/users_menu.png b/docs/shop_administration/img/users_menu.png new file mode 100644 index 00000000..0d9ba1f9 Binary files /dev/null and b/docs/shop_administration/img/users_menu.png differ diff --git a/docs/shop_administration/manage_orders.md b/docs/shop_administration/manage_orders.md new file mode 100644 index 00000000..05d93e9e --- /dev/null +++ b/docs/shop_administration/manage_orders.md @@ -0,0 +1,72 @@ +# Manage orders + +## Order management + +eZ Commerce provides a list of all orders in **eZ Commerce** > **Order Management**. + +![](img/order_management1.png) + +You can check, filter and export all orders that were processed in the shop. +Additionally, you can see the invoice that was automatically generated by the shop for the order (if no ERP is connected). + +### Available filters + +![](img/order_management_filter.png) + +You can filter orders using the following criteria: + +- Date - last month by default. +- State: + - Confirmed + - Payed + - Order failed - the order could not be transferred to the ERP, the shop retries sending it + - New - baskets which are not yet sent + - Offered - baskets in the payment process + - Approval - orders using an approval workflow + - Rejected - orders refused by the approver +- Payment option - the list has to be configured in the section **Configuration settings** under **Checkout**. +- Payment transaction ID. + +### Order list + +![](img/order_management_filter_1.png) + +- Basket ID - ID of the basket stored in the database +- Date - date and time this basket was last modified +- Customer name +- Total - total amount from the basket including VAT and shipping costs +- State - state of the basket +- Invoice +- Click on the plus icon to see the following information: + - Transaction ID - if the order has been paid using an electronic payment, the transaction code is displayed + - Payment options + - Invoice Address + - Delivery Address + - Products - list of products (SKU) and the quantity + +When an ERP system is used, the orders are transferred to the ERP. +In that case the shop does not create invoices, so no invoice is available in order management, +but you can still check orders in this section. + +### Lost orders + +If the ERP system is not running at the moment, eZ Commerce can store the orders and retransmit them when the ERP is working. +The orders are stored in a database table and marked for retransmission. The shop records the number of retries. +By default the maximum number is 3 (`siso_checkout.default.max_failed_order`). + +The shop sends an email to the shop administrator describing details of the order: + +![](img/failed_order_email_admin.png) + +Order submission can fail for different reasons, for example because the ERP system is offline, credit limit has been reached, or invalid SKU was provided. + +You can view all lost orders by selecting "Order failed" as order state. + +![](img/order_management_lost_order.png) + +#### Re-transfering lost orders + +Select the order you want to transfer and click **Transfer to ERP**. +The order is sent to the ERP and after a few seconds you see a message: + +![](img/lost_order_details.png "Details of a lost order") diff --git a/docs/shop_administration/manage_prices_and_stock.md b/docs/shop_administration/manage_prices_and_stock.md new file mode 100644 index 00000000..8c5ee1a8 --- /dev/null +++ b/docs/shop_administration/manage_prices_and_stock.md @@ -0,0 +1,49 @@ +# Manage prices and stock + +![](img/manage_prices_menu.png) + +## Product prices + +![](img/price_management_prices.png) + +You can set up product prices if the shop price provider (`siso_price.price_provider.shop`) is configured for calculating prices. + +Price management enables you to set up prices manually. A price can be setup per SKU and SKU/variant. +Each price can contain an offer price and a base price. +If an offer price is set, it is displayed in the shop as: + +~~Old price: 10.00 €~~ New price: 9.80 € + +In addition, prices can vary per customer group. + +### Currencies + +Currency is configured per country in the [configuration settings](https://doc.ezplatform.com/en/master/guide/configuration/configuration.md#currencies-used-per-country). + +If a product has a price for a product and a currency, this price is displayed in the shop. +If no price for a currency is set in a shop, eZ Commerce offers two possibilities, configured per shop: + +- Calculate the price for the requested currency using the base price defined in the product +(using the base currency setup for the installation) and an exchange rate defined in the configuration +- Display an error in the frontend that no price is available + +## Stock management + +![](img/stock_management.png) + +This menu enables you to set up stock if the shop price provider (`siso_price.price_provider.shop`) is configured for calculating prices. + +## Importing and exporting prices and stock + +![](img/import_export_prices.png) + +You can update stock and prices using a CSV file. +Prices and stock can be downloaded and uploaded if the shop price provider (`siso_price.price_provider.shop`) is configured for calculating prices. + +## Shipping costs + +![](img/shipping_costs.png) + +In **Shipping cost management** you can set up shipping cost rules. Shipping rules can be managed per delivery country, state, zip and shipping method. + +You can also configure different shipping costs depending on the amount of the basket (including free shipping rules). diff --git a/docs/shop_administration/manage_products_and_categories_with_the_ez_dataprovider.md b/docs/shop_administration/manage_products_and_categories_with_the_ez_dataprovider.md new file mode 100644 index 00000000..ce926dd6 --- /dev/null +++ b/docs/shop_administration/manage_products_and_categories_with_the_ez_dataprovider.md @@ -0,0 +1,58 @@ +# Manage products and categories + +## Managing categories + +When you use the content model data provider, the product catalog is fully integrated into the content tree. The products are managed as Content items. + +![](img/browse_products.png) + +![](img/product_catalog.png) + +Products and categories can be assigned to the product catalog. + +![](img/sub_categories.png) + +## Flexible categories + +A category contains a standard set of fields. A category is a Content Type and can be extended with additional fields. + +![](img/flexible_categories.png) + +## Previewing products + +While editing a product the preview displays how the product looks on desktops or mobile devices, including product variants. + +![](img/product_text.png) + +## Product variants + +eZ Commerce offers one or two level variants. A variant can be added directly in the product view. + +There are three preconfigured variant types: Color, Size, and Color and Size. + +The list of variant types can be extended in the configuration. + +![](img/product_variants.png) + +## Product assets + +eZ Commerce supports assets per product (not per variant). +By default a product can have one main image and up to three additional images, +one PDF, and one link to a video (e.g. YouTube). + +![](img/product_assets.png) + +## Product stock + +The stock can be managed by SKU and SKU/variant. This can be done manually or per upload. + +In addition, you can add a text about stock availability (e.g. informing that a product is out of stock but will be back on a given date). +After an order is placed, the stock is reduced by the number of products bought by the customer. + +You can manage stock in two places: + +1\. In the product in the **eCommerce** tab: + +![](img/product_stock.png) + +2\. In the **eCommerce** section under [**Price and stock management**](manage_prices_and_stock.md). diff --git a/docs/shop_administration/manage_users.md b/docs/shop_administration/manage_users.md new file mode 100644 index 00000000..5ec43bea --- /dev/null +++ b/docs/shop_administration/manage_users.md @@ -0,0 +1,17 @@ +# Manage users + +Users are displayed in the **Users** tab in th Back Office. + +![](img/users_menu.png) + +The **eCommerce** tab in User content view contains an overview of the user's orders and active baskets. + +![](img/user_detaild_view.png) + +Budget fields in the User Content item are related to Customer center. + +VAT control per user is overwritten by information from ERP. + +The current Account status is shown in the view tab of a user. + +![](img/user_account_status.png) diff --git a/docs/shop_administration/permissions.md b/docs/shop_administration/permissions.md new file mode 100644 index 00000000..80a6d309 --- /dev/null +++ b/docs/shop_administration/permissions.md @@ -0,0 +1,41 @@ +# Permissions + +By default eZ Commerce offers the following predefined Roles: + +| Role | Functions | +| -------| ------------| +| Ecommerce anonymous | Allows a user to see the content and catalog. They can see prices and can place products in basket. | +| Ecommerce checkout | Allows the user to go through the checkout and place an order.| +| Ecommerce registered users | Allows the user to manage the accounts of the registered users. | + +## List of available eZ Commerce modules and functions + +|Name|Description| +|--- |--- | +|Siso policy / All functions|User has access to all functions| +|Siso policy / Checkout|User can access the checkout process| +|Siso policy / Quickorder|User can access the quick order functionality| +|Siso policy / Read basket|User can access their basket view| +|Siso policy / Write basket|User can add products to basket| +|Siso policy / Configuration list|User can access configuration in the Back Office| +|Siso policy / Edit invoice|User can edit invoice address in their profile| +|Siso policy / Edit delivery|User can edit delivery address in their profile| +|Siso policy / Dashboard view|User can access the dashboard| +|Siso policy/ Forms profile edit|User can access profile editing| +|Siso policy / Manage orders|User can manage orders| +|Siso policy / Manage rating|Unused| +|Siso policy / Manage prices|User can manage prices| +|Siso policy / Manage stock|User can manage stock| +|Siso policy / Manage config|User can manage configuration settings| +|Siso policy / Order list|User can access their list of orders| +|Siso policy / See product price|User can see prices in the catalog, slider, product detail and comparison| +|Siso policy / Translations|User can change translations in the Back Office| +|Siso policy / Rating review|Unused| +|Siso policy / Red customers and orders|User can see the **Last orders** and **Best clients** tabs in the cockpit| +|siso_customercener/approve|Company user can approve/reject orders in the Customer center| +|siso_customercenter/buy|Company user can buy products in the Customer center| +|siso_customercenter/view|Company user can access te Customer center| +|Siso policy / Lostorder manage|User can access the lost orders list| +|Siso policy / Lostorder process|User can process a lost order (transfer it or remove it)| +|Siso policy / Lostorder list|User can access their list of lost orders| +|Siso policy / Delegate|User can use the delegate functionality| diff --git a/docs/shop_administration/shop_administration.md b/docs/shop_administration/shop_administration.md new file mode 100644 index 00000000..65e4955c --- /dev/null +++ b/docs/shop_administration/shop_administration.md @@ -0,0 +1,64 @@ +# Shop administration + +eZ Commerce provides the following eCommerce functions in the top menu of the backend. + +Depending on the chosen data provider and whether an ERP is connected, some tabs may contain no data. + +![](img/backend_menu.png) + +|Tab|Description| +|--- |--- | +|[Cockpit](cockpit.md)|Basic statistics| +|[Order Management](manage_orders.md)|Basic order management| +|[Components](components.md)|A folder where [translations](translations.md) are stored. Can provide additional content which is used by the shop for project-specific information which is not displayed directly (as a full page) in the shop.| +|[Configuration Settings](configuration_settings.md)|Basic shop configuration| +|[Price and stock management](manage_prices_and_stock.md)|Product price and stock management| + +## Control Center + +![](img/backend_menu_center.png) + +### ERP request log + +This section is available only if an ERP system is connected. + +All communication (request and response messages), that is sent between shop and ERP system is recorded and displayed here. + +![](img/erprequest_log.png) + +### ERP Performance + +If an ERP system is connected, the ERP performance viewer shows the efficiency of the connection between the shop and the ERP system. +It displays the number of the different requests per date and time. + +The monitoring tool regularly checks the connection to the ERP with a test request. + +If the connection fails, the administrator receives an email. +If the connection is successful again, the alarm is ended by another email. + +![](img/erp_performance.png) + +### eMail archive + +In the **eMail archive** tab the shop owner/admin can find all emails which were automatically sent from the shop, +with date of sending, recipient, subject and status. They can see the emails and resend them. + +![](img/email_archive.png) + +### eContent + +If eContent is used as data provider, in the **eContent tasks** tab the administrator can see how many products and product groups there are in the shop. +They can create a new index, import a backup into the database and create a backup from the database. + +![](img/econtent.png) + +In the **eContent types** tab the administrator can see the eContent types with their associated attributes (`product_group` and `product`) and the mapping information. + +![](img/econtent_types.png) + +### eCommerce jobs + +The shop uses jobs to perform recurring tasks such as imports, backups etc. +The job system lists the last jobs and shows the status and result of the job. + +![](img/ecommerce_jobs.png) diff --git a/docs/shop_administration/translations.md b/docs/shop_administration/translations.md new file mode 100644 index 00000000..4d7ad64e --- /dev/null +++ b/docs/shop_administration/translations.md @@ -0,0 +1,40 @@ +# Translations + +## Text modules + +Text module is a special Content item in eZ Commerce. +It enables the shop owner or editor to translate some of the text information in the shop using the Online Editor. + +Text modules are used for some short explanatory texts in the shop. +Every text module has a unique identifier. + +This identifier must match exactly and cannot be changed even with text changes. +If a text module has not yet been translated, the identifier is displayed in the frontend. + +### Example + +To create a text for the site footer, go to the **Components** section, +to **Textmodules** > **Footer** and choose "Footer block address". + +Edit this Content item and select the correct language, introduce your changes and publish the content. + +![](img/textmodules_1.png) + +![](img/textmodules_2.png) + +You can see the result when you reload the page. + +![](img/textmodules_footer.png) + +### Caching + +Text modules are cached. You can [refresh the text modules](https://doc.ezplatform.com/en/master/guide/cache/content_cache_refresh/content_cache_refresh.md) when they are edited. +Workflows and cron job have to be configured for that. + +However, if the full page is cached in HTTP cache, the new translation for the text module appears after the HTTP cache expires or is removed. + +## Working with OneSky + +[OneSky](https://www.oneskyapp.com/) is an external platform for managing translations. You can use this platform to offer a user interface for translations management. + +See [OneSky in the guide](https://doc.ezplatform.com/en/master/guide/translations/onesky.md) to learn how to set up OneSky for your shop. diff --git a/mkdocs.yml b/mkdocs.yml index a353d4b8..4f6458ce 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,34 @@ nav: - 'Multi-file content management': 'site_organization/multi_file_content_management.md' - 'Working with Page': 'site_organization/working_with_page.md' - 'Searching': 'search.md' + - Shop administration: + - 'Shop administration': 'shop_administration/shop_administration.md' + - 'Cockpit': 'shop_administration/cockpit.md' + - 'Components': 'shop_administration/components.md' + - 'Configuration settings': 'shop_administration/configuration_settings.md' + - 'Manage orders': 'shop_administration/manage_orders.md' + - 'Manage prices and stock': 'shop_administration/manage_prices_and_stock.md' + - 'Manage products and categories': 'shop_administration/manage_products_and_categories_with_the_ez_dataprovider.md' + - 'Manage users': 'shop_administration/manage_users.md' + - 'Permissions': 'shop_administration/permissions.md' + - 'Translations': 'shop_administration/translations.md' + - 'Olark chat tool': 'shop_administration/chat_tool_olark.md' + - Managing shop content: + - 'Embed product': 'managing_shop_content/embed_product.md' + - 'Pages in the shop': 'managing_shop_content/landingpages.md' + - 'Navigation structure': 'managing_shop_content/navigation_structure.md' + - 'Legal documents': 'managing_shop_content/legal_documents.md' + - Personalization: + - 'Personalization': 'personalization/personalization.md' + - 'Use cases': 'personalization/use_cases.md' + - 'Dashboard': 'personalization/dashboard.md' + - 'Event Types': 'personalization/event_types.md' + - 'Content Types': 'personalization/content_types.md' + - 'Recommendation models': 'personalization/recommendation_models.md' + - 'Filters': 'personalization/filters.md' + - 'Scenarios': 'personalization/scenarios.md' + - 'Content import': 'personalization/content_import.md' + - 'User data import': 'personalization/user_data_import.md' - 'FAQ': 'faq.md' theme: name: null @@ -57,10 +85,6 @@ extra: url: '/projects/userguide' - title: 'eZ Platform Developer Documentation' url: '/' - - title: 'eZ Personalization Documentation' - url: '/projects/ezpersonalization' - - title: 'eZ Commerce' - url: '/projects/ezcommerce' extra_css: - fonts/MavenPro.css