Integration Steps


Prefixbox solutions are easy to integrate. Each piece - Autocomplete, Related Searches, and the Search Engine - need to be implemented separately. We often onboard in phases so the process is quick and easy; customers usually integrate Autocomplete first (along with Search Analytics), Related Searches second, and the Search Engine third. You can take a look at the process below, but don’t worry, we have a dedicated team who is here to help you through the onboarding process.

Autocomplete

  • Export the top 5,000 keywords of your internal/site search keyword list from Google Analytics and save it as an Excel sheet. Send this to the Prefixbox team via e-mail (support@prefixbox.com) This will be the initial keyword suggestion list - another export will not be required because Prefixbox can refresh this list based on user behavior.

  • To display products in the search box, we need a product feed/product list that contains all products for sale on your site. Please share this via an HTTP or HTTPS URL (public or password protected). We refresh this list by downloading it from this URL multiple times per day. The recommended format is the following: simple CSV (or TSV) file. The file should contain the following columns in any order:

    • Product name: e.g.: Table Lamp

    • Product page URL: It is important that the feed contains the product URLs in the same format as they appear on your site.

    • Product image / thumbnail URL: Recommended size is 100 x 100px.

    • Gross Price:the products current price (with discount, if there is one).

    • [Optional] Old Price: The previous price of the product. This is required only if there is a difference between the old and current price.

    • [Optional] Discount: The amount discounted from the old price; it can be displayed as a simple string; e.g.: „-30 %”. This is required only if there is a difference between the old and current price.

    • [Optional] Item number/identifier: The item number or internal ID of the product.

  • [Prefixbox team] Based on the above data, we will setup your search box in the Prefixbox portal and you can test it. After this, a 1 line JavaScript will be shared with you. Once you add this script to your site, the autocomplete suggestions will begin working immediately. We set up separate mobile and desktop versions, so it will work everywhere your customers want to access it.

  • Analytics In order to activate the detailed search analytics, there are a few additional JavaScript calls that you need to implement on your site. Details are described here: Prefixbox Page Events. Based on the detailed search analytics, Prefixbox can compute the correct order of the suggestions.

  • [Prefixbox team] After the integration, we will test everything to ensure it’s working.

  • Go live! We will explain the metrics tracked in the Search Analytics dashboard.

  • Estimated effort:
    6 hours or fewer

  • Requirements:
    Front-end developer

  • Insert 4 empty HTML elements with unique identifiers and we will configure the Related Search boxes for you.

    • 2 for search engine result pages (keyword box for above and below the results).

    • 1 for keywords and 1 for products on “0-results” search pages.

  • Update the plugin.js insert line.

  • [Prefixbox team] We will configure the CSS in the Prefixbox portal.

  • [Prefixbox team] We will test everything to ensure it’s working.

  • Go live!

  • Estimated effort:
    1 hour

  • Requirements:
    Front-end developer

