📘

Note

Applicable Hawksearch Versions: All

Applicable Integration types: Hawksearch V4.0 API and API - front end integration

Overview

The event tracking API is used to support critical features in HawkSearch, for example:

• Reports
• Recommendations
• AI Multiplier

Tracking Process Overview

Domains

HawkSearch has three environments available: Development, Test and a load-balanced Production. When using the search API methods in this document, the following domains can be used to access each environment after your engine has been set-up in that environment.

🚧

Before You Begin

Please ensure that your client-specific endpoints are configured before implementing any API integrations. Please refer to this article to learn more about client-specific endpoints and reach out to our CSD team for any questions.

Development

client-specific URL: https://enginename.dev.tracking-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at dev.hawksearch.net.

Test

client-specific URL: https://enginename.test.dashboard-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at test.hawksearch.net.

Production

client-specific URL: https://enginename.tracking-na.hawksearch.com

Configurations for an engine in this location are maintained in the HawkSearch Workbench at dashboard-na.hawksearch.com.

Tracking API Components

🚧

Important

TrackingId is unique to every search request and required in tracking requests.

TrackingId

Since Search and Tracking are separate requests, and based on HTTP which is stateless inherently, there is a need to establish a relationship with the search request and a corresponding tracking request. This can be achieved by an identifier unique to the pair of search and tracking requests.

For every search request made to HawkSearch's Search API, along with the search results, merchandising section, etc., HawkSearch also gives back a unique identifier in the response. This identifier should be sent back through tracking requests which corresponds to the search made.

{  
...  
"TrackingId" : "0d6a30c0-5a6e-4995-8802-7d7096b7fb86",  
...  
}

This TrackingId needs to be used in sending the tracking requests back to HawkSearch's tracking service so that HawkSearch can establish the connectivity between the search and tracking requests.

Please note to include this dynamic id obtained from HawkSearch's response, into the tracking requests.

Using a TrackingId from an old search response or a random guid may not be recorded in the reports on HawkSearch workbench.

This is different from VisitId, VisitorId and the TrackingGuid attributes.

How to track requests

The steps to correctly track a Search event is as below, please refer to the specific event details in the remainder of this article for more examples.

Identifiers and their scope

All of these IDs need to be generated and sent to HawkSearch, since API integration typically does not require/use HawkSearch provided Javascript code:

VisitorId - this is the Guid to be set once per user. We recommend this to be stored in a browser cookie so that this same id is used when the user closes and reopens the browser and visits your website. Typically, once the vlaue of this cookie is set, it does not change. This is set to not expire or expire after a long term - like a year. HawkSearch uses this to ensure tracking events correspond to a given user and help recommend user-specific products through recommendation widgets.

Note - that VisitorId does not map to a registered user on your website so the same registered user opening your website in different browsers or in incognito mode will have different visitor id's. To ensure that HawkSearch system knows all these are the same user, please use our identify API in conjunction with the Ids explained later (Tracking Member Logins) in this article.

VisitId - this is the Guid set for every visit or “_user _session” of a logged in/guest user. This corresponds to the user opening the website and performing search, click, add to cart and any other operation. This gives our reports generator the information about the user’s activity on his/her certain visit to the website. This is scoped only until the browser is open. If the browser is closed and a fresh new browser window is opened, then this value needs to be set newly.

QueryId - is a unique id per “_keyword _session” - a session limited only to the specific search term. If the user searches for a keyword and continues to make facet selections, change the sort order and paging etc, all will fall under the same QueryId. QueryId changes when search term changes.

Notes:

1. Scope of User Id (identify api) > Scope of VisitorId > Scope of VisitId > Scope of QueryId
2. Note: TypeId is 1 for “Regular Searches” i.e., when a new search is performed. It is 2 for “Refined Search” - facet filtering, sorting, paging selection changes for the same keyword until the user searches for something else.

Code samples for Cookie and GUIDs for TrackingId, VisitorId and VisitId

If you are leveraging a HawkSearch SDK or Rapid UI, then those solutions include the creation of the first party cookie and correct VisitorId and includes functions to generate the correct VisitId. If you are building a solution using the HawkSearch API only, you can generate this information as you like. We have included code samples if interested.

