Docs

Integrating via Magento

Magento is an open-source CMS that gives eCommerce business owners an opportunity to expand their business operations in the digital e-commerce world.
In other words, Magento is a powerful system, flexible, scalable and easy to customize your eCommerce business.

The Unbxd Site Search extension packs all the essential product discovery features for your Magento-based website with little or no developer intervention.

This section helps you install the Unbxd extension, synchronize your product catalog, and integrate analytics.

Prerequisites

Before you can use the Unbxd Site Search extension:

  1. Create an Unbxd account and a site within our Console.
  2. Set up Magento on your server.
    We support versions 2.1.x, 2.2.x, and 2.3.0 to 2.3.3.
  3. Backup your web directory and store database.
    To backup using the Magento backup function, navigate to System > Tools > Backups.

Install your Extension

You can download and install the extension from the following locations:

Composer

To confirm if the Composer is installed, run the following commands within the SSH console of your server:

which composer  
composer -v  

Login to the SSH console of your server, navigate to the Magento root directory and run the following commands:

composer require unbxd/magento2-search  
php bin/magento module:enable Unbxd_ProductFeed  
php bin/magento module:enable Unbxd_Analytics  
php bin/magento module:enable Unbxd_Search  
php bin/magento setup:upgrade  

If production mode is enabled also run:

php bin/magento setup:di:compile  

To deploy content, run:

php bin/magento setup:static-content:deploy  
(use key –f if developer mode is enabled)

php bin/magento cache:flush  

You have successfully downloaded, installed, and enabled the Unbxd Magento extension.

To check your store current application mode, navigate to store root folder and run (as shown in the illustration below):

php bin/magento deploy:mode:show  

Direct Plugin File Upload

To install, you much copy the Unbxd extension files from the following Github locations to your Magento v2.x root directory:

UnbxdProductFeed
UnbxdAnalytics
UnbxdSearch Not available right now

Extract and copy related extension files to below path of you Magento 2 root directory. If the app/code/Unbxd folder is missing, follow the steps below to create it:

mkdir app/code/Unbxd/ProductFeed  
mkdir app/code/Unbxd/Analytics  

Login to the SSH console of your server, navigate to the Magento 2 root directory and run the following commands:

php bin/magento module:enable Unbxd_ProductFeed  
php bin/magento module:enable Unbxd_Analytics  
php bin/magento setup:upgrade  

If production mode is enabled also run:

php bin/magento setup:di:compile  


Finally run:
If production mode is enabled also run:

php bin/magento setup:static-content:deploy  
(use key –f if developer mode is enabled)

php bin/magento cache:flush  


You have successfully downloaded, installed, and enabled the Unbxd Magento extension.

To check your store current application mode, navigate to store root folder and run (as shown in the illustration below):

php bin/magento deploy:mode:show  

Configuration

This section walks you through the process of configuring product indexing, authentication and synchronizing your feed.

Enable Product Indexing

In order to provide fast and relevant search, our extension restructures your data through a process known as indexing. Indexing is how Magento transforms data such as products and other data, to improve the performance of your storefront. As data changes, the transformed data must be updated or reindexed.

Indexing Settings within Catalog allows you to specify what data should be indexed and when.

For instance, when you modify a product or category page, instead of uploading the entire catalog to the production index, a copy of the changes is created at the extension server which helps in sending only data that has been modified to the Unbxd server asynchronously every time the feed upload is triggered (manually or automatically or through Command Line Interface (CLI)).

To enable indexing:

  1. On the Unbxd tab, click Catalog.
  2. Within Indexing Settings, select Yes for Enable Indexing Queue. If you select No, your product catalog is not indexed automatically.
  3. Click Save Config.

If Enable Indexing Queue is set to 'Yes', then all indexing operations related to the products in the catalog will be added to the Indexing Queue and done asynchronously by a scheduled cron job.

If Enable Indexing Queue is set to 'No', then all indexing operations related to the products in the catalog will be done immediately after the original product information is modified.

You have successfully enabled Indexing for your product catalog and the extension is now set to automatically keep all your data updated to provide the best search experience for your shoppers.

To view the products added to the indexing queue, you can use the Indexing Queue View.

We recommend you set Enable Indexing Queue to Yes when you are in Production Mode or if you have a product catalog that has more than 2 million products or is larger than 2GB.

General Settings

This section allows you to indicate the product types available in your catalog while excluding specific categories of products while synchronizing.

