Installation

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:

1. 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.
2. Grouped producets: Enable this after the grouped export has been enabled and imported in tweakwise. This wil enable filtering based on variant data and enabled the product image to be controlled by tweakwise so that the correct color is shown based on selected filters. This requires the image url in tweakwise to be configured correctly. If this is not enabled and you've exported grouped products the catalog may be empty.

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

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

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

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

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

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

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

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

1. Enabled: use Seo options yes or no.
2. 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.
3. 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)

1. Enabled: Use tweakwise autocomplete results or not.
2. Use Suggestions Autocomplete: Use new suggestion api (Yes) or use the standard autocomplete api (No)
3. Show products *: Show product suggestions in autocomplete results.
4. Show suggestions *: Show search suggestions in autocomplete results.
5. Stay in category: Use the current category when getting autocomplete results.
6. 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)

1. Enabled: Use tweakwise search of default magento search results
2. Tweakwise search template: The tweakwise template to use for search results (this determines which filters are visible)
3. 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'.
4. Searchbanners enabled: Show searchbanners in the search results. The searchbanners need to be configured in tweakwise.

Merchandising Builder

1. Enabled: Use Merchandising Builder (Yes/No) This is only available if you use ajax filtering.
2. 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 Varnish must be enabled for this functionality to work correctly. Varnish is recommended by Magento anyway. The big advantage of Varnish Cache is of course the gain in speed. In addition, it ensures a lower load on the server and thus increases peak resistance.
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.
The product list is loaded via the merchandising builder only if the following conditions are met:

1. Personal merchandising setting is enabled
2. Cookie name setting has a value
3. 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

1. 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
2. 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.
3. Default related group code: Only visible when Default crosssell template has value '- Group Code -'. Use this to specify the group of recommendations
4. Upsell Enabled: Replace magento native upsell results with tweakwise crosssell & upsell recommendations.
5. 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.
6. Default upsell group code: Only visible when Default upsell template has value '- Group Code -'. Use this to specify the group of recommendations
7. Featured products enabled: If yes then tweakwise can show featured products on category pages.
8. 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.
9. 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'
10. Default crosssell template. Which tweakwise recommendation template to use for shoppingcart crossell items. Only relevant when shoppingcart crosssell is enabled
11. Default crosssell group code: Only visible when Default shoppincart crosssell template has value '- Group Code -'. Use this to specify the group of recommendations
12. Crossell type: show crossell or featured products in shoppingcart
13. Only show products from current category for featured products: Show product from current category in featured products.
14. 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.

Command

There is an command for regenerting filter urls. This is only relevant when using SEO path slug urls. Only run this command to regenerate the urls if you have problems.
Running this command may change the filter urls and thus may have SEO implications. The command can be run manually using:

php bin/magento tweakwise:regenerate-filter-urls

Support

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

1. Tweakwise support: https://www.tweakwise.com/support/
2. Tweakwise api documentation: http://developers.tweakwise.com/
3. General questions: https://www.tweakwise.com/contact/
4. Security vulnerabilities: Send an email to [email protected], 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.

6.0.0 (2024-04-12)

Features

