Overview

SoloSegment provides SearchBox to help your content owners analyze the usage and effectiveness of your website search facility. SearchBox requires two pieces of information to gather the right data. First it needs an API Key that identifies your unique website. Second, to enable the activity metrics to be collected when your searchers use your website search facility, you must provide required information about each search, your search page, and the results.

The JavaScript file that is on your “Getting Started” page needs to be embedded on your search results page. This file includes a unique API key that identifies your website and provides access to the Solosegment object. Within this object, you will populate the required information later detailed in this article and call the functions provided to allow the Collector to operate.

If that last paragraph didn’t make sense to you (or any of the coming text leaves you scratching your head), you may need some help from your development team to complete the installation. You can also contact your SoloSegment account manager for guidance. Your Account Manager is indicated in the Welcome email you received when you signed up for the Site Search Inspector.

Information Required for Collection

To accurately collect activity metrics, the collector needs particular information about each search along with additional links and your API key, all of which is stored in the Solosegment.data object.

To populate the Solosegment.data object, there are two main approaches:

  1. Provide the value directly, either through the use of your own stored values used to populate your search page or hard-coding the values.
  2. Provide CSS Selectors that will prompt the Collector to parse the Document Object Model (DOM) for the required values.

*Further information about setting the Solosegment.data object is provided in later sections of this article.

Below is a list of the required information, a description of each, which approach you may take to populate the Solosegment.data object, and a table describing the value types and examples.

API Key

The API key can be found on your “Getting Started” page as well as on your Profile page in SearchBox. The API key provides access to the API and appropriate databases for search activity storage.

The API key must have its value provided directly via hard-coding into your embedded JavaScript. The “Getting Started” page provides the default JavaScript.

Search Term

The Search Term is the term searched by your end users that is provided to the search engine.

Provide this information by value. This information may already be stored in one of your site’s JS objects or you may parse it from the URL params. Note that sending an empty ‘search_term’ will cause no communication between the browser and server.

Search Results

The Search Results are the URLs provided back to the end user and presented to the screen. The order of these search results matter and when populating the Solosegment.data object, the order stored should reflect the order shown in the user interface.

This information may be provided by value or by CSS selector. If your search page uses templates to aid in populating the page, there may be an object that already has each URL (href). If that data is available, you may use that information to create an array of URL strings in the same order it is shown on screen and store it to the Solosegment.data object.

You may also provide a distinct CSS selector for the Collector to easily identify individual results. The Collector will then parse the DOM and store each <a> tag’s href attribute in the order shown to the end user as an array of strings.

NOTE: If your search page does not reload the page entirely to show new results from a different page or new search, you will need to update the Solosegment.data object and notify the collector, appropriately. This note is later discussed in this article.

No Search Results Found

A No Results search event, where no URLs are returned is treated differently than a normal search result that includes URLs. When no results are found for a search, it should be explicitly told to the collector.

You must provide the Solosegment.data object this information by value, but there are two values you may provide: boolean value or the string presented to the end user indicating no results are found. The string value will prompt a DOM parse.

Search Facets

Search facets allow for filtering of search results and presenting the data to the end user in many different ways. If you use facets on your search results page you will need to provide that data. Currently, to store facet information, the search term should be provided along with the facet. Facets are called “category” in the Solosegment.data object.

Facet information should be provided by value. See table below for key values in the Solosegment.data object.

Pagination Details

Pagination allows for efficient display of large data lists, splitting the lists into separate pages with a certain amount of data per page. With regards to search results, a common approach is to provide the end user an option to change the number of items displayed per pages (termed results per page in this article) and an option to change which page is displayed (termed current page).

The current page number and the number of results per page should be provided to the Solosegment.data object in order to appropriately rank the position of URLs as the appear on the page. If this pagination data is not provided, a rank will not be calculated and stored.

The results per page and current page information should be stored by value. This information may also already be stored in an object in your site’s JS or accessible via URL.

Advertisements (Additional Links)

