How to upgrade to the latest Site Search 360 version (v13)

Migration guide for v10 or older versions

The latest script version currently offered by the Site Search 360 Plugin is v13.

If you're upgrading from v11 or v12 versions of the Site Search 360 script, please refer to our Release Notes.

If you're upgrading from v10 or older, you need to update your code structure first - v11 introduced a lot of improvements and changes which are not backwards compatible. To easily generate the new code, follow our Migration instructions. Once this is out of the way, you can add the v13 script at the end of your configuration code and enjoy the brand-new look and feel!

Still hesitant whether you should bother upgrading your not-so-pretty but steady-working v7, v9, or v10? Let's see why it's worth your time!

New features

Since v11, you can enjoy the features so many of you have been asking for - tabbed search results, grid layout, or, for example, the option to disable cookies.

Our new enhanced tracking makes a huge difference and brings you valuable insight into your user search behavior. 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 continuously work on providing you with the best analytics possible.

Are you interested in evaluating how well your queries perform? What's your search result page bounce rate? What queries bring 0 results? We'll start (anonymously!) collecting the necessary data as soon as you upgrade.

And if you don't want us to use enhanced tracking on your site, simply adjust your ss360Config like this:

var ss360Config = {
   ...,
   /* Turn off enhanced tracking */
   tracking: {
      enhanced: false
   }
};

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. v13 allows you to keep your content groups neatly organized in separate tabs by default + it automatically adds an All results content group (live example).

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:

var ss360Config = {
   ...,
   /* Show tabs */
   layout: {
      navigation: {
         type: 'tabs', //"tabs" or "scroll"
         position: 'top', // navigation "top", "left", or "none"
         tabSpacingPx: 8, // 8px by default
         borderRadiusPx: 3, // 3px by default
         tabTitle: 'Found #COUNT# #NAME# for \'#QUERY#\'' // e.g. "Found 43 Recipes for 'chocolate cake'"
      }
   }
};

We are also using fallbacks for smaller screen resolutions or huge content group counts resulting in a nice layout on all devices.

Implementing a grid layout with Site Search 360 is no longer a brainer! Since it's especially beneficial to show products in a grid if you run an ecommerce website, we've added a simple way to do this, no matter your skill level (live example).

Additionally, we now have a few settings that allow you to easily adjust the behavior for different screen resolutions. Let's take an example:

var ss360Config = {
   ...,
   /* Use grid layout */
   layout: {
      mobile: { // below 992px
         type: 'grid', // 'grid' or 'list'
         gridColsMd: 2, // grid layout column count for devices between 768px and 991px, default: 2
         gridColsSm: 2 // grid layout column count for devices below 768px, default: 1
      },
      desktop: { //992 px and larger
         type: 'grid', // 'grid' or 'list'
         gridColsXl: 3, // grid layout column count for devices larger than 1200px, default: 4
         gridColsLg: 3 // grid layout column count for devices between 992px and 1199px, default: 3
      }
   }
};

In the example above we're using grid layout on both, mobile and desktop, resolutions (992px is the breakpoint) and we want to have 3 columns on desktop and 2 columns on mobile devices.

Instead of having to manually hide parts of your search result layout in your stylesheets, we've made it simple to hide those directly by setting the desired parameters in the config. You can hide images, text snippets, titles, data points, and result URLs (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 only the title, result link, and the image on mobile but keep everything except the URL on desktop:

var ss360Config = {
   ...,
   layout: {
      /* Hide snippet and data points on mobile devices */
      mobile: { // below 992px
         showImages: true, // whether to show images in search result, default: true
         showSnippet: false, // whether to show text snippet in search result, default: true
         showTitle: true, // whether to show title in search result, default: true
         showDataPoints: false, // whether to show data points in search result, default: true
         showUrl: true, // whether to show link in search result, default: false
      },
      /* Show everything on desktop resolutions (those are also the defaults, so you don't need this part) */
      desktop: { //992 px and larger
         showImages: true
         showSnippet: true
         showTitle: true
         showDataPoints: true
         showUrl: false
      }
   }
};

Being able to control what data is stored in visitors' browsers by different service providers has become really important in the light of GDPR and similar regulations. You can now simply set the allowCookies option in the ss360Config to false and we won't set any cookies.

