User Manual

Introduction

The Hawksearch service enables online retailers and publishers the ability to drive a rich, compelling user experience.  This experience drives visitors to the products and information that they are seeking. 

Hawksearch provides the ability to power the product listing pages for categories and brand pages on the site in addition to driving the search page on the site. This document will cover integration between an existing Magento 2 site and Hawksearch to drive:  Search Results and Landing Pages. 

The Magento 2 plugin allows to set up the data feeds for Hawksearch export. These feeds conform to the guidelines provided in the Hawksearch Data Feed Guidelines.

Requirements and Installation

Configuration

Before Hawksearch can be used with Magento, a Hawksearch account is needed. Having the account, it’s possible to configure the Magento extension to work properly.

Hawksearch Account

Contact you account manager at https://www.hawksearch.com/ and request for an account.

Magento Settings

To configure the Magento extension, you need the following Hawksearch credentials:

• Engine Name - this is the engine ID associated with your HawkSearch account.

• API Key - it is used by the module to connect to HawkSearch Rest API.

• Tracking Key - it is used to uniquely identify your account in the image pixel that is added to the order confirmation page on the site to track orders and generate appropriate reports in Hawk Search.

You can find these credentials on the Hawksearch Dashboard on the Admin > Account Info tab. Please follow Hawksearch URLs article to find the dashboard URL depending on the Hawksearch environment.

In the administration section of your Magento project, navigate to Stores > Configuration > HAWKSEARCH and fill in the form in the Connection Settings tab with all the information required.

Domains

Hawksearch has three environments available: Development, Staging/Test and a load-balanced Production. When performing integration, each engine can be accessed by using appropriate domains

Hawksearch URL Settings

• Hawksearch URL (Development): https://dev.hawksearch.net/

• Hawksearch URL (Staging): https://test.hawksearch.net/

• Hawksearch URL (Production): https://yourenginename.hawksearch.com/ Provided at time of launch. OR https://manage.hawksearch.com

Hawksearch Tracking URL Settings

• Hawksearch tracking URL (Development): https://tracking-dev.hawksearch.net/

• Hawksearch tracking URL (Staging): https://tracking-test.hawksearch.net/

• Hawksearch tracking URL (Production): https://tracking.hawksearch.com/

Hawksearch Recommendation URL Settings

• Hawksearch recommendation URL (Development): https://recs-dev.hawksearch.net/

• Hawksearch recommendation URL (Staging): https://recs-test.hawksearch.net/

• Hawksearch recommendation URL (Production): https://recs.hawksearch.com/

DataFeed Settings

General

Enable Logging

Enable/Disable logging. Logs are stored in var/log/hawksearch_datafeed.log if the option is enabled.

Version

The version number indicates the current installed version of the module.

Feed Settings

Schedule Feed Generation

This button allows you to generate the feed on demand. Once clicked it adds a Feeds generation cron job to the list of jobs to be processed at the nearest time. Next cron run depends on your Magento cron settings

Feed Stores

This is the list of the sites that is currently installed on your Magento instance. Select the site(s) you need to generate the feeds for. The separate file will be created for each store per each data type. See Data Feeds section for more details

Batch Limit

It is used while processing Feed generation to limit the size of data to be handled during each iteration.

Run Index when Complete

If enabled, it will trigger reindex on the HawkSerch side via API call as soon as Feeds are generated.

Enable Datafeed Cron Task

This setting controls if the cron is enabled to generate the feeds files on a scheduled basis 

Cron expression

This setting allows you to specify the cron expression to control the schedule for generating the feeds. Enter a standard 5 part cron expression. See https://en.wikipedia.org/wiki/Cron for more information about cron expressions. Note that the job cannot be scheduled to run more frequently than hourly.

Feed Cron Email

This setting allows you to specify an email address that an email should go out to, once the feed has been generated.

Fileds Mapping

There is an ability to create new Hawksearch fields from Magento configurations page and then map Hawksearch fields to Magento Attributes. The Hawksearch field is created with the setting “Do not store in index?“ set to Yes. Please fine tune the field settings in Hawksearch Workbench after it is created from Magento configuration page. You can find more details about Fields configuration in Wiki section in Confluence.

Adding new field

To add new field please scroll down the field list and find Add button at the very end of the list. Fill in “HawkSearch Label“ and “HawkSearch Code“ input boxes and optionally select Magento attribute. You need to Save Config to apply changes.

Pulling fields from Hawksearch

To pull all fields created in Hawksearch Workbench push the button “Pull Fields from HawkSerch“. All fields available in HawkSearch will be added on the page. You need to Save Config to apply changes.

Map Hawksearch fields to Magento attributes

If you want to have attribute data appeared in Datafeed this attribute should be mapped to any Hawksearch field. To map Magento attribute to Hawksearch field just select attribute code from the “Magento Attribute“ dropdown list. To remove mapping specify “--Please Select--“ option in “Magento Attribute“ dropdown list. You need to Save Config to apply changes.