VisitorId, VisitId and TrackingId helper

/*

    Local and Session Storage based Tracking API helper
    - this helper class will assist in generating and storing GUID values for Visit and Visitor Ids
    - this helper class will not automatically set the Query Id returned from the Search API
    - Query Id is a GUID provided in the Search API response whenever someone performs a search. This GUID should be persistent until another search is performed

*/

class HawkSearchTracking {

    #hawksearch_query_id_name;
    #hawksearch_visit_id_name;
    #hawksearch_visitor_id_name;

    constructor(visit_id_name, visitor_id_name) {

        this.#hawksearch_query_id_name = 'HawkSearchQueryId'; // Query Id Storage Name
        this.#hawksearch_visit_id_name = visit_id_name ?? 'HawkSearchVisitId'; // Visit Id Storage Name
        this.#hawksearch_visitor_id_name = visitor_id_name ?? 'HawkSearchVisitorId'; // Visitor Id Storage Name

    }

    // Clear Visit Id - Call this function after an order has been placed
    clearHawksearchVisitId() {
        sessionStorage.removeItem(this.#hawksearch_visit_id_name);
    };

    // Retrieve HawkSearch Query Id
    getHawkSearchQueryId() {
        return localStorage.getItem(this.#hawksearch_query_id_name);
    }

    // Retrieve HawkSearch Visit Id
    getHawksearchVisitId() {
        let visit_id = sessionStorage.getItem(this.#hawksearch_visit_id_name);
        if (!visit_id) {
            visit_id = this.#createHawksearchUUID();
        }
        sessionStorage.setItem(this.#hawksearch_visit_id_name, visit_id);
        return visit_id;
    };

    // Retrieve HawkSearch Visitor Id
    getHawksearchVisitorId () {
        let visitor_id = localStorage.getItem(this.#hawksearch_visitor_id_name);
        if (!visitor_id) {
            visitor_id = this.#createHawksearchUUID();
        }
        localStorage.setItem(this.#hawksearch_visitor_id_name, visitor_id);
        return visitor_id;
    };

    // Set HawkSearch Query Id
    setHawkSearchQueryId(value) {
        localStorage.setItem(this.#hawksearch_query_id_name, value);
    }

    // Helper functions
    #createHawksearchUUID() {
        // Public Domain/MIT - RFC4122 v4 compliant
        let d = new Date().getTime();
        let d2 = ((typeof performance !== 'undefined') && performance.now && (performance.now()*1000)) || 0;
        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
            let r = Math.random() * 16;
            if(d > 0){
                r = (d + r)%16 | 0;
                d = Math.floor(d/16);
            } else {
                r = (d2 + r)%16 | 0;
                d2 = Math.floor(d2/16);
            }
            return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
        });
    }

}

Cookie helper

/*

    Cookie based HawkSearch Tracking API helper
    - this helper class will assist in generating and storing GUID values for Visit and Visitor Ids
    - this helper class will not automatically set the Query Id returned from the Search API
    - Query Id is a GUID provided in the Search API response whenever someone performs a search. This GUID should be persistent until another search is performed

*/

class HawkSearchTracking {

    #hawksearch_query_id_name;
    #hawksearch_visit_id_name;
    #hawksearch_visitor_id_name;

    constructor(visit_id_name, visitor_id_name) {

        this.#hawksearch_query_id_name = 'HawkSearchQueryId'; // Query Id Storage Name
        this.#hawksearch_visit_id_name = visit_id_name ?? 'HawkSearchVisitId'; // Visit Id Storage Name
        this.#hawksearch_visitor_id_name = visitor_id_name ?? 'HawkSearchVisitorId'; // Visitor Id Storage Name
    
    }

    // Clear Visit Id - Call this function after an order has been placed
    clearHawksearchVisitId() {
        this.#setHawksearchCookie(this.#hawksearch_visit_id_name, "", 'Thu, 01 Jan 1970 00:00:01 GMT');
    };

    // Retrieve HawkSearch Query Id
    getHawkSearchQueryId() {
        return this.#getHawksearchCookie(this.#hawksearch_query_id_name);
    }

    // Retrieve HawkSearch Visit Id
    getHawksearchVisitId() {
        let visit_id = this.#getHawksearchCookie(this.#hawksearch_visit_id_name);
        if (!visit_id) {
            visit_id = this.#createHawksearchUUID();
        }
        this.#setHawksearchCookie(this.#hawksearch_visit_id_name, visit_id, this.#getHawksearchVisitExpiry());
        return visit_id;
    };

    // Retrieve HawkSearch Visitor Id
    getHawksearchVisitorId() {
        let visitor_id = this.#getHawksearchCookie(this.#hawksearch_visitor_id_name);
        if (!visitor_id) {
            visitor_id = this.#createHawksearchUUID();
        }
        this.#setHawksearchCookie(this.#hawksearch_visitor_id_name, visitor_id, this.#getHawksearchVisitorExpiry());
        return visitor_id;
    };

    // Set HawkSearch Query Id
    setHawkSearchQueryId(value) {
        this.#setHawksearchCookie(this.#hawksearch_query_id_name, value);
    }

    // Helper functions
    #createHawksearchUUID() {
        // Public Domain/MIT - RFC4122 v4 compliant
        let d = new Date().getTime();
        let d2 = ((typeof performance !== 'undefined') && performance.now && (performance.now()*1000)) || 0;
        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
            let r = Math.random() * 16;
            if(d > 0){
                r = (d + r)%16 | 0;
                d = Math.floor(d/16);
            } else {
                r = (d2 + r)%16 | 0;
                d2 = Math.floor(d2/16);
            }
            return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
        });
    }

    #getHawksearchCookie(name) {
        let nameEQ = name + "=";
        let ca = document.cookie.split(';');
        for (let i = 0; i < ca.length; i++) {
            let c = ca[i];
            while (c.charAt(0) == ' ') c = c.substring(1, c.length);
            if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
        }
        return null;
    };