var ss360Config = {
   ...,
   /* Disable cookies */
   allowCookies: false
};

Please note that we are using a CDN provider (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, in which case you'd also need to make sure that your Site Search 360 script version is always up to date as some bug fixes usually follow without us changing the major version of the plugin.

Moreover, if you'd like to use our searcb analytics to its full potential, you might want to keep the cookies enabled to benefit from a better understanding of your searchers' sessions as those are tracked using cookies.

An incomprehensible 404 page might force 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 your 404 page (the page title), the selector where alternative results should be rendered, and the caption:

var ss360Config = {
   ...,
   smart404: {
      identifier: 'Page not found', // The string in the title that identifies the page as a 404 page
      resultSelector: '#ss360-404', // A CSS selector that points to the area in which the alternative links should be shown
      caption: 'Try checking this instead:' // Caption for 404 results
   }
};

Speech recognition has been among us for many years and is very much on the rise. Google claimes to have reached a 95% word accuracy threshhold back in 2017! Now is the perfect time to jump in with our voice search . All you have to do is enable the voice search function by adding a voiceSearch object to your ss360Config like this:

var ss360Config = {
   ...,
   voiceSearch: {
      enabled: true, // whether to enable voice search for supported browsers (an microphone icon will be added to your search field if Speech Recognition API is supported)
      lang: 'en-US' // the input language (BCP 47 language tag)
   }
};

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 recognized text processing.

Does it seem silly to display the SERP when there's one and only search result available? Set the redirectOnSingle property of the results object to true and the user will be redirected directly to the search result page skipping the result layout altogether.

var ss360Config = {
   ...,
   results: {
      redirectOnSingle: true  // whether to redirect instead of showing a single search result
   }
};

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

Check what the new default configuration looks like:

{
    showErrors: true, // whether to show implementation errors, set to false for production
    allowCookies: true, // whether to allow the javascript to set cookies
    suggestions: {
       show: true,  // whether to show search suggestions
       maxQuerySuggestions: 3, // the maximum number of query suggestions
       querySuggestionHeadline: undefined, // the headline of the query suggestions, leave blank if no headline should be shown
       emptyQuerySuggestions: undefined,
       showImages: true, // show images in search suggestions
       num: 6, // the maximum number of search suggestions to be shown
       minChars: 3, // minimum number of characters before the suggestions shows, default: 3,
       maxWidth: 'auto', // the maximum width of the suggest box, default: as wide as the input box, at least 275px
       throttleTime: 300, // the number of milliseconds before the suggest is triggered after finished input, default: 300ms
       extraHtml: undefined, // extra HTML code that is shown in each search suggest, you can even show values of datapoints here,
       highlight: true, // whether matched words should be highlighted, default: true
    },
    style: {
       themeColor: '#1C5D7D', // the theme color affecting headlines, buttons, and links
       suggestions: undefined,
       defaultCss: true, // whether to include the default CSS,
       searchBox: undefined,
       loaderType: 'circle', // can be "cirle" or "square"
       animationSpeed: 250 // speed of the animations in milliseconds
    },
    searchBox: {
       placeholder: undefined,
       autofocus: false, // if true, the search box will get focus after initialization
       selector: '#searchBox', // the selector to the search box,
       searchButton: undefined, // CSS selector of search buttons
       focusLayer: false // if true, a layer will be shown when the user focuses on the search input
       },
    results: {
       embedConfig: undefined, // {'url':undefined,'contentBlock':'.page-content-body'}, // if url is given the page will change to that URL and look for the content block there to insert the results
       fullScreenConfig: undefined, // {trigger: '#ss360-search-trigger', caption: 'Search this site'}, trigger is the CSS selector to the element that starts the search full screen overlay and searchCaption the caption on the full screen search page
       caption: 'Found #COUNT# search results for \"#QUERY#\"', // the caption of the search results
       group: true, // whether results should be grouped if content groups are available
       filters: undefined,
       num: 96, // the maximum number of search results to be shown
       highlightQueryTerms: true, // whether to highlight the query terms in search results
       moreResultsButton: "Show more results", // HTML for the more results button, all results will be shown if this is null
       noResultsText: 'Sorry, we have not found any matches for your query.', // the text to show when there are no results
       queryCorrectionText: 'Did you mean "#CORRECTION#"?',
       searchQueryParamName: 'ss360Query', // the name of the search query parameter
       linksOpenNewTab: false, // should clicking on the result links open a new tab/window?
       showSearchBoxLayover: true, //whether to show search box in search result layover
       moreResultsPagingSize: 12, // the number of new results to show each time the more results button is pressed (max: 24)
       orderByRelevanceText: "Relevance", // the text to be shown in order select box to describe 'order by relevance' option
       redirectOnSingle: false  // whether to redirect instead of showing a single search result
    },
    contentGroups: {
       include: undefined,
       exclude: undefined,
       otherName: '', // the name of the results not in any other content group
       ignoreOther: false // whether or not to ignore the "other" content group
    },
    tracking: {
       providers: [], // how to track, supported values: 'GA' (Google Analytics), 'GTM' (Google Tag Manager)
       searchCallback: undefined, // callback before SERP is reported, SERP events aren't reported if this returns false, you'll get the query as the parameter for the callback
       enhanced: true
    },
    callbacks: {
       suggestChange: undefined, // callback triggered after suggestion set is changed, takes boolean indicating whether suggestions are visible as argument
       redirect: undefined, // callback to handle search redirects, takes redirect url as parameter, window.location.href is changed by default
       preSearch: undefined, // a callback that is triggered before the search is executed, e.g. to catch empty queries
       postSearch: undefined, // a callback that is triggered after the search results have been populated
       preSuggest: undefined, // a callback that is triggered before the search suggest is executed, takes the query and search box reference as arguments
       searchResult: undefined, // a callback that is triggered after the search is executed, e.g. to build your own result page from the response
       enter: SS360.showResults, // callback on what should happen when enter is pressed and focus is in input field
       enterResult: SS360.followLink, // callback on what should happen when enter is pressed when a link is selected, default: undefined, meaning the link will be followed
       type: SS360.recordTyping,
       blur: SS360.blur,
       focus: SS360.focus,
       closeLayer: undefined,
       init: undefined // function to call after initialization is complete
    },
    accessibility: {
       isMainContent: false, // whether to mark ss360 layer as main content of the page
       resultTopHeadingLevel: 2, // heading level to start with in search result (default h3)
       suggestHeadingLevel: 2, // heading level to use in search suggestions, for content group heading
       searchFieldLabel: 'Search', // invisible label to be used with screen readers when search field is focused, will only be used if value is not empty and there is no label element associated to the search field,default: 'Search'
       srSuggestionsHiddenText: 'Search suggestions are hidden', // text to announce @screen reader after search suggestions have been hidden
       srNoSuggestionsText: 'No search suggestions', // text to announce @screen reader if no suggestions are available
       srSuggestionsCountText: '#COUNT# search suggestions shown', // text to announce @screen reader after search suggestions have been shown, #COUNT# will be replaced with the suggestion count
       srOneSuggestionText: 'One search suggestion shown',// text to announce @screen reader after search suggestions have been shown
       srSuggestBoxControlDescription: 'Use up and down arrows to select available result. Press enter to go to selected search result. Touch devices users can use touch and swipe gestures.' // text to announce @screen reader after search input is focused - describes keyboard controls
    },
    specialMobileSuggest: {
       enabled: undefined, // whether to show special mobile suggests, default: suggestions.show && style.defaultCss
       breakpoint: 768, // css breakpoint to show mobile suggests (max-width: breakpoint)
       placeholder: '', // placeholder for empty suggestions
       searchBoxPlaceholder: '', // the special search box placeholder
       customTopHtml: '', // additional html/text content to be shown above special mobile search field
       animateTransitions: true, // whether to animate special mobile transitions
       resizeSearchBoxOnScroll: true // whether to resize search field when user scrolls special mobile suggests
    },
    smart404: {
       identifier: 'Page not found', // the string in the title that identifies the page as a 404 page
       resultSelector: '#ss360-404', // a CSS selector that points to the area in which the alternative links should be shown
       caption: 'Try going here instead:' // caption for 404 results
    },
    layout: {
       mobile: { // below 992px
          type: 'list', // can be either "grid" or "list", default: "list"
          showImages: true, // whether to show images in search result, default: true
          showSnippet: true, // whether to show text snippet in search result, default: true
          showTitle: true, // whether to show title in search result, default: true
          showDataPoints: true, // whether to show data points in search result, default: true
          showUrl: false, // whether to show link in search result, default: false
          gridColsMd: 2, // grid layout column count for devices between 768px and 991px, default: 2
          gridColsSm: 1 // grid layout column count for devices below 768px, default: 1
       },
       desktop: { // 992 px and larger
          type: 'list', // can be either "grid" or "list", default: "list"
          showImages: true, // whether to show images in search result, default: true
          showSnippet: true, // whether to show text snippet in search result, default: true
          showTitle: true, // whether to show title in search result, default: true
          showDataPoints: true, // whether to show data points in search result, default: true
          showUrl: false, // whether to show link in search result, default: false
          gridColsXl: 4, // grid layout column count for devices larger than 1200px, default: 4
          gridColsLg: 3 // grid layout column count for devices between 992px and 1199px, default: 3
       },
       navigation: {
          position: 'none',  // navigation "top", "left", or "none"
          type: 'scroll', // the navigation layout 'scroll' or 'tabs', for more then 6 (position: 'top') or 10 (position: 'left') content groups the 'scroll' navigation will be used
          tabSpacingPx: 5, // spacing between tabs
          borderRadiusPx: 3, // tab border radius
          tabTitle: 'Found #COUNT# #NAME# for \'#QUERY#\'', // e.g. 'Found 43 Recipes for "curry"'
          showGroupResultCount: true // whether to show the count of results in specific content group in the navigation
       }
    },
     voiceSearch: {
         enabled: false, // whether to enable voice search for supported browsers (an microphone icon will be added to your search field if Speech Recognition API is supported)
         lang: 'en-US' // the input language (BCP 47 language tag)
     }
}

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 the Migration section).

  • Result counts are now based only on results available to the user in the current context

  • Search results and images are loaded progressively leading to even shorter loading times (depending on your paging size) and a more compact DOM structure

  • Result counts in navigation can be disabled with the layout.navigation.showGroupResultCount setting