The Unbxd extension supports three types of products:

  • Simple Product: A simple product is a physical item with a single SKU. When converted to the Unbxd format, a simple product is considered as a Normal Feed.
  • Configurable Product: A configurable product is a parent product of multiple simple products. When converted to the Unbxd format, configurable products are considered as variants.
  • Grouped Product:A grouped product presents multiple, standalone products as a group. You can offer variations of a single product, or group them for a promotion. The products can be purchased separately or as a group. Like configurable products, when converted to the Unbxd format, grouped products are considered as variants.

    Our extension allows you to exclude four types of products:

  • Disabled: Indicates products that have been disabled from being listed in the Product Listing Page.
  • Out Of Stock: Indicates products where the inventory count is 0.
  • Not Visible Individually: Indicates products that are available only as a bundle.
  • Without Images: Indicates products where there isn’t an available image.

    To upload product types:

    1. On the Unbxd tab, click Catalog.
    2. In General Settings, within Available Product Types, select All Available Types to select all available product types within your catalog. Click the drop-down box to select from one of the product types.
    3. Click Save Config.

    You have successfully mapped your catalog’s product types

    Authentication

    Once installed, you need to authenticate your Unbxd extension using your Unbxd account keys (also known as Authentication Keys).

    You’ll find your authentication keys within the Welcome mail you receive when signing up with us. Alternatively, you’ll also find these keys in Manage > Configure Site > Keys within your Unbxd Console.

    There are three types of account keys:

    • Site Key: The unique identifier of a Site. Each site added on your dashboard will have a unique Site key.
    • API Key: The unique identifier of the API calls made from an account. Unbxd provides only one API Key per account.
    • Secret Key: An additional securely generated key used in important request calls such as Product Feed upload. Secret Key is not exposed in URL. Unbxd provides one Secret Key per account.

    To authenticate:

    1. On the Unbxd tab, click Setup.
    2. In General Settings, type in the values for:
      • Site Key
      • Secret Key
      • API Key
    3. Click Save Config.

    You have successfully saved your Unbxd account keys within your Magento extension.

    The next step would be to map your catalog with us.

    Catalog Sync

    All Unbxd algorithms are based on product-related information within the product catalog.
    When you send your catalog to us, we convert it to the Unbxd format, store and index it on our servers. This is called Product Feed. Synchronizing your feed will allow your Unbxd extension to retrieve your catalog information stored within the Magento database. To know more, refer to Product Feed.

    Your Unbxd extension will access your catalog as a JSON file and sync it to the Unbxd server in three ways:

    • Automatic Synchronization
    • Manual Synchronization
    • Command Line Interface (CLI)

    Automatic Synchronization

    Our extension will send every update and deletion on products or categories to our servers to keep all data up-to-date by setting cron jobs.

    The indexers’ behavior can be changed to prevent these update calls, and only update the data through manual reindexing. For this to work, the cron mode should be set to ‘Manually’.

    To schedule automated synchronization:

    1. On the Unbxd tab, click Catalog.
    2. To schedule automated indexing, within Cron Settings, select Yes for Enable Cron.
    3. In Cron Type dropdown box, select the required type:
      • Manually: When this is chosen, you can indicate the frequency of the cron job. When the Cron Type is set to Manually indicate the frequency of indexing within Cron Schedule.
      • By Template: When this is chosen, you can indicate Start Time and the Frequency to ‘Daily’, ‘Weekly’, or ‘Monthly’.
    4. In the Cron Schedule text field, type in the required frequency. Click the icon for examples.
    5. To test the schedule, click the Check button for Check If Cron Is Running. This lists the status and a log of the last 10 cron jobs.
    6. Click Save Config.

    You have successfully scheduled automated synchronization for your product catalog.

    Manual Catalog Synchronization

    You can also set to manually index your product catalog using manual synchronization options.

    Before you set up manual indexing, ensure the related cron job is configured.

    To set up manual synchronization:

    1. On the Unbxd tab, click Catalog.
    2. In General Settings, within Indexing Settings, select Yes for Enable Indexing Queue. In Manual Synchronization, select Yes for Enable Manual Synchronization.
    3. To perform a full feed upload, click the Synchronize button for Full Product Catalog Synchronization. To perform a delta upload, click the Synchronize button for Incremental Product Catalog Synchronization.
    4. Click Save Config.

    You have successfully set up Manual synchronization for your product catalog.

    To check the status of the feed upload, click Unbxd > Feed View.

    To avoid causing unnecessary resource delays and timeout errors, the synchronization operation will be added to the Indexing Queue even when Enable Indexing Queue is set to No.

    Command Line Interface

    You can update your product catalog from within the Magento directory.
    Within your Magento root directory, run:

    php bin/magento  
    
    Add the –h key to see the features and configuration of each command. More about Magento CLI commands: Get started with command-line configuration

    Full Product Catalog Synchronization

    This command allows you to perform a full product catalog synchronization. If the specific store ID is not specified, synchronization will occur for default store ID.

    To schedule a full catalog synchronization, run:

    php bin/magento unbxd:product-feed:full  
    

    Incremental Product Catalog Synchronization

    This command allows you to perform an incremental product catalog synchronization. If the specific store ID is not specified, synchronization will occur for default store ID.
    To schedule an incremental catalog synchronization, run:

    php bin/magento unbxd:product-feed:incremental  
    

    Check Feed Upload Size

    This command allows you to check the total size of the feed being uploaded for a specific store. If the specific store ID is not specified – a default store ID will be used.
    To check the file size of the feed, run:

    php bin/magento unbxd:product-feed:upload-size  
    
    The appearance of the response result may differ based on the version of Magento 2.x you use.

    Check Feed Upload Status

    This command allows you to check the upload status for the specific upload ID. If the upload ID is not specified – the last upload ID will be used.

    If you want to check status for full upload - use key –t1 or you can just omit this parameter.

    If you want to check the status for incremental upload - use key –t2 (required).

    php bin/magento unbxd:product-feed:upload-status  
    
    The appearance of the response result may differ based on the version of Magento 2.x you use.

    Catalog Synchronization Information

    When synchronizing a catalog, the Last Synchronization information may display four status codes:

  • Running: Indicates the catalog is running and has been submitted to Unbxd.
  • Indexing: Indicates the catalog is being indexed.
  • Complete: Indicates the catalog has successfully uploaded.
  • Error: Indicates the catalog synchronization failed.

    By default, Magento doesn’t synchronize the catalog automatically.

    Feed View

    The Feed View (Unbxd > Feed View) screen lists all your product catalogs and its upload status. Primarily it would tell you if the upload was full or incremental and if it successfully completed or not.

    To view the description of the labels in the screenshot above, refer to the table below.




    LabelDescription
    IDIndicates the unique identifier of the record
    Store ViewIndicates the store related to upload operation
    CreatedIndicates the calendar date and time the specific upload queue entry was created
    FinishedIndicates the upload end time of the catalog
    Execution Time(s)Indicates the duration of time (in seconds) the upload took to complete
    Affected Entities Indicates the total number of products affected by the feed upload
    Number of Entities Indicates the total number of entities in the upload process
    Operation TypeIndicates the status of a feed upload operation
    Status
  • Running: Indicates the catalog is running and has been submitted to Unbxd
  • Indexing: Indicates the catalog is being indexed
  • Complete: Indicates the catalog has successfully uploaded
  • Additional InformationIndicates the information related to reindexing
    ActionIndicates the action available for the specific entity
    Actions
  • View Details: Allows you to view the information of the entity. The General Information also allows you to ‘delete’ the upload
  • Delete: Allows you to delete the reindexing activity
    You cannot delete an entity when the upload is ‘Running’


  • Clear Feed View Allows you clear the Feed View queue
    View LogAllows you to view the log file entries for the entire cron job. You can also download the log file, refresh the log entries, and clear the log
    ActionsAllows you to delete feed upload for multiple entities
    FiltersAllows you to create filters to refine the Feed View table
    Default ViewAllows you to reset the Feed View table to its original settings
    ColumnsAllows you to select the columns you want displayed in the Feed View table
    Log ViewerProvides some operations with log file:
  • the log file can be flushed
  • the log content can be refreshed to show actual information
  • the log file can be downloaded
    The viewer displays the current log file location and file size (in KB)
  • Indexing Queue View

    To view the products added to indexing queue, before the cron job or manual synchronization is triggered, use the Indexing Queue View within the Unbxd tab.

    For example, every time a product is added/deleted/modified, a row will be created to record the change within the Indexing Queue.

    The labels in the screenshot above are explained in the table below:




    LabelsDescription
    IDIndicates the unique identifier of the record
    Store ViewIndicates the store related to reindex operation
    CreatedIndicates the calendar date and time the specific Indexing queue entry was created
    StartedIndicates the reindexing start time of the catalog
    FinishedIndicates the reindexing end time of the catalog
    StatusIndicates the status of a catalog’s reindex operation
    Status
  • Pending (Default): Indicates the reindex entry was just created and is waiting to be processed
  • Running: Indicates the catalog is currently being processed
  • Complete: Indicates the catalog has successfully finished reindexing
  • Error: Indicates the catalog has finished reindexing with errors
  • Hold: Indicates the catalog’s reindexing is paused. This may also mean the reindexing may not resume
    You can choose to pause a pending scheduled reindex when you don’t want to reindex data for some reason


  • Execution Time(s)Indicates the duration of time (in seconds) the reindexing took to complete
    Affected EntitiesIndicates the total number of products affected by reindexing
    Number of EntitiesIndicates the total number of entities in the reindex process
    Action TypeIndicates the type of reindexing action for the entities.
    Action types:
  • Row reindex: Allows you to reindex only one product
  • List reindex: Allows you to reindex a list of products
  • Full reindex: Allows you to reindex an entire catalog
  • Additional InformationIndicates the information related to reindexing
    Actions:Indicates actions you can perform on required cron job
    Actions available
  • View Details: Redirects to separate UI layout with queue item details
  • Hold: Sets the reindex operation to 'Hold'
  • Unhold: Releases reindex operation from 'Hold' status (switch to 'Pending' status)
  • Delete: Deletes reindex operation item from queue
  • Log ViewerProvides some operations with log file:
  • the log file can be flushed
  • the log content can be refreshed to show actual information
  • the log file can be downloaded
    The viewer displays the current log file location and file size (in KB)
  • Integrate Analytics

    Unbxd search tracks user behavior anonymously and uses machine learning algorithms to power personalized search results that are relevant and accurate. Analytics is built into your Unbxd Magento extension.

    The extension helps us track and analyze user events, like product clicks, search queries, add to cart clicks, and successful orders. We then use this information to build a user profile that shows the user’s affinity towards a certain category, brand or price. This enables us to help you provide search results that are intuitive and relevant.

    General Settings

    You can enable or disable analytics within General Settings.

    When Enabled is set to 'Yes', the extension will track specific user events, like:

  • Product Page View
  • Add to Cart
  • Remove from Cart
  • Order Creation

    Upgrade

    Depending on the installation method you choose, you can upgrade the Unbxd extension in two ways:

  • Manual Upgrade: If the extensions files are located within app/code/Unbxd, then the extensions were installed manually and you need to upgrade the extensions files manually. You will need to log into your Github account.
  • Composer: If the extension files are located within vendor/unbxd/, then the extension was installed using the Composer and you need to use the Composer to upgrade.

    Create a backup (via System > Tools > Backup) before you upgrade.

    Manual Upgrade

    If you have installed the Unbxd extension via a direct file upload, you can upgrade manually:
    To upgrade manually:

    1. Download and install the latest version of the extension from the following Github locations:
      • UnbxdProductFeed
      • UnbxdAnalytics
      • UnbxdSearch
    2. To download a related extension, click Clone or download > Download Zip. For more information on how you can download and install via a direct link, refer to Installation via direct file upload.
    3. Extract and replace all existing files. Login to the Secure Shell (SSH) console of your server, navigate to the Magento 2 root directory and run:
      php bin/magento cache:flush
      php bin/magento setup:upgrade
    4. If production mode is enabled, run:
      php bin/magento setup:di:compile
    5. To deploy content, run:
      php bin/magento setup:static-content:deploy (use key –f if developer mode is enabled)
      php bin/magento cache:flush

    You have successfully upgraded using the direct file.

    Upgrade via Composer

    IMPORTANT: To perform this operation, in some cases, you need to setup your Magento 2 access keys. These would available in auth.json file located in your Magento 2 root directory. By default, Magento 2 provides auth.json.sample file located in root directory.

    TIP: To know more about authentication keys: HTTP basic authentication, Get your authentication keys

    If you have installed the Unbxd extension via the Composer, you can upgrade via the Composer as well.
    To upgrade via the Composer:

    1. Login to the SSH console of your server, navigate to the Magento 2 root directory and run:
      composer update unbxd/*
      php bin/magento setup:upgrade
    2. If production mode is enabled, run:
      php bin/magento setup:di:compile
    3. To deploy content, run:
      php bin/magento setup:static-content:deploy (use key –f if developer mode is enabled)
      php bin/magento cache:flush

    You have successfully upgrade via the Composer.

    Uninstall

    Depending on the installation method you choose, you can uninstall the Unbxd extension in two ways:

  • Manual Uninstall: If the extensions files are located within app/code/Unbxd, then the extensions were installed manually and you need to uninstall the extensions files manually. You will need to log into your Github account.
  • Composer: If the extension files are located within vendor/unbxd/, then the extension was installed using the Composer and you need to use the Composer to uninstall.

    Create a backup (via System > Tools > Backup) before you uninstall.

    Manual Uninstall

    If you have installed the Unbxd extension via a direct file upload, you can uninstall manually:
    To uninstall manually:

    1. Login to the SSH console of your server, navigate to the Magento 2 root directory and check the list of related extensions including their enable/disable status:
      php bin/magento module:status Unbxd_Search
      php bin/magento module:status Unbxd_Analytics
      php bin/magento module:status Unbxd_ProductFeed
    2. To disable the extensions, run:
      php bin/magento module:disable Unbxd_Search
      php bin/magento module:disable Unbxd_Analytics
      php bin/magento module:disable Unbxd_ProductFeed
      You can also disable extensions via Module Manager (System > Web Setup Wizard > Module Manager).
    3. To remove files related to the extensions, run the following commands from Magento 2 instance root directory:
      rm -rf app/code/Unbxd (for remove main extensions files)
      rm -rf val/log/unbxd (for remove log files)
    4. Login to the MySQL server where the Magento 2 instance database is located.
    5. To remove all tables related to the extensions, run:
      SET FOREIGNKEYCHECKS=0;
      DROP TABLE IF EXISTS unbxdproductfeedindexingqueue;
      DROP TABLE IF EXISTS unbxd
      productfeedfeedview;
      SET FOREIGNKEYCHECKS=1;
    6. To remove module configuration settings from coreconfigdata table, run:
      DELETE FROM coreconfigdata WHERE path LIKE '%unbxd%';
    7. To remove module from setupmodule table, run:
      DELETE FROM setup
      module WHERE module LIKE 'Unbxd_%’.
    8. Run php bin/magento setup:upgrade from Magento 2 instance root directory:
    9. If production mode is enabled, runphp bin/magento setup:di:compile.
    10. To deploy content, run:
      php bin/magento setup:static-content:deploy(use key –f if developer mode is enabled)
      php bin/magento cache:flush

    You have successfully uninstalled the Unbxd extension.

    Uninstall via Composer

    IMPORTANT: To perform this operation, in some cases, you need to setup your Magento 2 access keys. These would be available in auth.json file located in your Magento 2 root directory. By default, Magento 2 provides auth.json.sample file located in the root directory.

    TIP: To know more about authentication keys: HTTP basic authentication, Get your authentication keys

    If you have installed the Unbxd extension via the Composer, you can uninstall via the Composer as well.

    To uninstall via the Composer:

    1. Login to the SSH console of your server, navigate to the Magento 2 root directory and check the list of related extensions including their enable/disable status:
      php bin/magento module:status Unbxd_Search
      php bin/magento module:status Unbxd_Analytics
      php bin/magento module:status Unbxd_ProductFeed
    2. To disable the extensions, run:
      php bin/magento module:disable Unbxd_Search
      php bin/magento module:disable Unbxd_Analytics
      php bin/magento module:disable Unbxd_ProductFeed
      You can also disable extensions via Module Manager (System > Web Setup Wizard > Module Manager).
    3. To remove files related to the extensions, run the following commands from Magento 2 instance root directory:
      php bin/magento module:uninstall -r Unbxd_Search
      php bin/magento module:uninstall -r Unbxd_Analytics
      php bin/magento module:uninstall -r Unbxd_ProductFeed
      The -r flag removes extension data.
    4. To remove extensions log files, run rm -rf var/log/unbxd.
    5. To remove modules from composer and clean up the database and code, run the following commands after modules have been successfully uninstalled:
      composer remove unbxd/*
      php bin/magento setup:upgrade.
    6. If production mode is enabled, run php bin/magento setup:di:compile.
    7. To deploy, run:
      php bin/magento setup:static-content:deploy (use key –f if developer mode is enabled)
      php bin/magento cache:flush.

    You have successfully uninstalled the Unbxd extension via the Composer.