There is a “Dedicated method“ option in “Magento Attribute“ dropdown list which is a reserved option for the following Hawksearch field codes:

• url_detail

• group_id

• is_on_sale

• metric_inventory

• category_id

• rating_summary

• reviews_count

Do not use “Dedicated method“ for other fields because it does nothing.

SFTP Settings

Enable SFTP settings if you want to send your feeds to SFTP server. Please make sure to specify SFTP connection setting correctly.

SFTP Folder is a relative path to your SFTP root directory. Files are sent to SFTP and stored in folders with names of store codes.

HawkProxy Settings

General

Enabled

The enabled field indicates if the module has been enabled for the current store view.

Enable Logging

Enable/Disable logging. Logs are stored in var/log/hawksearch_proxy.log if the option is enabled.

Version

The version number indicates the current installed version of the module.

Proxy Module Settings - ‘Store view’ Scope

Manage Categories

This setting indicates if categories are managed through Hawk Search. Set to “Yes” to allow the HawkSearch Proxy module to manage your Magento categories as landing pages.

Manage All Categories

This setting indicates if only specific categories are managed through HawkSearch. If set to “Yes”, HawkSearch landing pages will be created for all categories. If set to “No”, only categories with the “Hawksearch Landing Page” attribute set to “Yes” will be managed. To enable specific category to be manage by HawkSearch as landing page go to Catalog > Categories, pick a category and switch on “Hawksearch Landing Page“ category attribute

Enable HawkSearch Landing pages

This setting indicates whether HawkSearch custom page URLs can be handled by Magento.

HawkSearch Landing pages cache

Cache lifetime in seconds. Values below 300 are not recommended. Increase cache lifetime if Landing Pages API is requested too often.

Manage Search

This setting indicates whether the search is being powered through HawkSearch.

Meta Robots

Meta robots used on "/catalogsearch/result" page

Search Box HTML ID's

This setting should match the Id of the text box for search that is currently used on the header of your Magento site. If your pages use more than one search box, enter the HTML ID’s of each box you wish to attach to the Hawk Search Auto Suggest tool.

Add custom URL route for search

Enables custom route for search results page instead of default "/catalogsearch/result" route

Custom search route

Custom route used for search results page in case when “Add custom URL route for search“ is enabled

Use HawkSearch CSS

Indicates whether external hawksearch.css file should be loaded.

Autocomplete Div ID

The HTML id of the div that will contain autosuggest results

Query Params for the autosuggest call to HawkSearch

Result Type

In case when Tabs are enabled for your engine this setting defines the default tab displayed on search results page

Show Hawk type tabs

This setting determines whether tabbed content should be requested from HawkSearch and displayed on search results page

Show Hawk type labels

Display/Hide HawkSearch content type labels

Tabs on search results page

Type Labels

This setting configures content type label mapping. In case if label code is not specified in the setting Title, Background Color and Text Color will be generated

Synchronization Settings

If you are powering the category pages on your Magento site through HawkSearch, this button will launch a background process that will send basic category data (such as the URL and category ID) to the Hawksearch engine for each managed store view. Categories can be managed individually or globally. Note this does not include product data or product/category associations.

Enable cron sync

This setting allows you to enable the cron job to synchronize categories on a regular basis.

Schedule Synchronization

This button allows you to schedule categories synchronization on demand. Once clicked it adds a job to be processed by cron at the nearest time. Next cron run depends on your Magento cron settings

Cron expression

This setting allows you to specify the cron expression to control the schedule for running the synchronization task. Enter a standard 5 part cron expression. See https://en.wikipedia.org/wiki/Cron for more information about cron expressions. Note that the job cannot be scheduled to run more frequently than hourly.

Feed Cron Email

This setting allows you to specify an email address that an email should go out to, once Categories have been synchronized via the cron job.

Data Feeds

Structure

Files generated by the module are stored in the following folder pub/media/hawksearch/feeds/<store code>. If several stores are enabled for DataFeed module in 'Feed Stores' setting then feed files for each store will be placed in separate folder with unique <store code> as folder name. Magento HawkSearch connector extension supports the following feed files by default:

• items.txt

• attributes.txt

• content.txt

• hierarchy.txt

• timestamp.txt

For more details about Data feed files please refer to Standard Data Feed Requirements documentation

Generate Data Feeds

If Magento cron is configured correctly data feeds will be generated automatically. Please make sure that “Enable Datafeed Cron Task” is enabled. The cron job interval is configured according to “Cron expression“. There is an ability to schedule datafeed generation cron job on demand. Please refer to the Schedule Feed Generation button description.

For manual datafeed generation there is a CLI command specified:

bin/magento hawksearch:generate-feed