Update the old configuration code

If you are upgrading to v13 from an older script version (v10 and earlier), please read this section and test thoroughly in your staging environment before going live with the changes. Let us know if you need any help with the upgrade.

First you need to update your ss360Config to match the new structure. To do so, copy your current ss360Config without comments and callbacks into the following input field and the updated configuration will be generated for you on the right. Callbacks now go under the callbacks setting with the exception of externalTracking.searchCallback which should now be placed under the tracking setting.

Not sure what to copy and paste? Just go to a page where you are using Site Search 360, open the developer console (ctrl+shift+j or option+command+j if you're using macOS), type console.log(JSON.stringify(ss360Config));, press Enter, and copy everything that gets logged on the console.

Now you can take the updated code, replace the old one with it on your site, and update the script reference to load the latest v13 version like this:

<script src="https://cdn.sitesearch360.com/v13/sitesearch360-v13.min.js" async></script>

After updating to v13, you should check whether your pagination behaves as expected. In the latest version, we load search results progressively instead of showing all at once. The paging size now defaults to 12, max results to 96, and the more results button text to 'See more'.

You can adjust those values like this (please note that the page size cannot be greater than 24):

var ss360Config = {
...,
/* Adjust pagination */
results: {
num: 48,
moreResultsPagingSize: 24,
moreResultsButton: '+'}
};

If you want to show all available results at once, you should set the moreResultsButton to null like this:

var ss360Config = {
...,
/* Show all results at once */
results: {
moreResultsButton: null
}
};

If you are using grid layout, please be sure to set the moreResultsPagingSize to a number that is evenly divisible by the number of columns you are using. This way your search result layout won't have any gaps (this is why it defaults to 12).

In v13, your suggestions will 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:

var ss360Config = {
...,
/* Limit the width of the suggest box */
suggestions: {
maxWidth: 800
}
};

If you are using Site Search 360'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:

SS360.changeConfig('includeContentGroups',['Menu Items']);
SS360.changeConfig('contentGroups.include',['Menu Items']);