Manual

User Manual:

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

Download
Open PDF In Browser	View PDF

Doofinder for Magento 2
User Manual

Overview

Support

Pre-requisites

Installation

Installation via Magento Marketplace

Installation via Composer

Post-Installation

Module Conﬁguration

Conﬁguration Flow

Conﬁguration

Index Settings

Data Feed (legacy)

Troubleshooting

Overview
This module provides integration between Magento 2 and the Dooﬁnder search service to enhance
the overall search experience in your site.
You can integrate Dooﬁnder at two different levels in your page:

• Front-end only: Use this level of integration if you want to provide Dooﬁnder’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 ﬁle to feed Dooﬁnder with your products information.

• Complete: Use this level of integration if you want to provide Dooﬁnder’s search layer to your
users and / or you want Dooﬁnder to manage search results when the user submits the search
form. This level of integration indexes your data directly through Dooﬁnder’s REST API and
requires a Management API key1 to authenticate requests.

Support
• For technical support, get in touch from your Dooﬁnder Account or drop us an email at
support@dooﬁnder.com.

• If you’re a developer, you can ﬁle an issue or contribution request in our public code repository at
Github: https://github.com/dooﬁnder/dooﬁnder-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 Dooﬁnder module you need an active Dooﬁnder account. Dooﬁnder is a paid service
but you can try it 30 days for free and beneﬁt 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.dooﬁnder.com/signup
Plans and pricing are available at:
https://www.dooﬁnder.com/price

1 There are two kind of API keys: search-only keys and management keys. The latter allow to make changes to your search engines.

Installation
Dooﬁnder 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 ﬁlesystem. 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 oﬃcial Magento documentation:

• Make a Purchase
• Download the Software
• Install the Extension
Dooﬁnder module is a free purchase so you have to pay nothing to use it. The only cost for you is the
price of the Dooﬁnder 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:
$ cd /var/www/domains/shop.example.com
3. Execute:
$ composer require doofinder/doofinder-magento2
$ php bin/magento setup:upgrade
$ php bin/magento setup:di:compile

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.

Post-Installation
After installing the module, a new “Dooﬁnder” menu should have
been added to “Stores > Conﬁguration”.
There you will ﬁnd all the module conﬁguration options.

Module Configuration
Magento 2 can be conﬁgured at different levels; you can set up default values and be more speciﬁc
for each store view. This module makes use of that conﬁguration scheme but not all settings are
available at all levels, some will be at the default level and some others will be speciﬁc for each store
view. You must pay attention so the module is properly conﬁgured.
Before conﬁguring the module we should clarify some concepts:

• From Magento’s point of view, Dooﬁnder is a search engine. This concept clashes with Dooﬁnder’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 Dooﬁnder
instead.

• In Dooﬁnder’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 Dooﬁnder module, you
associate each store view with its own search engine by using different Hash ID values.
Module conﬁguration is structured in three submenus:
1. Conﬁguration: General conﬁguration of the module, like authentication, search engine
identiﬁcators or whether to use the Dooﬁnder Layer in the frontend or not.
2. Index Settings: Conﬁguration about the data being exported.
3. Data Feed (legacy): Settings to generate a data feed suitable for Dooﬁnder via Cron.
WARNING: legacy data feed settings are there as a fallback for those cases in which indexing via API
does not work properly.

Configuration Flow
These are the recommended steps to have Dooﬁnder up and running in the shortest time.

Sign Up
Create a free account by visiting https://www.dooﬁnder.com/signup in your web browser. Once
registered you will automatically enter the next step.
NOTICE: If you already have a Dooﬁnder account you can omit this step.

Search Engine Creation
If you already have a search engine in your account you can create a new one from the list of search
engines by clicking the New Search Engine button.
The search engine creation wizard consists of three steps:
Site Information
In this screen you have to enter:

• A name for your search engine to easily distinguish it from other search engines in your account.
• The homepage web address for your site.
Once available, click the Continue button.
Choose Platform
In the platform selector choose I'm going to use the API. Then choose a language to optimize your
search engine contents for searches done in that language.
Once done click the Continue button.
Dooﬁnder Layer Script
This step is optional at this stage of the installation process. If you want to conﬁgure the script now,
click the Yes, let’s go! button and follow the instructions of the wizard. Otherwise click the Skip this
step and ﬁnish button.
You will be able to conﬁgure the layer later by accessing your search engine and going to
Conﬁguration > Installation Scripts > Dooﬁnder Layer.
The HashID
The hashid is the unique identiﬁer of your search engine in Dooﬁnder. Copy the hashid of the created
search engine in a temporary text ﬁle, you will need it later.
5

Additional Search Engines
If you plan to use Dooﬁnder 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 Dooﬁnder 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 ﬁle, 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 conﬁgure the Dooﬁnder module.
It’s recommended to start setting proper values in the Conﬁguration section, ﬁrst for the Default
Conﬁg 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 conﬁgure the module before enabling Dooﬁnder as
Magento’s search engine.
Enable Dooﬁnder for Internal Search
The module replaces the default product catalog indexer by a custom indexer which sends product
data to the Dooﬁnder servers.
The recommended index mode is Update On Save. If your catalog index is conﬁgured to Update By
Schedule it will be automatically changed after the ﬁrst indexing. This way the index is updated
atomically when a change is done in your catalog instead of reindexing everything.

Configuration
Account
API Key
Global