    #getHawksearchVisitExpiry() {
        var d = new Date();
        d.setTime(d.getTime() + (4 * 60 * 60 * 1000)); // 4 hours
        return d.toGMTString();
    };

    #getHawksearchVisitorExpiry() {
        var d = new Date();
        d.setTime(d.getTime() + (360 * 24 * 60 * 60 * 1000)); // 1 year
        return d.toGMTString();
    };

    #setHawksearchCookie(name, value, expiry) {
        let expires;
        if (expiry) {
            expires = "; expires=" + expiry;
        } else {
            expires = "";
        }
        document.cookie = name + "=" + value + expires + "; path=/";
    };

}

Tracking API Methods

POST

The POST method is used to pass tracking events to your recommendation engine. Hawk Search allows for tracking many different types of events (listed below) using only one generic method common for all types of events.

Response Code

Structure

Example

Go to Tracking Event Types section to see examples.

{

   "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",
   "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
   "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",
   "EventType":"PageLoad",
   "EventData": "",
   ...
}

Tracking Event Types

HawkSearch API allows you to collect information about different types of events in a system. Depending on the type, the API expects related data about the occurring event.

EventType property represents following values (both EventType Value and EventyType Code can be used to define field values)

EventType Values

This section describes different types of events and their representing model.

Page Load Event

Events representation for tracking specific pages customers are loading.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "PageTypeId":"1",  
      "Qs":"varA=1&varB=2",  
      "RequestPath":"/details/sku123",  
      "UniqueId":"sku123",  
      "ViewportHeight":1080,  
      "ViewportWidth":1920
   
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"PageLoad",  
      "EventData":... // Serialized and Base64 Encoded PageLoad Event Data Object
   
   }
   

3. Example of CustomDictionary

   1. Event Data Object

      {
         "PageTypeId":"1",
         "Qs":"varA=1&varB=2",
         "RequestPath":"/details/sku123",
         "UniqueId":"sku123",
         "ViewportHeight":1080,
         "ViewportWidth":1920
      
      }
      

   2. Complete Request Body

      {
      
         "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",
         "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
         "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",
         "EventType":"PageLoad",
         "EventData":... // Serialized and Base64 Encoded PageLoad Event Data Object
      
         "CustomDictionary": {“custom“:”search”}
      
      }
      