• searchable filters (#166) (bebd6c6)

Performance Improvements

• Applied phpcs and phpmd rules (9a499fd)

BREAKING CHANGES

• Code is refactored based on phpcs and phpmd rules.

6.0.0-beta.2 (2024-04-09)

Features

• searchable filters (#166) (bebd6c6)

6.0.0-beta.1 (2024-03-29)

Performance Improvements

• Applied phpcs and phpmd rules (9a499fd)

BREAKING CHANGES

• Code is refactored based on phpcs and phpmd rules.

Changelog

5.0.0

Backward incompatible changes

• Change repository to tweakwise repo. You need to uninstall the old tweakwise package en reinstall this one

5.0.1

Update module with changes from emico/tweawise v4.3.0

5.0.2

Bug fix for 500 error in autocomplete when no products are found

5.0.3

Bug fixes for autocomplete

• Old autocomplete api is still called when new suggestion api is enabled.
• When using the suggetions api, if the result contains an category you get an 500 error.

5.0.4

Bug fix for areacode in config
Updated readme

5.0.5

Bug fix for personal merchandising hyva theme

5.0.6

Bug fix adobe commerce

5.0.7

Bug fix show parent in autocomplete settings
Bug fix for commerce, searching is slow and wrong item count in hyva theme

5.0.8

Bug fix for installer when using an db prefix

5.1.0

• Added support for searchbanners. Show searchbanners in search results. Configure this in tweakwise. Only setting in magento is to enable/disable showing searchbanners
• Bug fix upsell/crossell templates

5.1.1

• Bug fix deprecated ctype function
• Bug fix swatch order
• Fix float and 0 prices

5.1.2

• Escape clear url

5.2.0

• Feature shoppingcart recommendations from tweakwise
• Bug fix ajax query url

5.2.1

• Bug fix upselll plugin not triggered

5.3.0

• Limit group code recommendations by @ah-net in #40
• Rename recommendations by @ah-net in #32
• add category to featured request by @ah-net in #42
• Feature shoppingcart crosssell featured by @ah-net in #35
• php8.2 by @ah-net in #43
• Added php 8.2 support, and droppend php 7.4 support

5.3.1

• Bug fix for slash in category url #45

5.3.2

• Fixed bug with undifined function

5.3.3

• Updated composer.json, removed wrong conflict value

5.4.0

• Fixed php 8.2 bug #53
• Fixed bug when search was enabled #46
• Speed improvement. Removed multiple spaces fram html response #50
• Remove container css class from searchbanners #49
• Improved XSS protection #47

5.4.1

• Fixed bug in observer #57
• Fixed items typo #59
• Hide categorie in url #55
• Bugfix category rewrite #56
• Improve query param url generation #37
• Add tn profile key to suggestions #58

5.4.2

• Fixed php 8.2 bug #61
• Use salt from db instead of session for xss hash

5.4.3

• Removed undefined index #64
• Revert changes from pull request #56. That pull request causes issues with the category url. The original issue from #56 will be fixed later

v5.4.4

• Fix category url if url is rewrite #67

5.4.5

• Bugfix search query parameters #69
• Delete p=1 indicator for first page #68
• Fix pagination/sorting url #72

5.5.0

• Add fallback for category recommendations #71

5.5.1

• Bump version number #73

5.5.2

• Return last added item back in around plugin #75

5.6.0

• Fix bug with multiple filters selected #84
• Rewrite fallbck #70

5.6.1

• Bump version nr

5.6.2

• Bugfix query parameters with multiple filters selected #87
• Bugfix check hash value on page load #86

5.6.3

• Revert fix fallback #70

5.6.4

• Bump version nr

5.6.5

• Fix store code in url #90
• Bugfix guzzle library #93

5.7.0

• Merge query parameters back after tweakwise personal merchandise refresh #83
• Bugfix fallback prduct collection #91
• Fix empty search result #96
• Feature facets requests #97
• Feature server timing #102

5.7.1

• Fix undefined array key #106

5.7.2

• Fix wrong variable check causing active filters to not be shown #110

5.7.3

• Remove category filter for facets requests #111
• Fix bug in tncid in recommendations #109

5.7.4

• Fix bug resulting in active filters not being shown
• Added ci pipeline to run unit tests
• Added support for multiple stores for ALP facets requests
• Rename personal merchandising
• Fix bug when searchbanners response is empty
• Fix bug in last item added to shoppingcart, should be removed after reading
• Disable searchbanners when search is disabled
• Items misspelled causing a lookup to Tweakwise not to be used

5.7.5

• Resolved an XSS security vulnerability linked to product sorting.
• Fixed an issue causing JavaScript errors with the hyva theme and ajax navigation.
• Enhanced SEO by removing 'p1' from URLs; this issue specifically affected the query parameter strategy for URLs.
• Rectified a bug causing an undefined index in active filters while using the ALP module.
• Addressed a problem where 404 errors were logged in Magento when_ a product, no longer available in Tweakwise (e.g., out of stock), still had recommendations called. This change prevents such 404 errors from being logged.
• Fixed an issue causing double filter values in URLs. This occurred when activating a filter while personal merchandising was active, resulting in incorrect filter URLs with doubled values.
• Improved handling of double values in URL filters. Now, only consecutive double values, such as '/category/category, are removed. This also removes unwanted double slashes in the url.
• Cleaned up unused imports
• Prevented category ID from being added to the URL during certain category searches, ensuring URL consistency

5.8.0

The category view in Magento differs from the way it is presented in Tweakwise Demoshop, which we considered to be the desired behavior. The difference is related to the way how (sub)category levels are shown.

We've added a setting in which you can define whether to use the old/existing way of presenting, or whether you want to use the desired way of presenting. The setting 'category view' which you can find under "Stores->Catalog->Tweakwise->Layered Navigation->Category View" is set default to 'simple'. This represents the old way of presenting and nothing will change if you do not touch this setting. If the setting is changed to 'extended', the category view is changed to the same view as the Tweakise demoshop

5.8.1

• Resolved an issue where the category filter was not considering the current applied filter, specifically when the query parameter strategy was enabled.
• Fixed a bug where sending the root category in Tweakwise requests resulted in 500 errors.
• Addressed an issue where a page reload caused the URL to be incorrect, preventing filters from deactivating.
• Implemented a check to verify if an item is a Tweakwise filter, preventing 500 errors when the Tweakwise API doesn't respond.

5.8.2

• Resolved an issue where the incorrect parent category was utilized while navigating a category tree that is three levels deep.
• Resolved an issue where the filter parameter remained in the URL after deactivating the filter.
• Resolved an issue where, with the URL pathslug strategy enabled, selecting a filter on a category page would lead to an incorrect URL upon refreshing the page and selecting another filter.
• Bugfix implemented to address the duplication of category names in the default Magento renderer.
• Implemented query length limitation for search to prevent a 500 error.
• Implemented a preventive measure to avoid errors when no attribute values are present for ALP facet requests.
• Resolved the issue with personal merchandising and pagination not functioning correctly when utilising the filter form.
• Implemented measures to prevent a 500 error in the search when Tweakwise is inaccessible or down.

5.8.3

• Implemented prevention of duplicate attribute slug values. Previously, attribute values with variations in their representations, such as Black and Black", resulted in duplicate entries in the tweakwise_attribute_slug table. This duplication could disrupt filter functionality if the incorrect value was retrieved. This pull request addresses the issue by appending a unique identifier ("-") followed by a number to each slug, ensuring their uniqueness. Note that attributes with previously duplicated slug values will require re-saving to activate this fix.
• Resolved a notice issue pertaining to missing variables when the shopping cart is empty. Previously, certain sections of the application would trigger notices due to uninitialized variables when the cart was empty.