README

Install package using composer

composer require tweakwise/magento2-tweakwise

This will install tweakwise/magento2-tweakwise and tweakwise/magento2-tweakwise-export

Enable module(s) and run installers

php bin/magento module:enable Tweakwise_Magento2TweakwiseExport Tweakwise_Magento2Tweakwise
php bin/magento setup:upgrade
php bin/magento setup:static-content:deploy

Configuration

When the extension is installed it is disabled by default. There are three different parts which can be enabled separately. Configuration can be found at Stores -> Configuration -> Catalog -> Tweakwise.

Rundown of all possible settings

Below is a rundown of all configuration options

General:

Authentication key: This is used to communicate with tweakwise and determines your navigator instance, it should be the same as the key found in the navigator under Connectivity > End points.
Server url: The url of the tweakwise server.
Timeout: If tweakwise fails to respond after this time in seconds the request is aborted.

Layered Navigation (All settings depend on Enabled having value yes):

Enabled: Use tweakwise results in navigation, if disabled the standard magento navigation is used. Don't disable the anchor tag on main categories, this causes al products to be shown. The anchor tag can be disabled on sub-categories.
Hide facets with only one option: Given a result set from tweakwise in which a filter has only one option show that filter or not?
Use default magento filter renderer: Use Magento standard filter templates or use templates bundled by the module. If you want to make full use of the features provided by this module then this should be set to No (i.e. make use of tweakwise template files).
Filter form: This depends on 'Use default magento filter renderer' having value No. Render all filters in a form with filter buttons so that the user can select a set of filters and then navigate to the result instead of immediately navigating to the results when a filter is clicked.
Filter url query parameters: Tweakwise filter urls will have all query parameters of the page in it so also the "cid" and utm_source parameters if present. You can determine in which way you want to filter these out (if any).
Filter url query arguments: This depends on 'Filter url query parameters' having any value not equal to 'Dont Filter'. This field specifies which parameters should be removed from the tweakwise filter urls.
Url strategy: Has two options Query parameters and Seo path slug. If query parameters is selected then the tweakwise filter urls (and thus your navigation urls) will be constructed as www.example.com/example-category?color=red.

If Seo path slugs is selected the url is constructed as www.example.com/example-category/color/red.

Seo (All settings depend on Enabled having value yes)

Enabled: use Seo options yes or no.
Filter whitelist: A list of filters which should be indexable (all filters not selected here are not indexable). If a filter is marked as not indexable then its href attribute will be set to "#" its original url will be set in a data-seo-href attribute which will be used by javascript to navigate. Note that the category filter is always marked as indexable. This used to be a multiselect field containing magento attributes however tweakwise facilitates derived properties, these properties are not related to magento attributes and as such these filters would be not indexable. The field has changed to a comma separated text field so that these derived properties can be properly whitelisted.
Max allowed facets: This combines with the Filter whitelist setting. Filters are indexable if and only if they are in the whitelist and the selected filter count does not go above max_allowed_facets. The reason this is an AND check is because otherwise indexation will still happen on the non whitelisted filters and it is unclear which url is present (an arbitrary amount of filters could be selected). Suppose max allowed facet is 1 and only "size" is in the whitelist. Then filter "color" with value "red" is not indexable (since "color" is not in the whitelist). If we now allow the size filter to still be indexable then url example.com/category/color/red/size/M would be indexable whereas example.com/category/color/red is not which is incorrect. This would lead to infinite crawling on filter urls which is undesirable

Autocomplete (All settings depend on Enabled having value yes)

Enabled: Use tweakwise autocomplete results or not.
Use Suggestions Autocomplete: Use new suggestion api (Yes) or use the standard autocomplete api (No)
Show products *: Show product suggestions in autocomplete results.
Show suggestions *: Show search suggestions in autocomplete results.
Stay in category: Use the current category when getting autocomplete results.
Maximum number of results *: At most this many autocomplete results will be show.

Hidden when Use Suggestions Autocomplete is enabled. These settings are not used in the new suggestions api. The new suggestions api is configured in tweakwise itself.

Search (All settings depend on Enabled having value yes)

Enabled: Use tweakwise search of default magento search results
Tweakwise search template: The tweakwise template to use for search results (this determines which filters are visible)
Search language: This determines the language used by the store and is passed to tweakwise. Tweakwise uses this to determine word conjugations and also correct spelling errors when considering which results should be shown to the user. An example: suppose Language is set to 'Dutch' and the user types 'Bed' (which is the same in English, namely the place where one sleeps) then tweakwise might suggest 'Bedden' (this is plural for 'Beds') If Language is set to English then in the example above tweakwise might suggest 'Beds'.
Searchbanners enabled: Show searchbanners in the search results. The searchbanners need to be configured in tweakwise.

