NAV Navbar

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.

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.

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_products 500 --max_categories 50
*/5 * * * * php -f /path_to_magento_root/bin/magento tagalys:update_product_positions --max_categories 50
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 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.

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

$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:

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:
  • view
  • add_to_cart
  • buy
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:
  • search
  • mpage
String NA
pl_details For search and mpage Details of the product list. Can contain the following common details
  • f in the same format as in listing page API requests
and the following pl_type specific details
  • search - The following parameters should be in the same format sent to the search API.
    • q
    • qf
  • mpage
    • url - should match the URL component /m/*url* entered in the Tagalys dashboard for the merchandised page being displayed
    • title - used for displaying the page in Tagalys Dashboard reports
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.

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.