Tagalys installation and setup on Magento 2
Sign up for a Tagalys account
Sign up for a Tagalys account
Copy your API credentials
Sign up for a Tagalys account at https://next.tagalys.com/signup.
- For
Your Server Setup
, chooseStaging
for your test server andProduction
for your live installation. You should use separate Tagalys accounts (that have different API keys) to maintain different configuration and product catalogs. Staging accounts are not billed. - For platform, select
Magento 2.1+
.
In the next screen, you will see your API credentials as a JSON object. You will need this text to start the setup later. Click the Copy API credentials
link to copy the credentials to your clipboard.
Technical Notes
Testing on localhost
If you want to test on a local developer system that is not connected to the public Internet, you have to use a tunnel like ngrok and Magento should be configured for the new domain.
This is required because Tagalys syncs and updates statuses on your Magento installation using HTTP(s) requests.
Install via Composer
# base module for sync and category page merchandising
composer require tagalys/tagalys-magento2
php bin/magento module:enable Tagalys_Sync
# for front-end features like search
composer require tagalys/tagalys-magento2-frontend
php bin/magento module:enable Tagalys_Frontend
php bin/magento setup:upgrade
# depending on your Magento mode:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
Tagalys is installed using Composer. Run these commands commands from within your Magento root directory.
Depending on your Magento mode, you may have to run the setup:di:compile
and setup:static-content:deploy
commands - just follow the same steps you do to install other extensions.
Setup
Tagalys Menu in Magento Admin
Now that Tagalys has been installed, you are ready to begin the setup process. Go to Magento Admin > System > Tagalys > Configuration
.
API credentials
Paste your API credentails
Paste your API credentials (available in your Tagalys Dashboard after signing up) in the API credentials
field and click Save API credentials
. This will verify your Tagalys account and take you to the next step.
Parent Category Assignment
Automated missing parent category assignment during sync
Tagalys requires products to be assigned to all parent categories of the sub categories they are assigned to. This is necessary to position products precisely in parent categories in Magento.
For example, if a product is assigned to "Men > Tops > Hoodies & Sweatshirts", it should also be assigned to the parent categories "Men" and "Men > Tops":
Sync Settings
Settings for syncing products
In this step, choose the stores for which you want to enable Tagalys features. Each Store View is listed separately and will be saved as a separate bucket in Tagalys. This allows for features like multiple languages or catalogs and default currencies to work correctly and makes it possible to apply more relevant Analytics metrics.
We recommend that you leave Periodic full sync
on to make sure that any updates missed in the normal Sync process (due to, for example, network issues) are fixed automatically. The frequency for this is defined by your Cron file.
Detecting custom product updates
Tagalys automatically detects product updates made from the Magento Admin interface via the Catalog/Products, Catalog/Categories and Data Transfer/Import sections. If you are using third-party / custom code that doesn't dispatch the standard Magento hooks, there are two options to notify Tagalys of updates:
Trigger an event
$productDetailsObj = new \Magento\Framework\DataObject(array('product_ids' => array(1,2,3,4,5,6)));
$eventManager = $this->_objectManager->get('\Magento\Framework\Event\Manager');
$eventManager->dispatch('tagalys_record_updated_products', ['tgls_data' => $productDetailsObj]);
You can trigger the tagalys_record_updated_products
event like this to notify us of updates. This can be done in batches.
Enable updated_at tracking
If your code / module updates the updated_at
column of the catalog_product_entity
table, Tagalys can monitor it to detect changes. You can enable this from the Products Sync section of the Support & Troubleshooting tab under Magento Admin > Setup > Tagalys > Configuration
Image Settings
To reliably display product images in the Tagalys Dashboard and in any front-end features like Recommendations or Search, Tagalys generates and maintains its own product thumbnails in the media/tagalys
folder. Please adjust the image quality settings as required.
Once you've reviewed and chosen all the options, click Save & Continue to Sync
.
Cron
Crontab - Replace `path_to_magento_root` with the correct path
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:sync --max_categories 50
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:update_product_positions
0 2 * * * php -f /path_to_magento_root/bin/magento tagalys:run_maintenance
0 * * * * php -f /path_to_magento_root/bin/magento tagalys:update_popular_searches
For earlier versions, replace the respective commands with the following:
Plugin version <= 2.2.8
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:update_product_positions --max_categories 50
Plugin version <= 2.2.5
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:sync --max_products 500 --max_categories 50
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:update_product_positions --max_categories 50
For Tagalys to keep products and categories in sync, some background processes have to be setup. These have been defined as various Console Commands and should be triggered via your crontab
as per these recommended frequencies.
The user running these Commands should have write access to the media
folder.
Command | Recommended frequency | Description |
sync |
*/5 * * * * (every 5 minutes) |
Syncs products and categories enabled for merchandising by Tagalys. At every run, it writes a configurable number of products to a sync file and syncs a configurable number of newly added / selected categories to Tagalys. If there is nothing to update, it quits immediately. Earlier versions: --max_products - If your products have a large number of attributes and writing 500 products takes longer than 4 minutes, then reduce this number. |
update_product_positions |
*/5 * * * * (every 5 minutes) |
Updates product positions in categories (and cleares relevant caches) if required |
run_maintenance |
0 2 * * * (once a day at a low traffic time*) |
Triggers a full resync of products and retries syncing categories that have not been synced. * Should be scheduled after Catalog Price Rules are applied and reindexing is finished. |
update_popular_searches |
0 * * * * (every hour) |
Requires Tagalys_Frontend: Update pinned and popular search suggestions. |
Sync
Sync Status
After you save the sync settings, you will be taken to the Sync
tab where you can see the status of the syncing process.
If you have setup the background processes to run automatically, as per the previous step, the Feed Status
entry will automatically increase from 0% to 100% in batches every five minutes. After this the status will change to Waiting for Tagalys
during which time Tagalys processes your products. Once our servers finish processing, the status will automatically change to Finished
.
You will receive an email when this is done, so you don't have to wait till you see 100%. Just make sure that the percentage starts increasing. If it doesn't please check your cron settings or contact us.
Category Pages
Settings for Category Pages
Once setup is complete, you will see a new tab for Category Pages Magento Admin > System > Tagalys > Configuration
. If you do not see this, refresh the page. If Setup Complete
says No
, then check your sync status or contact us.
After choosing to enable the feature, read through the Technical Considerations
section carefully - there are options to configure Tagalys correctly for multi store setups with same / different products and with ascending / descending order of the Category-Product-Position field. If you have any questions, please contact us.
Once you choose some categories and click Save Listing Page Settings
, the background process will transfer the categories to the Tagalys Dashboard within 10 minutes and you can merchandise the pages by logging in to your Tagalys Dashboard. Any updates you make in the dashboard will transfer within 10 minutes to the front-end.
Setup checklist: This feature works by modifying Magento's Category-Product-Position field. To make sure it works as expected, please verify the following:
- Your category pages are configured to be sorted by the Position field.
- Your category pages sorting direction matches your choice in
Magento Admin > System > Tagalys > Configuration > Listing Pages
. This could be set in one of your blocks / view files, so please double-check. - If you have any custom / front-end caches enabled, you may have to listen to Tagalys events and clear cache as appropriate. Tagalys fires the event
tagalys_category_positions_updated
with the category IDs that were updated in the payload so you can do this. If you have any questions on this, please contact us.
$categoryIdObj = $observer->getData('tgls_data');
$categoryIds = $categoryIdObj->getCategoryIds();
Search
Settings for Search
Tagalys Search can be enabled from the Search tab in Magento Admin > System > Tagalys > Configuration
. The configuration options are:
- Search box selector: The jQuery selector of the search box on your front-end.
- Align suggestions to search box parent: If you want to align the search suggestions popup under a parent of the search box instead of the search box itself, specify the selector here.
Recommendations
Tagalys Recommendations are loaded by reading data attributes on HTML tags. You place a line of HTML code with with your requirements where you want the recommendation widget to appear and Tagalys will load this content asynchronously.
In all these examples, data-tagalys-widget-opts-per-page
should be a valid JSON string, where each key is a browser window size in pixels and value is number of visible product tiles at that size. You can use custom pixel sizes, but Tagalys internally sets the keys 300, 600, 900 and 1200 so you should also overwrite these if you want them to be different from the defaults mentioned below.
Similar Products
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="similar_products"
data-tagalys-widget-opts-product-id="product-id-for-similar-products"
data-tagalys-widget-opts-heading="More like this"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'>
</div>
Place this HTML where you want the recommendations widget to appear.
data-tagalys-widget-opts-product-id
should be dynamically set to the ID of the product
Recently Viewed
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="recently_viewed"
data-tagalys-widget-opts-heading="Recently Viewed"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="1">
</div>
Place this HTML where you want the recommendations widget to appear.
New Arrivals
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="new_arrivals"
data-tagalys-widget-opts-heading="New Arrivals"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="10">
</div>
Place this HTML where you want the recommendations widget to appear.
Top Discounts - By Percentage
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="top_discounts_percentage"
data-tagalys-widget-opts-heading="Top Discounts"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="10">
</div>
Place this HTML where you want the recommendations widget to appear.
Top Discounts - By Amount
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="top_discounts_amount"
data-tagalys-widget-opts-heading="Biggest Savings"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="10">
</div>
Place this HTML where you want the recommendations widget to appear.
Bestsellers
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="bestsellers"
data-tagalys-widget-opts-heading="Bestsellers"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="10"
data-tagalys-widget-opts-f='{}'>
</div>
Place this HTML where you want the recommendations widget to appear.
data-tagalys-widget-opts-f
can be dynamically set to a category or some other attribute to allow category specific widgets. For example: data-tagalys-widget-opts-f='{"__categories":["3"]}'
. It should be a valid JSON string following the same filter format as the search API uses (https://www.tagalys.com/docs/api/front-end/).
Most Viewed
<div id="tagalys-namespace" class="tagalys-namespace"
data-tagalys-widget="most_viewed"
data-tagalys-widget-opts-heading="Most Viewed"
data-tagalys-widget-opts-per-page='{"300":2,"600":3,"900":4,"1200":5}'
data-tagalys-widget-opts-hide-if-results-under="10"
data-tagalys-widget-opts-f='{}'>
</div>
Place this HTML where you want the recommendations widget to appear.
data-tagalys-widget-opts-f
can be dynamically set to a category or some other attribute to allow category specific widgets. For example: data-tagalys-widget-opts-f='{"__categories":["3"]}'
. It should be a valid JSON string following the same filter format as the search API uses (https://www.tagalys.com/docs/api/front-end/).
Analytics
Tagalys Analytics is a critical piece of the integration that makes it possible for us to optimize the sort order of products.
Custom JavaScript
If you have a custom front-end, then please use the following JS integration method. We have a separate JS file for each client account - please contact us for your link.
Track User
Tagalys.Analytics.trackUser(user_id);
The trackUser
helper allows you to associate each browsing session with a user account across devices. To perform this association, make the following call after the user logs in. Previous events in the session where the user was not logged in are automatically associated with this user account.
Track Event
Tagalys.Analytics.trackEvent(event_type, event_data);
Using the trackEvent
helper, you can send Tagalys details on product listing pages and actions. This helps us improve the relevance and sort orders of various Tagalys features, as well as provide you with detailed reports on our dashboard.
event_type
maybe one of product_action
or product_list
.
Product Action Events
product_action
events send Tagalys details on each product view, add to cart and buy.
The event_data
argument should be an object containing the following parameters:
Parameter | Required | Description | Type | Default value |
---|---|---|---|---|
sku |
Yes | The SKU of the target product | String | NA |
action |
Yes |
That action that is being performed on the product. One of:
|
String | NA |
quantity |
For add_to_cart and buy |
The number of items of the sku that are being added to cart or bought |
Integer | NA |
order_id |
For buy |
The unique ID of the order to which this buy is associated. If an order is placed for multiple items, send the buy event once for each sku with the associated quantity and the same order_id . |
String | NA |
Product List Events
product_list
events send Tagalys details about searches and product listing pages to enable attribution of product actions to specific features and queries. This helps with providing our popular searches API, sorting products better for individual searches / pages, and with advanced reporting that lets you figure out which pages and searches are working and what can be done to improve conversion.
The event_data
argument should be an object containing the following parameters:
Parameter | Required | Description | Type | Default value |
---|---|---|---|---|
pl_type |
Yes |
The type of the Tagalys feature being shown to the user. One of:
|
String | NA |
pl_details |
For search and mpage |
Details of the product list. Can contain the following common details
pl_type specific details
|
String | NA |
pl_total |
Yes | The total number of product results for the search / merchandised page | Integer | NA |
pl_page |
Yes | Events should be sent for each page number of the search or merchandised page being displayed. This parameter should mention the page number for the event being sent. | Integer | NA |
pl_sort |
If not using the default sort option | The sort option in the same format as listing page API requests | string | trending |
pl_products |
Yes | An array of SKUs of the products being displayed on the current page. | Array of integers | NA |
Direct API calls
If you are integrating into your mobile app or are unable to run our JS, you can call our Analytics API endpoints directly. This requires some planning and configuration as cookie management won't be automatic, so please contact us and we will guide you through the process.
Upgrade
# if you are using the frontend module
composer update tagalys/tagalys-magento2 tagalys/tagalys-magento2-frontend
# if you are only using the core module
composer update tagalys/tagalys-magento2
php bin/magento setup:upgrade
# depending on your Magento mode:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
You can run these commands to upgrade the Tagalys modules
Disable / Uninstall
Disable
# for front-end features like search
php bin/magento module:disable Tagalys_Frontend
# base module for sync and category page merchandising
php bin/magento module:disable Tagalys_Sync
php bin/magento setup:upgrade
# depending on your Magento mode:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
You can disable the Tagalys modules using the commands to the right.
Uninstall
# for front-end features like search
php bin/magento module:disable Tagalys_Frontend
composer remove tagalys/tagalys-magento2-frontend
# base module for sync and category page merchandising
php bin/magento module:disable Tagalys_Sync
composer remove tagalys/tagalys-magento2
php bin/magento setup:upgrade
# depending on your Magento mode:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
You can completely remove the Tagalys modules by using these commands.