Merge in personalization doc

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).

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)

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.

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.|