Search Event

To track search events in web application you should call tracking API using this type of event.

Event Data Model

Parameters

Example

1. Event Data Object

   {
   
      "Qs":"",
   
      "TypeId":"1",  
      "QueryId":"26a0a9f9-f22d-45c2-bee7-35832a2171e3",  
      "RemoteAddr":"127.0.0.1",  
      "RequestPath":"/",  
      "TrackingId":"6d017a40-54ba-4508-9272-fc14f4616661",  
      "ViewportHeight":1080,  
      "ViewportWidth":1920
   
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"Search",  
      "EventData":..... // Serialized and Base64 Encoded Search Event Data Object
      "CustomDictionary": {
         "custom": "VisitorTarget1"
      }
   }
   

Click Event

To track click events in web application you should call tracking API using this type of event.

This click event is applicable for user clicks made on the search results on search page or HawkSearch landing page.

For user clicks on Banners, Recommendation widget items and Autocomplete sections, please refer to appropriate events.

Event Data Model

Parameters

📘

Note

All of the properties that name starts with Element* should pass corresponding information about clicked element

Example

1. Event Data Object

   {
   
      "Mlt":false,  
      "TrackingId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "Url":"/details/sku123.html",  
      "UniqueId":"sku123",
      "ElementNo": 17
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"Click",  
      "EventData":..... // Serialized and Base64 Encoded Click Event Data Object
   
   }
   

Add To Cart Event

This type of tracking should be populated by events of adding items to the cart.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "UniqueId":"123456789",  
      "Price":15.97,  
      "Quantity":1,  
      "Currency":"USD"
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"Add2Cart",  
      "EventData": ... // Serialized and Base64 Encoded Add To Cart Event Data Object
   }
   

Add To Cart Multiple Event

In some unique instances, the user is able to add many items to the cart with one click.
This method will allow you to call API tracking with single event with multiple items.

Event Data Model

Parameters

Item Info Model

Parameters

Examples

1. Event Data Object

   {
   
      "ItemsList":[
   
         {
   
            "uniqueId":"123456789",
            "price":15.97,
            "quantity":1,
            "currency":"USD"
   
   },
         {
   
            "uniqueId":"54234",
            "price":10.97,
            "quantity":2,
            "currency":"USD"
   
         }
   
     ]
   
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",
      "EventType":"Add2CartMultiple",
      "EventData":..... // Serialized and Base64 Encoded Add To Cart Multiple Event Data Object
   
   }
   

Sale Event

In order to track sales events, call the tracking API using the following event eg. on your confirmation page.

Event Data Model

Parameters

Sale Item Info Model

Parameters

Example

1. Event Data Object

   {
   
      "SubTotal":100.33,  
      "Tax":23.3,  
      "Total":123.3,  
      "OrderNo":"A0000378",  
      "Currency":"USD",  
      "ItemList":[  
         {  
            "uniqueId":"123456789",  
            "ItemPrice":15.97,  
            "quantity":1  
         }  
      ]
   
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"Sale",  
      "EventData":..... // Serialized and Base64 Encoded Sale Event Data Object
   
   }
   

Rate Event

HawkSearch can provide personalized recommendations to users who rated items on the website. In order to send ‘rate’ event, please call the Tracking API using following event type.

Event Data Model

Parameters

Examples

1. Event Data Object

   {
   
      "UniqueId":"Item_1232",  
      "Value":3.00
   
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"Rate",  
      "EventData":..... // Serialized and Base64 Encoded Sale RateData Object
   
   }
   

Banner Impression Event

To track banner impressions in web application you should call tracking API using this type of event, each time users display banner.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "BannerId":1250,  
      "CampaignId":12,  
      "TrackingId":"6d017a40-54ba-4508-9272-fc14f4616661",
   }
   

2. Complete Request Body

{

   "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
   "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
   "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
   "EventType":"BannerImpression",  
   "EventData":..... // Serialized and Base64 Encoded Banner Impression Event Data Object

}

Banner Click Event

