Migration Guide (v12)

Migration Guide for v10 or older

The latest script version currently offered by the Site Search 360 Plugin is v12. To upgrade, usually you simply need to change the number in the script, e.g. -v11.min.js => -v12.min.js. You can also check our Release Notes.

However, version 11 introduced a lot of improvements and major changes in the configuration structure which are not backwards compatible. So if you're using v10 or older, please refer to the Migration section to update your code syntax first. The new syntax is compatible with all later script versions.


And here are some important reasons why you should consider upgrading!

New Major Features

In v11 we've implemented some features that many of you were asking for - tabbed search results, grid layout, or, for example, the option to disable cookies.

Enhanced Tracking

Before we start with features that will be useful for only some Site Search 360 integrations, let's look at our new and enhanced tracking which could make a huge difference for all of you. Analytics can help you leverage your product and make it shine - it makes all the difference between the average and the extraordinary. That's why we are investing a major part of our resources to provide you with the best analytics possible. It's now up to you to take the next step by upgrading to v11. In the near future we will be adding another analytics feature to our control panel - an overview of links that have been clicked on from your search result pages, so you can evaluate how well your queries perform. You don't want us to use enhanced tracking on your page? Simply adjust your ss360Config like this:

Tabbed Navigation

A feature many of you have been waiting for. Until now the only way to navigate through content groups on the search result page was by clicking on a button that would make the SERP scroll to the required content group. V11 allows you to keep distinct content groups in separate tabs (live example). Tabbed navigation (position: top) Tabbed navigation (position: left) You can also easily specify the spacing between tabs, their border radius, and even the title of the tab content. Here is a sample configuration:
We are also using fallbacks for smaller screen resolutions or huge content group counts resulting in a nice layout on all devices.
Tabbed navigation (mobile devices)

Grid Layout

Before now, implementing a grid layout within Site Search 360 required some serious skills. Since a grid layout might be the better option for many of you, we've added a simple way to do this, no matter your skill level (live example). Grid layout Additionally, we've added a layout object to our ss360Config where you can specify the behavior for different screen resolutions. Let's look at an example:
In the given example we want to use a grid layout on both - mobile and desktop resolutions (992 px is the breakpoint) and we want to have 3 columns on desktop and 2 columns on mobile devices.

Hide parts of content from ss360Config

Instead of having to find the correct classes by yourself and hiding parts of search results in your stylesheets, we've made it simple to hide those directly from the plugin configuration. You can hide images, text snippets, titles, data points, and the result links (those are hidden by default). You can also apply different configurations for mobile and desktop devices (the breakpoint is 992px). Here is an example where we want to display the title, result link, and the image on mobile and everything except the result link on desktop:

Disable cookies

The need to control which data different service providers store in visitors' browsers has become really important. You can now simply set the allowCookies option in the ss360Config to false and we won't set any cookies.
Please note that we are using Cloudflare to host our scripts. And there are some cookies that come from Cloudflare and not from us. Those cookies help ensure a secure connection to Cloudflare and don't store any personal information, so there is no need to try to avoid them at all costs, see Cloudflare's cookie policy. For this reason, if you want to avoid all cookies that might be set by Site Search 360, then you will need to host the script yourself (please also make sure that you keep Site Search 360 up-to-date as some bug fixes or additional tracking features might follow without us changing the major version of the plugin). Moreover, if you want to use the full extent of our upcoming analytics solution you might want to keep cookies enabled to benefit from better understanding of your visitors' sessions as those are tracked using cookies.

Smart 404

An incomprehensible 404 page might cause many of your visitors to leave your website and choose a competitor instead. Using our new Smart 404 feature, you can make sure that your visitors always find what they have been looking for. Simply add a smart404 object to your ss360Config and let us do the job of finding out what the visitor expected to find. All you need to do is specify a unique identifier that indicates the 404 page (the page title), the selector where alternative results should be rendered, and the caption:

Voice Search

Speech recognition has been among us for many years and is still on the rise. The perfect time to jump in with our Voice Search. All you have to do is to enable the Voice Search function by adding a voiceSearch object to your ss360Config like this:
We will take care of the rest - adding a microphone icon to your search box for compatible browsers (Google Chrome, Chrome for Android and Samsung Internet), ignoring the incompatible ones, error handling and processing of the recognized text.

Redirect On Single Result

Showing the SERP when having only a single search result? Set the redirectOnSingle property of the results object to true and the user will be redirected directly to the search result page.

Better configuration structure

You might have noticed that the ss360Config was getting a bit overwhelming as new features were added. . To address this issue, we've decided to group the settings semantically. Thus, the configuration has become more of a hierarchical structure than a linear one. For example, the numResults option can now be found under results.num. Here you can see how the new default configuration looks:

Manually adjusting the ss360Config to fit the current structure wouldn't make much sense. That's why we have provided a simple tool to convert the old config into the new one (see Migration section).

Other Changes

  • Result counts are now based only on results available to the user in the current context
  • Search results are progressively loaded resulting in even shorter loading times (depending on your paging size) and more compact DOM structure
  • Result counts in navigation can be disabled with the layout.navigation.showGroupResultCount setting


If you are migrating from an older plugin version (v10 and older), please read this section and test thoroughly in your staging environment before making any public changes.

Update your ss360Config and script reference

First you will need to update your ss360Config to match the new structure (more about this in Better configuration structure section). Simply copy your current ss360Config (without comments and callbacks, you can add your callbacks in the 'callbacks' configuration of ss360Config, the only exception is the 'externalTracking.searchCallback' which should now be placed under the 'tracking' configuration) into the following input field and the updated configuration will be generated for you.

Not sure what to paste? Just go to a page where you are using Site Search 360, open the developer console (ctrl+shift+j or f12), execute console.log(JSON.stringify(ss360Config)); and copy everything that gets logged on the console.

Then you can take the updated ss360Config, replace it on your page, and update the script reference to load the latest v12 version like this:
<script type="module" src="https://cdn.sitesearch360.com/sitesearch360-v12.mjs"></script>
<script nomodule src="https://cdn.sitesearch360.com/sitesearch360-v12.min.js" async></script>

Check your pagination

After updating to v11 you should check whether your pagination behaves as expected. In the latest version, we load search results progressively instead of showing all results by default. The paging size now defaults to 12, max results to 96, and the more results button text to 'Show more results'. You can adjust those values like this (please note that the page size cannot be greater than 24):
If you want to show all available results at once, you should set the moreResultsButton to 'null' like this:
If you are using a grid layout, please be sure to set the the moreResultsPagingSize to a number that is evenly divisible by the number of columns you are using. This way there will be no gaps and your layout will always look nice (this is why it defaults to 12).

Check your suggest box

In v11, your suggestion box will now be as wide as the search field by default (but at least 275px). If you want it to be wider or narrower you can specify the 'maxWidth' property in the 'suggestions' configuration object like this:

Update all your changeConfig calls

If you are using SS360's changeConfig method, you will need to update all the keys to match the new configuration structure. For example, if you were changing the included content groups like this:
You would now have to change the key to 'contentGroups.include' (simply the path in the ss360Config object) instead of 'includeContentGroups':