Search Engine

  • Create JSON feed and please share this via an HTTP or HTTPS URL (public or password protected). We refresh this list by downloading it from this URL multiple times per day. You can find more information about the feed format here: JSON Feed Format

  • [Prefixbox team] We will configure the Search Engine from your JSON product feed.

  • Integrate the API call

    • You can call your configured search engine via HTTP GET:
      https://serving5.prefixbox.com/?btr=BoxTracker &pattern=Term &format=json&page=PageNum &top=TopNum &filter=Filters &orderby=OrderField OrderDir

    • Note: please make the API domain name (serving5.prefixbox.com) configurable in case this changes in the future. serving5.prefixbox.com has 2 DC hosting configured for increased availability.

    • The request must contain at least the following two query string parameters:

      • btr=BoxTracker – the tracker of your search engine, you can get it from Prefixbox Portal, or from the Customer Success Manager.

      • pattern=Term – the pattern / search term the user is searching for.

    • The following query string parameters are optional:

      • TopNum – the number of the search results to be displayed on one page (SERP), default is specified by the search settings on the Prefixbox Portal.

      • PageNum – the number of the result page to be shown.

      • Filters – the filter conditions by which the search results will be filtered (in addition to the search term).

      • OrderField – the name of the field by which the search results will be ordered. The default order of the search results is by relevance specified by the automatically calculated Score field.

      • OrderDir – the direction of the ordering. Applicable values are asc and desc. The default order direction is ascending.

    • Specify what “sorting” options you would like on the UX. For example: price, relevance, product name, etc.

    • Filters

      • You can specify filters in the Search API request for all your searchable and facetable product attributes. The format of the filters follow the OData filter URI conventions. (OData Uri Conventions Paragraph 4.5 Filter System Query Option)

      • For example:

        • “(Price gt 2000) and (Price lt 50000)”.

        • “(Category eq ‘Laptop’) and (Brand eq ‘ASUS’)”

      • Logical operators for filtering:

        • lt – lower than

        • gt – greater than

        • le – lower or equal

        • ge – greater or equal

        • eq – equals (only for textual type fields)

      • You can combine any number of filters by using the and / or filter operators. You can negate any filter condition by using the not operator.

      • When combining filters please always make sure of the proper precedence by using brackets.

    • Search Response format

      • After calling our search API, the response returns in JSON format.

      • The response contains the following main parts:

        • Documents – the search results themselves and additional info.
          Object. Wrapper object for the collection of the search results.

          • Count (Documents.Count) – Number. The number of results returned by this search.

          • Results (Documents.Results) – Array of Result. The products / results returned by this search.

            • Result (Documents.Results[i]) – Object. Wrapper object for a single search result.

              • Score (Documents.Results[i].Score) – Number. The relevance (matching score) of the search result represented by a number.

              • Document (Documents.Results[i].Document) – Object. A single search result (a product).

        • Note: there is a difference between the Id and the Identifier fields of the Document. Id is used by Prefixbox internally, and Identifier is the product identifier received from the feed.

        • Filters – There are two types of facet filters. Please look for JSON example at the end of this document.

          • RangeFilters – this will contain facets for numerical values, like Price. RangeFilters contain a name field, this is the name of your field, and the minimum and maximum value of the filter.

            RangeFilters (Filters.RangeFilters) – Array of RangeFilter objects. The range filters applicable for the returned search results.

            • RangeFilter (Filters.RangeFilters[i]) – Object. A single range filter.

              • RangeFilter.Name (Filters.RangeFilters[i].Name) – String. The name of the range filter. Matches the name of the column on which the filter can be applied.

              • RangeFilter.DisplayName (Filters.RangeFilters[i]. DisplayName) – String. A friendly name for the filter that can be displayed on the UI.

              • RangeFilter.Min (Filters.RangeFilters[i]. Min) – Number. The lower value of the filter.

              • RangeFilter.Max (Filters.RangeFilters[i]. Max) – Number. The upper value of the filter.

          • ValueFilters – this will contain facets for textual facets, like Brand or Category. ValueFilters contain a name field, this is the name of your field, the number of facets returned, and the values of the facets. Every facet value contains the name and the number of products in that facet.

            ValueFilters (Filters. ValueFilters) – Array of ValueFilters objects. The value filters applicable for the returned search results.

            • ValueFilter (Filters.ValueFilters[i]) – Object. A single value filter.

              • ValueFilter.Name (Filters.ValueFilters[i].Name) – String. The name of the value filter. Matches the name of the column on which the filter can be applied.

              • ValueFilter.DisplayName (Filters.ValueFilters[i].DisplayName) – String. A friendly name for the filter that can be displayed on the UI.

              • ValueFilter.Values (Filters.ValueFilters[i].Values) – Array of ValueFilterValues.

                • ValueFilterValue (Filters.ValueFilters[i].Values[j]) – Object. Contains a value by which the results can be filtered and the number of the current search results with the specified value.

                  • ValueFilterValue.Count (Filters.ValueFilters[i].Values[j].Count) – Number. The number of the current search results with the specified value.

                  • ValueFilterValue.Value (Filters.ValueFilters[i].Values[j].Value) – String. A value by which the results can be filtered.

        • Count – Number. The total number of results that match this search. (It is identical to the Documents.Count).

        • PageSize – Number. The current page size in the request. Matches the top query string parameter specified in the search request, or the page size setting of the search box if the parameters is missing.

      • Recommendation for using filters.
        When the user searches for the first time (no filters specified) the API response contains the filters list. Use this for rendering the filters on the UX. When the user selects a Filter, the API request/response changes the filters. You have two options:

        • [Recommended] Keep the original filters of the first response. Note: this is how it is implemented on the Prefixbox Portal Search Demo Tool.

        • Alternatively you can render the new filters returned by the current API response.

      • Recommendation for Search API response field selection.
        You can get all the properties of the products, as specified in the JSON example above. Typically you just want the Search API to return the list of Product Identifiers, and you can SELECT the rest of the product properties from your own SQL product database for these. It ensures that you have access to the latest product data, in case the Prefixbox Search Index might be out of sync. E.g.: there was a price or discount update for a few products.

  • [Prefixbox team] After the integration, we will test everything to ensure it’s working.

  • Go live!

  • Estimated effort:
    3 days

  • Requirements:
    Back-end developer