Setting Up Cloud Usage Analytics Logging by the JavaScript Search With an On-Premises Index

You can use the Coveo Cloud Usage Analytics with an on-premises index. In this scenario, the index is hosted locally by a Coveo Enterprise Search (CES) instance, but the analytics data is sent from your Coveo search pages to an index-less Coveo Cloud Organization through the Coveo Search API.

When you acquire a Coveo license that includes Coveo Cloud Usage Analytics, the Coveo Cloud Organization hosting the analytics data is created for you by Coveo. As illustrated in the following figure, the on-premises Coveo Search API will act as a proxy to forward search event log calls from the Coveo JavaScript Search to your Coveo Cloud Organization.

UAwithOnPremisesIndex1

At this point, it is assumed that you have a working Coveo JavaScript Search page getting search results from an on-premises CES index through an on-premises Coveo Search API deployed as a Windows service (see Installing the Windows Service).

This topic describes how to configure the Coveo Search API and the Coveo JavaScript Search page to send usage analytics data to your Coveo Cloud Organization.

To set up cloud usage analytics logging with an on-premises index

  1. If not already done, contact Coveo Support to get the access token allowing you to push analytics data to your Coveo Cloud Organization.

  2. Configure the Coveo Search API to act as a proxy and redirect usage analytics logging calls:

    1. Using an administrator account, connect to the server on which the Coveo Search API is installed.

    2. Using a text editor, open the [Search_API_Install_Path]\config.yml file (by default C:\Program Files\Coveo Search API 8\config.yml).

    3. In the file, add an analytics section as follows:

       analytics:
         apiKey: copy_your_API_token_here
         endpoint: https://usageanalytics.coveo.com
      

      The endpoint parameter default value is https://usageanalytics.coveo.com, the generic URL used for all Coveo Cloud Organizations. You can therefore omit endpoint parameter.

      The apiKey value will be injected along with other search event data to perform the usage analytics logging calls. With this configuration, the apiKey value is never visible on the client side.

      The YAML format of the config.yml file does not accept tab characters. You must use spaces to indent the parameters.

      The Coveo Search API configuration file can contain other sections and other parameters (see Windows Service Configuration File).

    4. Save the config.yml file.

  3. Configure your Coveo JavaScript Search page to send usage analytics data to your Coveo Cloud Organization:

    1. Using a text editor, open your Coveo JavaScript Search page.

    2. Add the following HTML code inside the main search page DIV (with the class CoveoSearchInterface):

       <div class="CoveoAnalytics"
           data-endpoint="http://mysearchserver/rest/analytics/"
           data-search-hub="Main Search Page"
           data-anonymous="true"/>
      

      The CoveoAnalytics component has no visible elements in the user interface so it can be inserted anywhere in the CoveoSearchInterface class DIV, but you should insert it close to the beginning of the parent DIV to make it easier to find.

      Refer to the following table for details on the value of each CoveoAnalytics component attribute (see also Coveo Component Analytics).

      Attribute Value
      data-endpoint

      The URL of your on-premises Coveo REST Search API.

      http://mysearchserver/rest/analytics

      data-search-hub

      The string identifying the origin of the search event, setting both the Origin 1 (Page/Hub) Coveo Usage Analytics dimension [see Origin 1 (Page/Hub) (formerly Search Hub)] and the searchHub query field sent to the index with each query. This parameter is useful when you have more than one search access point and you want to be able to discriminate from which one search events occurred. The default value is default.

      data-anonymous

      The Coveo Usage Analytics Platform creates visit ID GUIDs for anonymous visitors to allow usage analysts to follow search events made by a given visitor. When both authenticated and anonymous visitors can push search events, it may become tedious to compare visitor IDs (Unique Visitor ID dimension) and identified users (Unique Users dimension).

      If you have mixed anonymous and authenticated visitors, when a user accesses the search page anonymously (not authenticated or logged in), set this Boolean attribute to true to allow the usage analytics platform to consolidated a dimension that mixes user names and anonymous visitor ID GUIDs.

      The default is false, in which case all anonymous visitors appear as one anonymous user in the Unique Users dimension.

      data-token In this configuration, you must not set this attribute because the token is made available from the Coveo Search API.

    Once configured as above, the CoveoAnalytics component automatically logs events for actions made by users in all the search page elements (search box, facets, search results…).

    You can also set the attributes with JavaScript when you initialize the search page. In this case, you still need a <div class="CoveoAnalytics"\> in the HTML, but attributes must be set only in one place, in the JavaScript or in the HTML markup.

    You could code a function to set a Username variable and a LoggedUser flag to dynamically set the user and anonymous attributes. The Username variable would contain the username of the authenticated user performing the search and the LoggedUser flag would be set to false when the user is anonymous.

     $('#search').coveo('init',{
       Analytics: {
         user : Username,
         endpoint : "http://mysearchserver/rest/analytics/",
         searchHub : "Main Search Page",
         anonymous : LoggedUser
       },
       ...
    
  4. Test the configuration:

    1. In the search interface in which you configured the CoveoAnalytics component, perform some search actions with one or more users.

    2. In your browser console, validate that requests are sent and return HTTP 200 success codes.

      When the GET request returns an Invalid origin for cross-domain request error, you can resolve the error using one of the three following solutions:

      • Host your Coveo JavaScript Search page at the same address as your proxy.

      • Configure the Cross Origin Resource Sharing (CORS) headers (request-response) of your search page host to allow cross-origin requests [see HTTP access control (CORS)].

      • Set the allowedDomains parameter in the config.yml file located in the Coveo Search API folder (C:\Program Files\Coveo Search API n), respecting the following format:

          http:
           port: [PORT_NUMBER]
           allowedDomains:
             - "*.ROOT_DOMAIN"
             - "localhost"
             - "[REST_API_SERVER_NAME]"
             - "https://[REST_API_SERVER]:[port]"
        
          http:
           port: 9090
           allowedDomains:
             - "*.companyxyz.com"
             - "localhost"
             - "coveoprod"
             - "https://coveoprod.companyxyz.com:9090"
        
    3. If not already done, log in to your Coveo Organization, with a user name that has an Administrator, Analyst Viewer, or Analyst Manager role.

    4. Access a usage analytics page such as the Summary Dashboard (see Reviewing the Search Usage Trends From the Summary Dashboard).

    5. Validate that the search events you performed appear in the analytics page.

      There is a delay of up to 15 minutes between the moment a search event is performed and the time the event appears in the Admin Console analytics pages. The analytics transactions are processed at least at a 15-minute interval, or faster whenever a sufficient number of events to process accumulate. The delay therefore decreases as the rate of search events increases.