Implement Cludo’s API analytics script

15 Feb, 2023 FAQ

Cludo has developed a script specifically for API implementations. With this, you won’t have to manually set up tracking for your API implementation.

Introduction

The Cludo API Analytics script is a JavaScript snippet to be placed on your search results page that will send query and click data to Cludo’s analytics API. In addition to placing the code snippet on your search results page, you will need to render some key information on the page via data attributes. When the script is initialized, it parses the HTML document in order to find this information and will be sent to Cludo’s API for reporting analytics.

Instructions

Implementing the Cludo API Analytics script depends on whether you’re building the results server-side or client-side. For server-side result rendering, follow the instructions in the next section. For client-side rendering, skip ahead to the ‘Client-side search requests’ section.

Server-side search requests

Building the results server-side means that the results are part document returned from the web server. Solutions like this can integrate with the API analytics script through custom attributes to be added to the results markup that is processed by the script on load. If this sounds like you’re solution, follow the ‘Server-side search requests’ instructions.

1: Add query attributes to search results pages

The following data attributes can be added to ANY element that is rendered on your search results page. We do, however, recommend that it be placed on some element that logically wraps search results (i.e. search-results-container). There are two main functions that the script is responsible for: sending query data AND sending click data.

The second column in this table indicates its level of requirements. Implementing all of the ‘recommended’ and ‘required’ attributes will ensure you don’t miss out on any functionality driven by analytics data. The referral page title is marked as optional as it is only used for display purposes where we would display the referral URL when absent. In the table below, ‘cludoSearchResponse’ represents the JSON search response returned by the search API.
 

Query logging data attributeRequired?Description
data-cludo-query*RequiredThis is the search query that was executed.
Where to find it: Store it at search time and make it available during HTML document rendering
data-cludo-query-id*RequiredThis is the unique id that is returned in the search response from Cludo’s search API.
Where to find it: cludoSearchResponse.QueryId
data-cludo-page*RequiredThe page number that was requested in the search request to Cludo’s API.
Where to find it: Store it at search time and make it available during HTML document rendering
data-cludo-total-resultsRecommendedThe total number of results for the query. (Note: This does not represent the number of results per page.)
Where to find it: cludoSearchResponse.TotalDocument
data-cludo-banner-idsRecommendedThis is a comma-delimited string of the banner ids that matched the search query. This value should be built by building the delimited string by looping through the Banners property in the response and concatenating the ids.
Where to find it: cludoSearchResponse.Banners[@id]
data-cludo-referral-urlRecommendedThe page URL in which the search took place. Typically this would be the page the end-user was on just prior to displaying search results.
Where to find it: HTTP referrer header (commonly known as referer)
data-cludo-referral-titleOptionalThe title of the page from which the user originated. This should be the title for the page at the data-cludo-referral-url address.
Where to find it: This requires storing more comprehensive referral information at search time — often through query parameters
Code example
<div
  class="search-results" 
  data-cludo-query="test search term"
  data-cludo-query-id="search-response-guid-00000000000"
  data-cludo-cludo-page="1"
  data-cludo-total-results="173"
  data-cludo-banner-ids="2323,1234"
  data-cludo-referral-url="http://example.com/page/where/search/originated/from""
  data-cludo-referral-title="Contact Us"   
>
  <ul>
    <li class="search-result" data-cludo-search-result="Search Result Title">
      ...
    </li>
    ...
  </ul>  
</div>

2: Add support for click logging

Click logging builds on top of the data in step 1 as it generates a click log to be sent to Cludo. In order to add support for click tracking analytics, you need to add the following data attribute to each individual search result. The value assigned to the data attribute should be the title of the result it corresponds with: data-cludo-search-result=”Page Title”

Code example
<div class="search-results">
  <ul>
    <li class="search-result" data-cludo-search-result="Search Result Title">
      <h3>Search Result Title</h3>
      <p>Search result description</p>
      <a href="/path/to/search/result">http://example.com/path/to/search/result</a>;
    </li>
    <li class="search-result" data-cludo-search-result="Another Result Title">
      ...
    </li>
    ...
  </ul>  
</div>

3: Add JavaScript snippet to Search Results Page

Add the following JavaScript snippet to your website. Be sure to update the CUSTOMER_ID and ENGINE_ID with the correct values. These IDs can be found in MyCludo under Install › API.

<script type="text/javascript">
(function(c, l, u, d, o){
  var ele = document.createElement('script');
  m = document.getElementsByTagName('script')[0];
  ele.async = 1;
  ele.src = 'https://customer.cludo.com/scripts/bundles/analytics/1.0.3/cludo-statistics.app.js';
  ele.onload = function() {
    CludoSearch.initialize(c, l);
  };
  m.parentNode.insertBefore(ele, m);
})(CUSTOMER_ID, ENGINE_ID);
</script>