To track banner clicks in web application you should call tracking API using this type of event.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "BannerId":1250,  
      "CampaignId":12,  
      "TrackingId":"6d017a40-54ba-4508-9272-fc14f4616661",  
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"BannerClick",  
      "EventData":..... // Serialized and Base64 Encoded Banner Click Event Data Object  
   }
   

Banner Impression Bulk Event

To track a list of banner impressions in web application you should call tracking API using this type of event, each time users display a single or multiple banners.

Event Data Model

Parameters

Banner Info Model

Parameters

Examples

1. Event Data Object

   {  
      "TrackingId":"6d017a40-54ba-4508-9272-fc14f4616661",  
      "Banners": [  
         {  
            "BannerId":1250,  
            "CampaignId":12  
         },  
         {  
            "BannerId":1257,  
            "CampaignId":14  
         }  
      ]  
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"BannerImpressionBulk",  
      "EventData":..... // Serialized and Base64 Encoded Banner Impression Event Data Object
   
   }
   

Recommendation Click Event

To track recommendation widget click action you should call tracking API using following type of event, each time user clicks on recommendation widget.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "ItemIndex": 1,  
      "RequestId":'',  
      "UniqueId":"6d017a40-54ba-4508-9272-fc14f4616661",
   
      "WidgetGuid":'',
   
   }
   

2. Complete Request Body

   {
   
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"RecommendationClick",  
      "EventData":..... // Serialized and Base64 Encoded Banner Impression Event Data Object
   
   }
   

Autocomplete Click Event

Use this event to track user clicks on different type of autocomplete results eg. Products, Categories, Content, Popular Searches.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "Keyword": "jacket",  
      "Name":"Man » Jacket",  
      "SuggestType":2,  
      "Url":'<https://dev.hawksearch.net/elasticdemo?department_nest=Jackets_6'>,  
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"AutocompleteClick",  
      "EventData":..... // Serialized and Base64 Encoded Autocomplete Event Data Object
   
   }
   

Autocomplete Trending Items Click Event

Use this event to track user clicks on autocomplete trending items results. When autocomplete returns products and IsRecommended = ture then Autocomplete Trending Items click event should be used.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "ItemId": "Item_146566",  
      "Url":'<https://preview-dev.hawksearch.net/elasticdemo/details?itemid=Item_146566>'  
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"AutoCompleteTrendingItemsClick",  
      "EventData":..... // Serialized and Base64 Encoded Autocomplete Event Data Object
   
   }
   

Autocomplete Trending Category Click Event

Use this event to track user clicks on autocomplete trending category results. When autocomplete returns category and IsRecommended = ture then Autocomplete Trending Category click event should be used.

Event Data Model

Parameters

Examples

1. Event Data Object

   {  
      "Field": "jacket",  
      "Value":"Camp & Hike » Tents & Shelters",  
      "Url":'<https://preview-dev.hawksearch.net/elasticdemo?department_nest=Tents--Shelters&prv=1>"  
   }
   

2. Complete Request Body

   {
   
      "ClientGuid":"dfb51ea2ea1a42e4a53d4e67f7f6847b",  
      "VisitId":"2F87556F-AA2F-438E-A52C-AFF4B7E10EB5",  
      "VisitorId":"7e3efd4c-ca6b-46fe-b576-1a00ce8d1d43",  
      "EventType":"AutoCompleteTrendingCategoryClick",  
      "EventData":..... // Serialized and Base64 Encoded Autocomplete Event Data Object
   
   }
   

Tracking Member Logins (if applicable)

Bind anonymous users to registered users on your web site

By default, each individual user is tracked via “visit_id” and “visitor_id” cookies. These cookies are used to track the activity of the user. If you have a member sign-up on your site, you can attach the member login to the user’s activity. In order to provide a relationship between the logged-in member and the user’s cookie values, please make an API call to the following method:

https://tracking-dev.hawksearch.net/api/identify

In order to use the API you will need to pass the API key in the header of your request to authenticate your request. To lookup the API key for your account please look in the HawkSearch workbench under Admin >> Account Info.

Sample request