Merchandising Builder

Enabled: Use Merchandising Builder (Yes/No) This is only available if you use ajax filtering.
Cookie name: The cookie which holds the tweakwise profile id, this cookie is (usually) set with a tracking script. The value of this cookie will be added to the tweakwise request, the response will contain a personalized sort order for that particular customer.

Note that enabling these settings has consequences for performance. Using this feature means that all category pages have personalized content. As such, it is no longer possible cache navigation responses where this profile cookie name has been used. If a category page is cached in varnish (which it usually is) the varnish version is still served, however we reload the product list via ajax to get the personalized sort order. We do not add the profile cookie to non-ajax navigation requests, this is done so that normal requests can still be cached by varnish. This means that the user is greeted by a loader. The product list is reloaded if and only if the following conditions are met:

Personal merchandising setting is enabled
Cookie name setting has a value
The user has the specified cookie with a non empty value.

When the product list is loaded in such a manner the result will not be cacheable. This has consequences for server load keep this in mind.

Recommendations

Related products enabled: Replace magento native related products with tweakwise crosssell & upsell recommendations. Terminology is confusing since this is relevant for magento related products and not for magento crosssell products
Default related products template: Which tweakwise recommendation template to use for related products. Only relevant when crosssell is enabled This can also be configured on a product and on a category. The template used is determined as follows: first check product for a configured template if not then check the product category for a template. If the category does not have a template configured then use the default.
Default related group code: Only visible when Default crosssell template has value '- Group Code -'. Use this to specify the group of recommendations
Upsell Enabled: Replace magento native upsell results with tweakwise crosssell & upsell recommendations.
Default upsell template: Which template recommendation template to use for upsell products. Only relevant when upsell is enabled. This can also be configured on a product and on a category. The template used is determined as follows: first check product for a configured template if not then check the product category for a template. If the category does not have a template configured then use the default.
Default upsell group code: Only visible when Default upsell template has value '- Group Code -'. Use this to specify the group of recommendations
Featured products enabled: If yes then tweakwise can show featured products on category pages.
Default Featured product template: The default template to use when rendering featured products. The template can also be set per category and falls back to this setting if not found on the category. The templates that can be selected correspond with the templates under 'recomendations->featured products' in tweakwise.
Show Cross-sell items in the shoppingcart. Enables tweakwise cross-sell items in the shoppingcart. Magento shoppingcart crossell items should also be enabled under 'Stores->configuration->sales->checkout->Show Cross-sell items in the Shopping Cart'
Default crosssell template. Which tweakwise recommendation template to use for shoppingcart crossell items. Only relevant when shoppingcart crosssell is enabled
Default crosssell group code: Only visible when Default shoppincart crosssell template has value '- Group Code -'. Use this to specify the group of recommendations
Crossell type: show crossell or featured products in shoppingcart
Only show products from current category for featured products: Show product from current category in featured products.
Limit group code recommendations: If group code is used for one/more recommendations, limit the total number of products returned. If empty or 0, all products are returned.

Support

For in depth support regarding configuration and all options tweakwise has to offer use the following links.

Tweakwise support: https://www.tweakwise.com/support/
Tweakwise api documentation: http://developers.tweakwise.com/
General questions: https://www.tweakwise.com/contact/
Security vulnerabilities: Send an email to support@tweakwise.com, with the message that it's an security issue for the magento plugin

For feature requests we refer to the links above. For technical issues github is used. If you find a technical issue please create an issue on github and notify tweakwise via the links above. If you also happen to have the solution to that issue feel free to create a merge request.

Compatibility

We strive to remain compatible with all Magento 2.X versions and the latest 2.X-1 version where X is the highest Magento official 'sub' release. Currently X=4 hence we should be compatible with all 2.4 versions and the latest 2.3.x version. We do not actively drop support for versions below this range and will implement minor changes if that means we can remain compatible with versions below this range. That being said if we can do a massive simplification of code at the cost of dropping support for version 2.3.Y we will do so. We also refer to the magento software lifecycle: https://magento.com/sites/default/files/magento-software-lifecycle-policy.pdf. Note that 2.3 is End Of Life.

Contributors

If you want to create a pull request as a contributor, use the guidelines of semantic-release. semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package. By adhering to the commit message format, a release is automatically created with the commit messages as release notes. Follow the guidelines as described in: https://github.com/semantic-release/semantic-release?tab=readme-ov-file#commit-message-format.

tweakwise / magento2-tweakwise

Maintainers

Details