Once this step is complete, you should see analytics data showing up in your MyCludo dashboard. You can also validate that it’s working as expected by inspecting the network traffic in your browser. Typically this can be done by opening your browser’s dev tools (F12) and selecting the network tab. Shortly after page load, you should see a query log sent to Cludo’s API. You should also see a click log sent after clicking on individual results.

Client-side search requests

Building the results client-side means that that your website uses JavaScript to interact with Cludo’s search API. Results that come back from those requests are rendered client-side with JavaScript. These solutions require calling some JavaScript after the results are rendered in order to log the events associated with the request. Another function is invoked to add click handling such that when end users interact with the rendered search results, the event is also sent to Cludo’s API.

1. Add JavaScript snippet to the Search Results page

Add the following JavaScript snippet to your website. Be sure to update the CUSTOMER_ID and ENGINE_ID with the correct values. These IDs can be found in MyCludo under Configuration › API. Note: CUSTOMER_ID and ENGINE_ID should be strings.

<script type="text/javascript">
(function(c, l, u, d, o){
  var ele = document.createElement('script');
  m = document.getElementsByTagName('script')[0];
  ele.async = 1;
  ele.src = 'https://customer.cludo.com/scripts/bundles/analytics/1.0.3/cludo-statistics.app.js';;
  ele.onload = function() {
    CludoSearch.initialize(c, l, u);
  };
  m.parentNode.insertBefore(ele, m);
  window.CludoSearch = {
    eq: [],
    trackQuery: function() {
      return this.eq.push({ a: arguments, e: 'q' }) - 1;
    },
    trackClicks: function() {
      return this.eq.push({ a: arguments, e: 'c' }) - 1;
    },
  };
})(CUSTOMER_ID, ENGINE_ID, true);
</script>

Client-side requests occur in JavaScript. The previous step defined a global object (CludoSearch) which can now be used after a search to log that a query took place.

CludoSearch.trackQuery(
query: string,
queryId: string,
totalResults: number,
pageNumber: number,
referralUrl?: string,
referralPageTitle: string,
responseTime: number,
bannerIds: string): QueryLog
Parameters (asterisk (*) indicates required):
  • *query: string – The query that was searched.
  • *queryId: string – When a search response is returned from Cludo’s search API, it contains a query id (QueryId). This is the value that should be passed in.
  • *totalResults: number – The number of results for the search request. This value represents the total result set size, not the page size.
  • *pageNumber: number – The page number that was requested.
  • referralPageUrl: string – The URL where the search originally took place.
  • referralPageTitle: string – The page title for which the search originally took place.
  • responseTime: number – The number of milliseconds elapsed while waiting for the search request. This value is returned in the Cludo API response. If your solution uses a proxy server or server-side endpoints that interact with Cludo’s API, you could choose to time that request and use that value instead.
  • bannerIds: string – A comma delimited string with banner ids that were rendered in search results. If your solution utilizes banners, this is used to report when particular banners are returned from the search response and displayed to end users.
Returns

A QueryLog is returned from the trackQuery function. This will be used shortly after when registering click handling on the results.

Code example
CludoSearch.trackQuery(
  "test query",
  "dummy-query-id-abc-123",
  123,
  1,
  "https://example.com/homepage.html"",
  "Example Home",
  58,
  ""
);

3. Invoke CludoSearch.trackClicks after results are rendered

Once the results are rendered on the page, you can call CludoSearch.trackClicks and pass the associated QueryLog from the last step as well as a query selector targeting individual results for which click handling will be attached.

CludoSearch.trackClicks(queryLog: QueryLog, resultSelector: string): void;
Parameters
  • queryLog: QueryLog – This is the object that was returned from trackQuery in the previous step. If trackQuery is invoked after the results have been added to the DOM, these two method calls can happen in sequence.
  • resultSelector: string – This is a selector that is expected to return each result element. For each of the result elements returned, click handling will be attached to all of the anchor elements within the result so that result click events are sent to Cludo’s analytics API.
Code example

Suppose the following results are rendered:

<html>
  ...
  <body>
    ...
    <div class="search-results">
      <div class="search-results__result-item">
        <h3>First result title</h3>
        <p>First result description</p>
        <a href="...">...</a>
      </div>
      ...
      <div class="search-results__result-item">
        <h3>Last result title</h3>
        <p>Last result description</p>
        <a href="...">...</a>
      </div>
    </div>
    ...
  </body>
</html>

The selector that we need to pass into the trackClicks method needs to return the set of elements where each element is an individual result. So, in this case, if the example above renders 10 results, we would expect the selector to return 10 elements. The selector that will satisfy this condition from the example above would be .search-results__result-item.

Invoking trackQuery:
CludoSearch.trackClick(
  queryLog, // Returned from trackQuery function
  '.search-results__result-item'
);

After calling this method, click tracking will now be sent to Cludo’s API if an end-user selects any of the results from the result set that was rendered.

Limitations

This script does not currently support sending click analytics for banners.

Tags:  ,

Related Posts