PUT /api/identify HTTP/1.1  
Host: tracking-dev.hawksearch.net  
X-HawkSearch-ApiKey: 535bd002-1fc5-41a1-b264-1cd29dbd0e65  
Content-Type: application/json; charset=utf-8  
Cache-Control: no-cache

{"userId":311043,"visitId":"b014cb04-6c73-4e84-8cba-a6858bb1f785","visitorId":"e98f3943"}

userId: the Unique Identifier of the logged in user that is stored in your database (i.e. UserAccountId or MemberId, etc.)

vistitId: this is taken from the visit_id cookie

vistitorId: this is take from the visitor_id cookie

This request should be a server-side request.

Common Action Flows

Search Result Click Flow

A user visits an e-commerce site selling electronics. They load the homepage (#1), search for "wireless headphones" (#2), click on a pair of headphones (#3) from the search results, view the product details page (#4), add the headphones to their cart (#5), and complete the purchase (#6).

1. Page load event (other page type)
2. Search event
3. Click event (item clicked in search results)
4. Page load event (product detail page)
5. Add to cart event
6. Sale event

Autocomplete Click Flow

A user visits an online bookstore homepage (#1). As they start typing "sci-fi nov" in the search bar, they see "science fiction novel" in the autocomplete suggestions. They click on this suggestion (#2), are taken to a page to view its details (#3), add it to their cart (#4), and complete the purchase (#5).

1. Page load event (other page type)
2. Autocomplete click event (item selected from autocomplete suggestion)
3. Page load event (product detail page)
4. Add to cart event
5. Sale event

Recommendation Click Flow

A user is shopping on a fashion website and viewing a landing page (#1). On this page, they see a "Frequently Bought Together" recommendation widget (#2) showing accessories. They click on a recommended necklace (#3), got redirect to its product detail page (#4), decide to add it to their cart (#5), and then complete the purchase the item (#6).

1. Page load event (landing page)
2. Recommendation impression event (this is tracked on server side, no need to send request)
3. Recommendation click event (item clicked in recommendation widget)
4. Page load event (product detail page)
5. Add to cart event
6. Sale event

FAQs

Where do I find the ClientGuid (Tracking Key)?

When logged into the HawkSearch Workbench, click on the account icon found on the right side of the top bar, next to the logout icon. When your account page loads, look at the bottom where the Tracking Key/Guid is displayed.

How to Test Tracking?

Presence of events on Tracking Preview page

All tracking events can be viewed and tested by logging into the HawkSearch workbench and navigating to

Admin >> Tracking Events Preview

<https://dev.hawksearch.net/admin/trackingPreview.aspx>

Perform a search from the preview page and refresh the tracking preview page

It must display the search event corresponding to the keyword search you just made.

Similarly test for presence of the Event Click and other events on the tracking preview page.

Please ensure all the tracking events are coming through. Some important events are:

• Event Page Load
• Search
• Event Click
• Add To Cart
• Event Sale

Combinations of tracking events confirm to every report. So if a report is not displaying data or showing incorrect data, please check to ensure your website is sending the tracking events to your HawkSearch engine.

📘

Note

The event Request Tracking is logged by HawkSearch internally for summarization purposes.

Presence of UniqueId

TIP: clicking the eyeball icon will pop-up a window with details of the request.

To test every event, you can use the search bar on the Tracking Preview to filter the event type.

To test every event, you can use the search bar on the Tracking Preview to filter the event type.

The most important thing to check is that the UniqueId is being passed in the correct manner. This MUST match what is set to the primary key in the HawkSearch workbench.

Note that, in the tracking requests, the name of the attribute remains “UniqueId” however its value will need to be that associated with the primary key. So:

• If “SKU” is set as primary key, then HawkSearch expects that field in the tracking requests, example:
  if your item’s SKU is ABC-1

{
...
"UniqueId" : "ABC-1",
...
}

• If “Id” is set as primary key, then HawkSearch expects that field in the tracking requests, example:
  if your item’s Id is 10001

{
...
"UniqueId" : "10001",
...
}

The primary key field is defined under the Field Configuration settings.

🚧

Important

If you have a parent-child setup in your HawkSearch index, ensure that you send the correct id according to your setup.

Examples:

If you have all child items' attributes roll up into your parent so that you display only the parent item, then the uniqueid you need to send in tracking should be the parent id even if the item displayed is the child.

If you have all child items displayed in the search results, then send the child item’s id as the uniqueid to the tracking API.

For the latest version of Variant Logic with HawkSearch v4.0 API, sending the parent’s unique id helps generate correct reporting data and recommendations.

📘

Note

UniqueId may not be applicable to all events - for example, a search event may not need to have a uinique id associated with it however for a click event, HawkSearch must know which item was clicked upon.

HawkSearch Event - V1 Click Tracking

HawkSearch has three environments available: Development dev.hawksearch.net), Test – test.hawksearch.net and Production dashboard-na.hawksearch.com. When performing integration, each engine can be accessed by using these domains. For each of the three environments the value for 'url_value' would be different. Please confirm the URL values with the HawkSearch team during implementation.

One of the first steps to populate click tracking report, would be loading the JavaScript file provided by HawkSearch and to initialize the Hawk URLs on the listing page

<script type="text/javascript">
      //<![CDATA[
      (function (HawkSearch, undefined) {
                    HawkSearch.BaseUrl = url_value;
          HawkSearch.TrackingUrl = url_value;
          if ("https:" == document.location.protocol) {
              HawkSearch.BaseUrl = HawkSearch.BaseUrl.replace("http://", "https://");
              HawkSearch.TrackingUrl = HawkSearch.TrackingUrl.replace("http://", "https://");
          }
      }(window.HawkSearch = window.HawkSearch || {}));
      var hawkJSScriptDoc = document.createElement("script");
      hawkJSScriptDoc.async = true;

      hawkJSScriptDoc.src = HawkSearch.TrackingUrl + '/includes/hawksearch.js?v1.01';

      var hawkJSTag = document.getElementsByTagName('script')[0];
      hawkJSTag.parentNode.insertBefore(hawkJSScriptDoc, hawkJSTag);
      var hawkCSSScriptDoc = document.createElement("link");
      hawkCSSScriptDoc.setAttribute("rel", "stylesheet");
      hawkCSSScriptDoc.setAttribute("type", "text/css");
      hawkCSSScriptDoc.setAttribute("href", HawkSearch.TrackingUrl + '/includes/hawksearch.css');
      document.head.appendChild(hawkCSSScriptDoc);
      //]]>
</script>

If the listing page is completely formatted by HawkSearch then the following on click event would be added to the anchor elements for each of the items.

If the site is not using HTML formatted by HawkSearch, then you will require to add the following on click event on each of the item links for products on the listing page.

<a onclick="return HawkSearch.link(event,'61816065-4fa5-4bf2-9604-f76e664f9334',1,’123456789',0);">

Item Name

</a>

The parameters used in the above code snippet are

Parameter 1: passes the event to the function. For click tracking, this value is usually event.

Parameter 2: This is the TrackingId that is passed back in the search response from HawkSearch

61816065-4fa5-4bf2-9604-f76e664f9334

Parameter 3: this is the index of the item in the search results.

Parameter 4: this is the uniqueId of the item.(this may not necessarily be the product Id)

Parameter 5: is always 0 (zero)

Once the above mentioned tracking code has been added, you can test the click tracking event by

• Searching for a term
• Once items have been listed from the search open up the developer tools for the browser
• This can be done either by right clicking on the page and selecting inspect or clicking F12

Chrome

Firefox

• Once the developer tools has been opened up, click on the network tab to view the network requests/response

• Click on any of the products item links on which we have added the click tracking code mentioned previously in the document. On successful tracking the network tabs would show a request to link.aspx with a response status of 302 as shown below.

• If you are not able to see the link.aspx request under network tab make sure that the product listing doesn’t have multiple item links and if they do have multiple item links then the click tracking code is added to each of the links . For example it may happen that a page will have same item link url added on the page for the item image and the item name, then it is required that the click tracking code is added on both item image and item name.
• If the network tab does display the link.aspx request and the item is not redirecting to the product page please make sure there are no error messages on the browser console

Cookie Expiration Table