Register stats programmatically

When using Doofinder for search, whether you are using our layers or not, you can programmatically register events like clicks or purchases / checkouts (or any goal achieved by your users) via our Javascript library.

Introduction

For this article we’ll assume that you already have a working search engine and some knowledge of HTML and Javascript.

What we want is to register clicks on links obtained as results of a search throught the Doofinder service.

The search is supposed to be done server to server by sending a form; your server will ask Doofinder and will create a response to be sent to the user’s browser.

Also, we want to register checkouts (a purchase, for instance) as the result of a search.

Working Example

To learn how to register clicks and checkouts we will use this HTML code:

<h1>Products</h1>

<!-- This is our search box -->
<div>
  Search: <input type="search" name="q" id="search" value="fitness">
</div>

<!-- Product links -->
<ul>
  <li>
    <a href="#" data-product-id="10001943">
      Slendertone Bottom Toning Pads
    </a>
  </li>
  <li>
    <a href="#" data-product-id="10004152">
      Weider Nutrition Protein 80 Plus - 2kg vanilla
    </a>
  </li>
  <li>
    <a href="#" data-product-id="10004178">
      Body Shaper Classic Pack - 24x35gr Banana and dark chocolate
    </a>
  </li>
  <li>
    <a href="#" data-product-id="10004219">
      Bruce Lee Signature Bag/Sparring Gloves size L
    </a>
  </li>
  <li>
    <a href="#" data-product-id="10002249">
      Oregon SE336M heart rate monitor
    </a>
  </li>
</ul>

<!-- Fake purchase button -->
<button type="button" id="confirm-purchase">Confirm Purchase</button>

This is how it looks like:

In the image:

The search box where we type the search terms.
The links that will be used to register clicks in stats.
The button that will be used to register the checkout event in stats.

Requisites

Doofinder Client Library

First of all you need the Doofinder Javascript Client library. It allows you to perform queries to Doofinder and receive results, and also send events to be computed in the Doofinder stats.

NOTICE: If you are using any of the Doofinder Layers (v7+) you can skip this section.

The library can be found here:

https://github.com/doofinder/js-doofinder

WARNING: Don’t link directly to the file hosted on Github. Github is not a hosting service and could block direct requests made to that file and your code would stop working. Instead, you can point to our CDNs either at jsdelivr or at cdnjs.

For this example we will use direct download from a CDN:

<script src="//cdn.jsdelivr.net/npm/doofinder@latest/dist/doofinder.min.js">
</script>

JQuery

To handle events we will use jQuery but you can use native Javascript if you want.

Add this to your HTML:

<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js">
</script>

Before typing any code, make sure you have the hashid that identifies you search engine and the search zone of your search engine (it will usually be eu1 or us1).

Also make sure that your search engine is allowed to receive requests from the domain you’re using. If you want to try first in your local machine you probably will want to authorize localhost in your search engine configuration. Just go to Search Engines, open your search engine and go to Configuration > Allowed Domains. Then add localhost and save.

The Session ID

The session id is a token used to anonymously identify a search session in stats.

When a user searches in the site you should register the session id. When the search results page is loaded you can execute:

if (!session.exists()) {
  // a session id is automatically generated
  stats.registerSession(session.get('session_id'));
}

When using our layers the session id lifecycle is managed automatically for you and you can get the session id from the layer itself:

var sessionId = dfClassicLayers[0].layer.session.get('session_id');

If you’re using the library directly you may want to manage the session yourself:

var session = new doofinder.session.Session(
  new doofinder.session.CookieSessionStore("mySessionCookie")
);
var sessionId = session.get('session_id');

NOTICE: Search sessions stored in a cookie expires in 1h by default.

If you prefer using a Javascript plain object to store the session you could use:

var session = new doofinder.session.Session(
  new doofinder.session.ObjectSessionStore()
);
var sessionId = session.get('session_id');

If you want a quick and dirty solution just to try some stuff you can just use:

var sessionId = doofinder.util.uniqueId.generate.browserHash();

Register Clicks

In this example we want to register clicks made on the links that we assume that are search results obtained from Doofinder and inserted into the HTML of your page somehow.

We will:

Instantiate a Doofinder client and stats objects.
Wait until the page is fully loaded and use a function to handle click events triggered on results links.
Inside that function we will put the code that notifies the event to Doofinder.

When using our layers, the instances already exist through the layers array (dfClassicLayers, dfFullscreenLayers, …). For instance:

var layer = dfClassicLayers[0].layer;
layer.client.search("something", function(err, response){
  // …
});
layer.stats.registerClick(sessionId, dfid, query);

NOTICE: When using stats in the layers, initialize custom behaviors in the loaded callback. There you can access the instances through the instance parameter. See more details on Callbacks at the Layer Options article.

<script type="text/javascript">
  var client = new doofinder.Client('97be6c1016163d7e9bceedb5d9bbc032', {
    zone: 'eu1'
  });
  var stats = new doofinder.Stats(client);
  var session = new doofinder.session.Session(new doofinder.session.CookieSessionStore('doofinder-sessid')
  );


  // Handle click events in product links (in this case in any link)
  // to register clicks in Doofinder. Notice that we're getting the
  // search query from a search box and specifying a datatype.
  // Make sure you use the right datatype according to your
  // feeds config.
  $('body').on('click', 'a[data-product-id]', function(e){
    stats.registerClick(
      session.get('session_id'),  // some id to identify the session
      $(this).data('product-id'), // the clicked item id
      'product',                  // datatype, assumed for this example
      $('#search').val()          // the query that triggered the result
    );
  });
</script>

And that’s all! If you feel confident we can continue with a more advanced example…

Register Checkouts

Checkouts are final actions performed by the user as a consequence of search. In a store it can be a purchase. In any other page could be following a certain link.

To compute checkouts Doofinder needs to (anonymously) identify a user by a session id. Our layers do it automatically but, when not using them, you’ll have to do it yourself. For more information check the previous section.

When a user loads the page we will check if a session id exists and, if not, we will create it and register the session in Doofinder.

To simulate a purchase we will use a fake purchase button. We will handle the click event and compute a checkout.

<script type="text/javascript">
  var client = new doofinder.Client('97be6c1016163d7e9bceedb5d9bbc032', {
    zone: 'eu1'
  });
  var stats = new doofinder.Stats(client);
  var session = new doofinder.session.Session(new doofinder.session.CookieSessionStore('doofinder-sessid')
  );

  jQuery(function($){
    if (!session.exists()) {
      stats.registerSession(session.get('session_id'));
    }

    // Handle the click event in a fake purchase button.
    $('#confirm-purchase').on('click', function(e){
      stats.registerCheckout(session.get('session_id'));
    });
  });
</script>