Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 16

Doofinder for Magento 2
User Manual
Overview 2
Support 2
Pre-requisites 2
Installation 3
Installation via Magento Marketplace 3
Installation via Composer 3
Post-Installation 4
Module Configuration 4
Configuration Flow 5
Configuration 7
Index Settings 10
Data Feed (legacy) 11
Troubleshooting 12
Overview
This module provides integration between Magento 2 and the Doofinder search service to enhance
the overall search experience in your site.
You can integrate Doofinder at two different levels in your page:
•Front-end only: Use this level of integration if you want to provide Doofinder’s search layer to your
users but you want Magento to manage the search when the user submits the search form. This
level requires having your own data file to feed Doofinder with your products information.
•Complete: Use this level of integration if you want to provide Doofinder’s search layer to your
users and / or you want Doofinder to manage search results when the user submits the search
form. This level of integration indexes your data directly through Doofinder’s REST API and
requires a Management API key to authenticate requests.
1
Support
•For technical support, get in touch from your Doofinder Account or drop us an email at
support@doofinder.com.
•If you’re a developer, you can file an issue or contribution request in our public code repository at
Github: https://github.com/doofinder/doofinder-magento2.
Pre-requisites
•This module requires Magento 2.1 or greater, due to technical incompatibilities with Magento 2.0.
•Hardware and software requirements are the same as for Magento 2. Check Magento 2 technical
requirements for more information.
•This module is heavily based on Cron. Magento 2 requires Cron to properly work, so you must
have Cron up and running in your server for the module to work.
•To use the Doofinder module you need an active Doofinder account. Doofinder is a paid service
but you can try it 30 days for free and benefit from the freemium plan if you have a small store. If
you don’t have an account yet you can sign up at: !
!
https://www.doofinder.com/signup!
!
Plans and pricing are available at:!
!
https://www.doofinder.com/price
There are two kind of API keys: search-only keys and management keys. The latter allow to make changes to your search engines.
1
2
Installation
Doofinder can be installed via Component Manager as a free purchase done in Magento
Marketplace, or via Composer, the the-facto PHP package manager, if you feel at home working from
the command line directly in your server.
WARNING: Do not install this module via FTP or direct upload to your server’s filesystem. This
module has external software dependencies that Component Manager and Composer know how to
deal with. If you try to install the module by any other way than recommended you may experience
errors in your system.
Installation via Magento Marketplace
For up-to-date instructions refer to the official Magento documentation:
•Make a Purchase
•Download the Software
•Install the Extension
Doofinder module is a free purchase so you have to pay nothing to use it. The only cost for you is the
price of the Doofinder service once the trial period has ended.
Installation via Composer
1. Log into your Magento 2 server via SSH.
2. Go to Magento 2 installation path, for instance:
3. Execute:
WARNING: Some versions of the module, specially initial versions, may be in a beta stage. That
means they include features that may not work in some circumstances. To install them you will have
to specify the proper support stability tag, @beta in this case."
3
$ cd /var/www/domains/shop.example.com
$ composer require doofinder/doofinder-magento2!
$ php bin/magento setup:upgrade
$ php bin/magento setup:di:compile
Post-Installation
After installing the module, a new “Doofinder” menu should have
been added to “Stores > Configuration”.
There you will find all the module configuration options.
Module Configuration
Magento 2 can be configured at different levels; you can set up default values and be more specific
for each store view. This module makes use of that configuration scheme but not all settings are
available at all levels, some will be at the default level and some others will be specific for each store
view. You must pay attention so the module is properly configured.
Before configuring the module we should clarify some concepts:
•From Magento’s point of view, Doofinder is a search engine. This concept clashes with Doofinder’s
concept of search engine. In Magento 2 the search engine is the system you use for search and
you can use only one. MySQL is Magento’s default search engine but you can use Doofinder
instead.
•In Doofinder’s slang a search engine is a single container where you can put documents you want
to search. You can have multiple search engines in the same account, each with a different unique
ID which is called a Hash ID. When you set up search in Magento 2 with the Doofinder module, you
associate each store view with its own search engine by using different Hash ID values.
Module configuration is structured in three submenus:
1. Configuration: General configuration of the module, like authentication, search engine
identificators or whether to use the Doofinder Layer in the frontend or not.
2. Index Settings: Configuration about the data being exported.
3. Data Feed (legacy): Settings to generate a data feed suitable for Doofinder via Cron.
WARNING: legacy data feed settings are there as a fallback for those cases in which indexing via API
does not work properly.
4
5
Additional Search Engines
If you plan to use Doofinder completely integrated in your Magento you will need a different search
engine for each store view. Create as many search engines as store views are in your site and
annotate the hashid for all of them.
API Key
For your Magento to talk with Doofinder you need a Management API Key. You can create one by
clicking on the top-right menu and choosing API Keys.
In the API Keys list screen:
1. Click on the New API Key button. A dialog will appear.
2. Enter a name for your API Key.
3. Ensure you check I will use this API Key with the management API.
4. Click the Create API Key button.
5. Copy the API Key in a temporary text file, you will need it later.
NOTICE: In this case you only need one API Key.
Module Configuration
Once you have all hashids and the API Key you can configure the Doofinder module.
It’s recommended to start setting proper values in the Configuration section, first for the Default
Config scope (API Key and global options), then for each store view (hashid, layer script…).
Optionally, you can customize the information being exported in the Index Settings section.
NOTICE: It’s recommended to take some time to configure the module before enabling Doofinder as
Magento’s search engine.
Enable Doofinder for Internal Search
The module replaces the default product catalog indexer by a custom indexer which sends product
data to the Doofinder servers.
The recommended index mode is Update On Save. If your catalog index is configured to Update By
Schedule it will be automatically changed after the first indexing. This way the index is updated
atomically when a change is done in your catalog instead of reindexing everything.
6
API Key
Global
If you plan to use Doofinder as your Magento 2 search
engine instead of the default (MySQL), or you plan to use
only the Atomic Updates feature (see Index Settings later)
you will need an API Key to properly authenticate requests
done from your server against Doofinder servers.
WARNING: Doofinder offers two different types of API Keys
depending on the use. Remember to configure a
Management API Key so your Magento 2 can perform
indexing operations in Doofinder.
WARNING: This setting must be configured BEFORE
selecting Doofinder as Magento 2 search engine or enabling
the Atomic Updates feature.
If you don’t have an API Key:
•Log into your Doofinder account.
•In the top menu press your account’s email to open the
menu and go to API Keys.
•Press New API Key.
•Enter a name for your API Key so you know where you’re
using it and check I will use this API Key with the
management API.
•Press Create API Key.
7
Search Engine
Use Doofinder for Internal Search
Global
This is actually a shortcut to configure Doofinder as the
Magento 2 search engine. If the link doesn’t work you only
have to go to Stores > Configuration > Catalog > Catalog
and, under Catalog Search uncheck Use System Value for
Search Engine and choose Doofinder instead.
WARNING: When you choose Doofinder as Magento’s
search engine the catalog index will require a reindex.
Max Requests per Search
Global
Due to the way Magento 2 works, Doofinder must get all
results for each search. That can consume too much
queries so it’s limited to 5 requests per search by default.
Update Products on Save
Global
Enable this option to send changes to Doofinder whenever
you save a product to the database so it’s updated as soon
as possible for search.
NOTICE: You don’t need this setting if you’re using
Doofinder for internal search.
WARNING: This setting requires a valid Management API
Key.
Hash ID
Store View
This is the unique ID of a search engine in Doofinder. It’s a
32-character long string. You can get it from the list of
search engines that appears when you access your
Doofinder account.
WARNING: This setting must be configured BEFORE
selecting Doofinder as Magento 2 search engine or
enabling the Atomic Updates feature.
8
Enabled
Global, Store View
Enable or disable the layer globally or per store view.
Script
Store View
This is the place where you have to paste the layer script.
9
Export Product Prices
Global, Store View
Choose whether to export prices or not.
Price Export Mode
Global, Store View
Choose Auto (default) to export prices the same way as
they’re displayed in your store. If your store displays prices
with and without taxes included you will want to choose an
specific mode: With Taxes or Without Taxes.
Image Size
Global, Store View
Export product images at the given width. Leave empty to
export at the original size.
WARNING: Take into account that, if the images don’t exist
at the specified size, they will have to be generated, which
is a high time and resources consuming process. It is
recommended to leave it empty and use the default size of
the selected image attribute.
Export only categories present in
navigation menus
Global, Store View
The module exports only active categories. This option will
limit them to categories used for navigation purposes.
10
Enabled
Global, Store View
Choose whether to generate a data feed via Cron or not.
Feed Generation Start Time
Global, Store View
The time at which the feed generation starts.
Step Delay
Global, Store View
The interval (in minutes) between subsequent stages of
the feed generation process. It should not be smaller than
the frequency of execution of your Cron process.
Step Size
Global, Store View
The maximum number of products added to the feed on
each iteration of the generation process (maximum
recommended value: 1000).
Security Phrase
Global, Store View
You can set a secret word to protect your data feed. The
name of the generated file will contain the secret word so
nobody can guess it from the module defaults.
11
Troubleshooting
Q:
Wrong URL for images in search results: the URL contains /pub after the site domain
name (1st solution).
A:
Depending on how your Magento is set up, the cause may be different.
Indexes configured to be updated on save or dynamic feeds (deprecated)
It may be related to the web server configuration. Magento is served from
MAGENTO_ROOT/pub but it will work fine when served from MAGENTO_ROOT. Unfortunately,
when served not from pub directory, there is an issue with some publicly accesible paths
(images for instance).
So to correct the photos path issue, you might check your web server configuration, for
example in Apache you would replace:
<VirtualHost *:80>
ServerName www.homesweethome.gr
DocumentRoot <MAGENTO_ROOT>
</VirtualHost>
by:
<VirtualHost *:80>
ServerName www.homesweethome.gr
DocumentRoot <MAGENTO_ROOT>/pub
</VirtualHost>
Indexes configured to be updated by schedule or cron-based feeds
In case you are using a feed generated by cron or atomic updates with update by
schedule option, there may be an issue with Magento, not related strictly to the
Doofinder module. You may work around this issue by setting Base URL for User Media
Files to {{unsecure_base_url}} and Secure Base URL for User Media Files to
{{secure_base_url}}.
The issues that provoke this behavior:
https://github.com/magento/magento2/issues/8868!
https://github.com/magento/magento2/issues/9111
12
Q:
Wrong URL for images in search results: the URL contains /pub after the site domain
name (2nd solution).
A:
Doofinder for Magento 2 only performs a full reindex the first time the internal search is
enabled so, if you want to reindex everything yourself instead of changing the server
configuration, you can execute this command:
env \
"MAGE_DIRS[base][path]=/var/www/html" \
"MAGE_DIRS[pub][uri]=" \
"MAGE_DIRS[media][uri]=media" \
"MAGE_DIRS[static][uri]=static" \
"MAGE_DIRS[upload][uri]=media/upload" \
php bin/magento indexer:reindex catalogsearch_fulltext
!
You will have to replace the /var/www/html by your Magento root folder.
The issues that provoke this behavior:
https://github.com/magento/magento2/issues/8868!
https://github.com/magento/magento2/issues/9111!
Q:
Right after installing the module, trying to save the module configuration I get an
error:
Warning: array_merge(): Argument #1 is not an array in /var/www/html/ vendor/
doofinder/doofinder-magento2/Helper/Indexer.php on line 63
A:
Right after the installation of the module, Magento doesn't know about the default
settings, which can trigger this error. The solution usually is to clean the cache after
installing the module.
You can execute this in the CLI:
$ php bin/magento setup:upgrade
$ php bin/magento setup:di:compile
$ php bin/magento cache:flush
Or go to System > Cache Management and choose Flush Magento Cache.
Q:
I have my indexes configured to be updated on save: when will the items be indexed?
A:
They should be indexed after a while, assuming cron works properly - indexes are
revalidated in case of invalidation in cron no matter of index mode.
13
Q:
I can’t change the Update Products on Save configuration in Index Settings
A:
When Doofinder is configured to be Magento’s search engine, atomic updates
configuration is forced. When your indexed are configured to be updated on save, atomic
updates are enabled. When they are configured to be updated by schedule, atomic
updates are disabled.
If you don’t use Doofinder as Magento’s search engine (for instance, you only use the
Javascript layers), you can configure atomic updates yourself.
Q:
Some products are being indexed with a wrong link, they point to the backoffice
instead of the correct frontend store view.
A:
Unfortunately at the time of writing this, there’s a bug in Magento 2 which produces
wrong URLs in certain conditions:
https://github.com/magento/magento2/issues/4247
To prevent this, make sure every product has a URL key set.
14
15

Navigation menu