If you plan to use Dooﬁnder 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 Dooﬁnder servers.
WARNING: Dooﬁnder offers two different types of API Keys
depending on the use. Remember to conﬁgure a
Management API Key so your Magento 2 can perform
indexing operations in Dooﬁnder.
WARNING: This setting must be conﬁgured BEFORE
selecting Dooﬁnder as Magento 2 search engine or enabling
the Atomic Updates feature.
If you don’t have an API Key:

• Log into your Dooﬁnder 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.

Search Engine
Use Dooﬁnder for Internal Search
Global

This is actually a shortcut to conﬁgure Dooﬁnder as the
Magento 2 search engine. If the link doesn’t work you only
have to go to Stores > Conﬁguration > Catalog > Catalog
and, under Catalog Search uncheck Use System Value for
Search Engine and choose Dooﬁnder instead.
WARNING: When you choose Dooﬁnder as Magento’s
search engine the catalog index will require a reindex.

Max Requests per Search

Due to the way Magento 2 works, Dooﬁnder 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

Enable this option to send changes to Dooﬁnder whenever
you save a product to the database so it’s updated as soon
as possible for search.

Global

NOTICE: You don’t need this setting if you’re using
Dooﬁnder 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 Dooﬁnder. It’s a
32-character long string. You can get it from the list of
search engines that appears when you access your
Dooﬁnder account.
WARNING: This setting must be conﬁgured BEFORE
selecting Dooﬁnder as Magento 2 search engine or
enabling the Atomic Updates feature.

Doofinder Layer
Dooﬁnder provides some Javascript layers to easily integrate search with any website. You can also
use those layers in your Magento 2 website and this section provides a place to paste the necessary
Javascript code to make them work.
To generate a layer for your website:
1. Log into your Dooﬁnder account.
2. Access the search engine you want to conﬁgure.
3. Go to Conﬁguration > Installation Scripts > Dooﬁnder Layer.
4. Press Conﬁgure Dooﬁnder Layer.
5. Follow the wizard steps.
WARNING: Magento 2 uses RequireJS to load Javascript dependencies. When creating your script
you must change the type of script. The recommended value to paste the script in this section is
RequireJS (HTML script tag, easy).

Enabled

Enable or disable the layer globally or per store view.

Script

This is the place where you have to paste the layer script.

Global, Store View

Store View

Index Settings
Attributes
When indexing products in Dooﬁnder, a default attribute set is used. You can customize the
attributes being exported globally or per store view.
NOTICE: Some virtual attributes are available. They’re preﬁxed by Dooﬁnder: string and are used to
perform calculations so proper values are exported. You can change them and use RAW attributes
but it’s not recommended.

Settings
Export Product Prices

Choose whether to export prices or not.

Price Export Mode

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
speciﬁc mode: With Taxes or Without Taxes.

Image Size

Export product images at the given width. Leave empty to
export at the original size.

Global, Store View

WARNING: Take into account that, if the images don’t exist
at the speciﬁed 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.

Data Feed (legacy)
This mode of indexing data in Dooﬁnder is going to disappear in the near future but it is still available
to provide a fallback for users that don’t want to use Dooﬁnder as Magento 2 search engine. We are
working to separate indexing and search as a new feature.

Cron Settings
Enabled

Choose whether to generate a data feed via Cron or not.

Feed Generation Start Time

The time at which the feed generation starts.

Step Delay

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

The maximum number of products added to the feed on
each iteration of the generation process (maximum
recommended value: 1000).

Security Phrase

You can set a secret word to protect your data feed. The
name of the generated ﬁle will contain the secret word so
nobody can guess it from the module defaults.

Global, Store View

Troubleshooting
Q:

Wrong URL for images in search results: the URL contains /pub after the site domain
name (1st solution).

Depending on how your Magento is set up, the cause may be different.
Indexes conﬁgured to be updated on save or dynamic feeds (deprecated)
It may be related to the web server conﬁguration. Magento is served from
MAGENTO_ROOT/pub but it will work ﬁne 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 conﬁguration, for
example in Apache you would replace:

ServerName www.homesweethome.gr
DocumentRoot

by:

ServerName www.homesweethome.gr
DocumentRoot /pub

Indexes conﬁgured 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
Dooﬁnder 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

Wrong URL for images in search results: the URL contains /pub after the site domain
name (2nd solution).

Dooﬁnder for Magento 2 only performs a full reindex the ﬁrst time the internal search is
enabled so, if you want to reindex everything yourself instead of changing the server
conﬁguration, 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

Right after installing the module, trying to save the module conﬁguration 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

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.

I have my indexes conﬁgured to be updated on save: when will the items be indexed?

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.

I can’t change the Update Products on Save conﬁguration in Index Settings

When Dooﬁnder is conﬁgured to be Magento’s search engine, atomic updates
conﬁguration is forced. When your indexed are conﬁgured to be updated on save, atomic
updates are enabled. When they are conﬁgured to be updated by schedule, atomic
updates are disabled.
If you don’t use Dooﬁnder as Magento’s search engine (for instance, you only use the
Javascript layers), you can conﬁgure atomic updates yourself.

Some products are being indexed with a wrong link, they point to the backoﬃce
instead of the correct frontend store view.

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.

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
Page Count                      : 16
Title                           : Manual
Producer                        : Mac OS X 10.13.6 Quartz PDFContext
Creator                         : Pages
Create Date                     : 2018:10:23 14:41:20Z
Modify Date                     : 2018:10:23 14:41:20Z

EXIF Metadata provided by EXIF.tools

Manual

Navigation menu

Versions of this User Manual:

Views

Navigation