Any other additional links you would like to track, such as advertisements (may also be referred to as Additional Links or Featured Links), may also be provided, but are not required. These links will have its clicks tracked on the search page, but no ranking information will be computed.

Storing this information is similar to the Search Results approach. You may either directly provide an array of URL strings in the order shown to the user or you may provide a distinct CSS selector to parse the DOM for the URLs from the links.

Note: Prepend the Property Name with “Solosegment.data”

Required Information Property Name Type Example
API Key (by value) apiKey String “99d32sfj38ieKerdfc”
Search Term (by value) search_term String “Customer Service”

*Note that sending an empty ‘search_term’ will cause no communication between the browser and server.

Search Results (by value) results [ ] Array of Strings [“http://url.com”,
“https://url2.net”]
No Results Found (by value) no_results_found
no_results_string
Boolean
String
true (no results found)
“There were no matches for”
Search Results (by CSS) result_tag String (using CSS [Attribute] Selector) “div[‘class=result’]”
Search Facets (by value) search_facets { term: “search term”,
category: “all | filter” }
{ term: “warranty”,
category: “All” }
Pagination Details (by value) current_page /
results_per_page
Integer 0
20
Advertisements (by value) ads [ ] Array of Strings [“http://ad1.org”,
“https://ad2.io”]
Advertisements (by CSS) advertisement_tag String (using CSS [Attribute] Selector) “div[‘class=adLink’]”

Preparing Your Website’s Results Page

CSS Attribute Selector Approach

With the use of CSS attribute selectors, you may add attributes to your HTML to indicate specific areas of your page to allow the SearchBox Collector to gather the appropriate data to accurately track user interaction and search results on your results page. The following areas of your HTML must be specifically indicated by some sort of distinct class name or attribute value:

HTML Areas Description
Individual Search Result This element should contain a single search result and a single <a> tag containing the URL.
Advertisements
(Additional Links)
This element should encompass a single advertisement containing a single a-link.

We ask you to add class attributes to some of your tags so that we can recognize these specific areas of your site. For example, to determine whether the searcher clicks on a search result or not, we need to know which tags on your page are actually search results. To do that, we ask you to add a class attribute (e.g. class=”solosegment-result”) to that tag. Often, your search results page is being generated by a program, so you would actually be changing the HTML template used by the program rather than an actual HTML page.

For example, if your HTML template encloses in brackets every program-inserted variable, and each of your search results is enclosed in a div tag, like so:

<!-- HTML BEFORE -->
<div class="result-link">
<p><a class="title-link" href="[result-url]">[result-title]</a></p>
<br/>
<span class="snippet">[result-snippet]</span>
<span class="url">[result-url]</span>
</div>

You can simply add the class of your choosing to that div tag, like so:

<div class="solosegment-result"> … </div>

If you already have a class attribute on your <div> tag, like so:

<div class="result-link"> … </div>

You can add your separate class attribute if you wish to do so:

<div class="result-link solosegment-result"> … </div>

It is recommended to try and attach the CSS selector as close to the data values as possible in order to be more compatible with the collector’s library. Also, note that you are not restricted to the use of just classes, you may also use other attributes such as IDs.

Below is a basic example of what a website’s results page HTML using separate classes.

<!-- EXAMPLE HTML -->
<html>
 <head>Client Search Engine</head>
 <body>
 <!-- SEARCHBAR BEGIN -->
 <div class="someOtherClass">
 <form id="clientSearchBox"  action="#" method="get">
 <p>
 <input type="text" value="i search term"/>
 <input type="submit" value="Submit"/>
 </p>
 </form>
 </div>
 <!-- END SEARCHBAR -->

 <main id="client-site-body">

 <!-- SEARCH RESULTS CONTAINER -->
 <div id="client-search-results">
 <!-- INDIVIDUAL RESULT -->
 <div class="client-search-result solosegment-result">
 <h2><a href="https://www.test.com">Test</a></h2>
 <p>This link will go to google.com</p>
 </div>
 <!-- END INDIVIDUAL RESULT -->

 <!-- INDIVIDUAL RESULT -->
 <div class="client-search-result solosegment-result">
 <h2><a href="https://www.test2.com">Test2</a></h2>
 <p>This link will go to yahoo.com</p>
 </div>
 <!-- END INDIVIDUAL RESULT -->
 </div>
 <!-- END SEARCH RESULTS CONTAINER -->
 <!-- PAGINATION -->
 <ul id="client-pagination" >
 <li><a href="#">Page number 1</a></li>
 <li><a href="#">Page number 2</a></li>
 </ul>
 <!-- END PAGINATION -->
 </main>
<!-- continued on next page -->
 <!-- ADVERTISEMENT -->
 <div id="client-advertising" class="solosegment-ad">
 <a href="http://ads.com/">Ad Text Here</a>
 </div>
 <!-- END ADVERTISEMENT -->
 </body>
</html>

Provide Information by Value

For the direct approach, your web developer will utilize objects that already exist within your site’s DOM or JavaScript code used to display your current search results. The following SoloSegment data properties must be set by code written by the web developer on your website’s search page:

Note: Prepend the Property Name with “Solosegment.data”

Required Information Property Name Type Example
API Key (by value) apiKey String “99d32sfj38ieKerdfc”
Search Term (by value) search_term String “Customer Service”

*Note that sending an empty ‘search_term’ will cause no communication between the browser and server.

Search Results (by value) results [ ] Array of Strings [“http://url.com”,
“https://url2.net”]
No Results Found (by value) no_results_found
no_results_string
Boolean
String
true (no results found)
“There were no matches for”
Search Facets (by value) search_facets { term: “search term”,
 category: “all | filter” }
{ term: “warranty”,
 category: “All” }
Pagination Details (by value) current_page /
results_per_page
Integer 0
20
Advertisements (by value) ads [ ] Array of Strings [“http://ad1.org”,
“https://ad2.io”]

The Search Results and Advertisements arrays would be automatically set by the CSS attribute selector approach, but providing this option allows you to use a combination of both approaches as the web developer for your site sees fit. This is especially useful if your page is somewhat complex or dynamic, such that your results or ads do not always load in at the same time. Thus, as data arrives, you can populate the object accordingly.

Placing the SearchBox Collector on Your Page

Your account manager should have provided you with your customized JavaScript code source URL that serves as your SearchBox Collector. Place that code or reference to the code as close to the bottom of the HTML as possible, such as at the bottom of the <body> or in the <footer>. Note the pair of <script> elements shown. Place the reference to the SearchBox Collector first, followed by a second set of script tags to set required data to indicate API key, class names, and pagination information.

<!-- INCLUDE SEARCHBOX COLLECTOR -->
 <footer>
 <script src="https://api.solosegment.com/analytics/embed/?u=YOUR API KEY"></script>
 <script type="text/javascript">
 Solosegment.data.apiKey = "....";
 /* … Further Configuration … */
 Solosegment.analyze();
 </script>
 </footer>
 <!-- END JAVASCRIPT -->

Here you may put in the logic to fill in the Solosegment.data object using your site’s getter functions your web developer may have created for a direct approach along with any CSS selectors you would like to use to grab that information. As the page loads its results and any other pertinent links, you may update these values. Otherwise, do not alter the provided JavaScript code without checking first with your account manager.

Note: We recommend that users of SearchBox install our JavaScript directly on their website. Many website owners may opt to install the JavaScript through third-party technologies, such as Google Tag Manager, but please be aware that certain browser adblockers may block these tracking managers, which will prevent the loading of our JavaScript and subsequent data collection.

Providing SearchBox Collector Configuration Settings

To inform the Site Search Inspector Collector on the names of the classes, pagination information, and your API key you can create a second set of <script> tags. The two main properties of the SoloSegment object are the apiKey and the data properties. Provide your API key as a string by setting the apiKey property of the Solosegment data object.

The data property of the Solosegment object is a set of name:value pairs, thus allowing you to access them as shown below.

As previously described, some of the data values allow you to provide HTML classes you have used to tag elements with the information we need. Simply give each data value the appropriate class name for each section described earlier in this article. Each class name should be unique with regards to which area of the HTML the element will represent. For example, do not use the same class name to represent the results container and an individual result. If you choose to use your own class names, be sure to configure the settings, appropriately. In the same <script> tags, you may insert any code that will provide any additional data described the “Direct Approach” section of under the heading “Preparing Your Website’s Results Page.”


<script type="text/javascript">
 // Set API Key - EXAMPLE ONLY
 Solosegment.data.apiKey = "15abcd3EFg4hErer2xZ";


// Directly pass the urls returned by your search (in order, limit 10)

Solosegment.data.results = [

“http://www.website.com/path/to/page/1/”,

“http://www.website.com/path/to/page/2/”,

“http://www.website.com/path/to/page/3/”

]

// Alternatively, set Individual Results Class
Solosegment.data.result_tag = "div[class=‘solosegment-result’]";




// Directly pass the urls for additional links or ads returned by your page

Solosegment.data.ads = [

“http://www.website.com/path/to/ad/1.pdf”,

“http://www.website.com/path/to/ad/2.pdf”,

“http://www.website.com/path/to/ad/3.pdf”

]




// Alternatively, set Advertisement Class 
Solosegment.data.advertisement = "div[class=‘solosegment-ad’]";

//Inform us directly which term was searched

Solosegment.data.search_term = app.request.input;




//Alternatively provide us with the facets of a multifaceted search

Solosegment.data.search_facets = {

term: app.request.input, // Sample Term

category: app.request.query.servicetype  // Sample Facet

};


// Provide Results Per Page Data - Code/Logic inserted here to provide current page
Solosegment.data.results_per_page = 10;
// Provide Current Page Data - Code/Logic inserted here to provide current page
Solosegment.data.current_page = 1;




// Inform us directly that no results were found

Solosegment.data.no_results_found = true;

// Alternatively provide String that indicates no results found

Solosegment.data.no_results_string = "No Results Found";

</script>

Using WordPress?

If you’re using WordPress, some configuration may be unnecessary. Instead, copy and paste the implementation example below, filling in where specified.

<script src="https://api.solosegment.com/analytics/embed/?u=YOUR API KEY"></script>
<script type="text/javascript">
 // Set API Key - EXAMPLE ONLY, REPLACE WITH YOUR API KEY
 Solosegment.data.apiKey = "15abcd3EFg4hErer2xZ";

// Set Individual Results Class
Solosegment.data.result_tag = "div[class=‘YOUR CLASS HERE’]";

// Leave this section untouched
var site = window.location.href;
var query = site.split("?");
var value = "";

if (query.length > 1){
 if (query[1].indexOf("&") > -1){
   query = query[1].split("&");
   for (var i = 0; i < query.length; i++){
     console.log(query[i]);
     var pair = query[i].split("=");
     if (pair){
       if (pair[0] === 's'){
         value = pair[1];  
       }
     }
   }
 }
 else{
   var pair = query[1].split("=");
   if (pair){
     if (pair[0] === 's'){
       value = pair[1];  
     }
   }
 }  
}  

if (value != ""){
Solosegment.data.search_term = value.replace(/\+/g, ' ');

//

// Provide Results Per Page Data - Code/Logic inserted here to provide current page
Solosegment.data.results_per_page = 10;

// Provide Current Page Data - Code/Logic inserted here to provide current page
Solosegment.data.current_page = 1;

// Provide String that indicates no results found
Solosegment.data.no_results_string = "No results for your search";

</script>

Starting the SearchBox Collector

Starting the SearchBox Collector is as simple as calling the Solosegment.analyze() method once the search page has loaded and you have set the appropriate configuration.

Ideally, the Solosegment.analyze() should only be called once the search results have loaded and the appropriate Solosegment.data attributes have been set. For most static search pages, this simply means calling the function near the bottom of the page. If your search results are loaded dynamically, you should call this function once they are loaded.

When Solosegment.analyze() is called, it gathers information about the search from the results page, and sends it with the information you provide in SoloSegment.data to our server for further analysis.

Calling Solosegment.analyze() multiple times in succession is not a problem as it will not send data until one of the following happens:

    • Search results differ from previous analyze call
    • Search term differs from previous analyze call
  • Search facet differs from previous analyze call

Solosegment.analyze() will only return true if it locates (via css class tags) or is provided (via Solosegment.data) both a term and at least one result or the “no result” status. Otherwise it returns false. Solosegment.analyze()only records a search when it returns true. With this design you can run and test that it has received the data it requires allowing you to provide more data and calling analyze again if necessary.

Implementation Example

Here is an example of calling SoloSegment with all data provided directly via javascript. This is the most efficient and accurate way to use SoloSegment.

On a static search page, this would simply be called once at the bottom of the page.

<script src="https://api.solosegment.com/analytics/embed/?u=YOUR API KEY"></script>


<script type="text/javascript">
 Solosegment.data.apiKey = "15abcd3EFg4hErer2xZ";
 Solosegment.data.results_container = ".solosegment-results";

Solosegment.data.results = [

“http://www.ibm.com/analytics/us/en/technology/spss/”,

“https://www.ibm.com/software/analytics/spss/products/statistics/”,

“http://www.ibm.com/software/products/en/spss-statistics”

];

Solosegment.data.search_facets = {

term: "bluemix",

category: "all"

}; 
Solosegment.data.results_per_page = 10;
Solosegment.data.current_page = 1;

Solosegment.analyze();

</script>

On a dynamic search page, you would first put

<script src="https://api.solosegment.com/analytics/embed/?u=YOUR API KEY"></script>

somewhere in the initially loaded HTML, and then make the calls to populate SoloSegment.data you have any defined. Once the search results have properly loaded, call Solosegment.analyze(). If the search completes without returning results, you would set the no results found property:

Solosegment.data.no_results_found = true;

Instead of populating the results property:

SoloSegment.data.results = [ … ];

NOTE: Calling analyze is still required regardless of results or no results found:

Solosegment.analyze();

Manually Sending Results and Binding Links

The SearchBox Collector also provides methods to emulate the Solosegment.analyze() method in order to give more control to the web developer on when search results are sent, click actions are bound to links, or when click actions are sent to be analyzed. This approach may mainly be leveraged when the search page being analyzed does not always completely reload the page or loads in data dynamically (e.g. AJAX calls).

The functions below may be called in lieu of Solosegment.analyze():

  • Solosegment.bind_clicks()
    • This function will bind the click handler function in the collector library to listen for clicks on search results and send the packaged request to the API. This may be called as many times as you would like as the search results are loaded to the page.
  • Solosegment.bind_adclicks()
    • This function behaves similarly to the bind_clicks() function, but should be used specifically for advertisements or auxiliary links (non-result links).
  • Solosegment.send_results()
      • Once the results have loaded into the page, you may call this function to package and send the data to the Solosegment server for analysis.
    • This function should only be called once the results are loaded or changed. The change may come from a new search, a current page change, or results per page change.

*Note: that these functions do not currently take any input parameters, as the Solosegment.data object should have its values set as previously explained in this article.

Further Granularity in Sending Clicks

Additional functions are provided to allow ultimate control on when clicks are recorded on your search page through the following functions:

    • send_click(string result_URL) – Call this function to send data to the SoloSegment server with regards to an Search Result Click.
  • send_ad_click(string ad_URL) – Call this function to send data to the SoloSegment server with regards to an Advertisement Click.

You may call the above functions in a click handler function that is bound to your links, letting you control what results get bound. Do be aware that for search results, using this level of granularity, what is bound to be tracked for what links are clicked does not necessarily match the set of results sent to the SoloSegment server. If you use the bind_click() and bind_ad_click() functions will bind to what is in the Solosegment.data.results and Solosegment.data.ads arrays.