Applicable Hawksearch Versions: Hawksearch v2.0L to 4.0L

Applicable Integration types: JavaScript Integration and Proxy/Hybrid Integration

In order to populate data in the Hawksearch Reports, and to leverage Personalized Search, it is CRITICAL to implement Tracking Integration. The Hawksearch Recommendation service also requires tracking events from a user on your website.

This document describes the steps to install client side tracking on your website to send relevant data to the Recommendation engine. This needs the JavaScript file provided by Hawksearch for your site hawksearch.js.

- 1.1 Tracking Domains
- 1.2 Prerequisite
2 User Event Based Tracking
- 2.1 Track Method & Context Property
- 2.2 Track Method:
- 2.3 Context Property:
- 2.4 Step 1: ‘pageload’ event
- 2.5 Step 2: ‘add2cart’ event
- 2.6 Step 3: ‘add2cartmultiple’ event
- 2.7 Step 4: ‘sale’ event
- 2.8 Step 5: ‘rate’ tracking event
- 2.9 Step 6: ‘click’ tracking event
- 2.10 Step 7: Tracking Member Logins (if applicable)
- 2.11 Search Event for full API Implementations
- 2.12 How to Test Tracking

Tracking Domains

Hawksearch has three environments available: Development, Staging/Test and a load-balanced Production. When performing integration, each engine can be accessed by using these domains:

1. Development Environment

When including the scripts below, please use the appropriate domains for the development environment.

Hawk URL
http://dev.hawksearch.net/

Tracking URL
http://tracking-dev.hawksearch.net/

Recommendations URL
http://recs-dev.hawksearch.net/

2. Staging/Test Environment.

When including the scripts below, please use the appropriate domains for the test environment.

Engine Reference URL
http://test.hawksearch.net/

Tracking URL
http://tracking-test.hawksearch.net/

Recommendations URL
http://recs-test.hawksearch.net/

3. Production Environment

When including the scripts below, please use the following domain for the production/live environment.

Engine Reference URL
http://yourenginename.hawksearch.com/
This will be provided at time of launch.

Tracking URL
http://tracking-na.hawksearch.com/

Recommendations URL
http://recs-na.hawksearch.com/

Prerequisite

The Hawksearch object must be initialized and the Tracking URL must be set in the <head> tag:

    <script type="text/javascript">
        //<![CDATA[
        (function (HawkSearch, undefined) {
            HawkSearch.BaseUrl = 'YOUR HAWKSEARCH ENDPOINT';
            HawkSearch.TrackingUrl = 'HAWKSEARCH TRACKING URL';
            HawkSearch.RecommenderUrl = 'HAWKSEARCH RECOMMENDER URL';
            HawkSearch.ClientGuid = 'YOUR TRACKING GUID';
            if ("https:" == document.location.protocol) {
                HawkSearch.BaseUrl = HawkSearch.BaseUrl.replace("http://", "https://");
            }
        }(window.HawkSearch = window.HawkSearch || {}));
        //]]>
    </script>

Example link: view-source:https://demo.hawksearch.com/ (if inaccessible, please visit https://demo.hawksearch.com, then view source)

This is an example from demo website, please use the values given by your Hawksearch point of contact

User Event Based Tracking

Set the Hawksearch.Context variable as applicable.

Corresponding to user activity such as search, click, add to cart, buy, etc., initiate Hawksearch.Tracking.Track event call.

Track Method & Context Property

Track Method:

Hawksearch provides a convenient and consistent way to pass tracking events to your Recommendation engine. The HawkSearch.Tracking.track is a JavaScript method that accepts two parameters. The first parameter is the name of the event you are trying to call. The second parameter will be the arguments to pass for that specific event.

HawkSearch.Tracking.track(eventName, args);

This method will be called for every tracking event that will be passed to the Recommendation engine.

Context Property:

In certain scenarios, additional details are needed to add more context around the item. These details are added on the page using the dictionary object called HawkSearch.Context. The object currently supports the following methods and properties:

add(key,value) – this method will add a property with name: “key” and value: “value”
remove(key) – this method will remove a property for a particular key
clear() – this method will clear all values from the context
keyValuePairs() – this method will return all objects from the context
HawkSearch.Context[key] – indexer will return value for a particular key

All values stored in Context object need to be initialized before any tracking method is called (i.e. writePageLoad)

HawkSearch.Context.Custom is another dictionary that is used to trigger Visitor Targets and other scenarios within Recommendations. It contains the same methods and properties as the context object and is used to store custom values for retrieving visitor targets and other custom values.

Example:

To trigger the visitor target “VIP” we can pass the following in the custom dictionary

HawkSearch.Context.Custom.add('vip','true');

Step 1: ‘pageload’ event

To track specific pages customers are loading, you need to track the page load event using the JavaScript call listed below. Here is an example of enabling pageload tracking.

Note that the track function is encapsulated within the customevent function (lines 3 and 5). HawkSearch exposes a function to ensure that the pageload event is tracked even if hawksearch javascript is loaded last.

The second parameter for the pageload call above expects the pageType argument. The table below specifies the values to use for specific page types supported by Hawksearch.

Page Type	Page Type

Page Type	Page Type
Item detail page (i.e. PDP)	"item"
Landing Page	"landing"
Shopping Cart Page	"cart"
Order Confirmation Page	"order"
All other Page Types	"custom"

Providing additional context for the Item Detail Page

In order to pass a uniqueid to our tracking engine for the item detail page, the following code is required:

uniqueId: Represents the unique identifier of a product. This should correspond to the value of the field set up as the primary key in the fields section of Hawksearch dashboard.

By passing the uniqueId in the context, the Hawksearch Recommendation engine will allow you to use the product’s attributes in the Recommendations tool.

Step 2: ‘add2cart’ event

In order to track an “add to cart” event, please call following function:

uniqueId: Represents the unique identifier of a product. This should correspond to the value of the field set up as the primary key in the fields section of Hawksearch dashboard.

price: represents a single item price

quantity: is the number of items being added to the cart

currency: is actual currency in ISO format

Step 3: ‘add2cartmultiple’ event

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

uniqueId: Represents the unique identifier of a product. This should correspond to the value of the field set up as the primary key in the fields section of Hawksearch dashboard.

price: represents a single item price

quantity: is the number of items being added to the cart

currency: is actual currency in ISO format

Step 4: ‘sale’ event

In order to track sale events, please add the following function call to the order confirmation page:

orderNo: is an alphanumeric value representing the order number

total: is the actual order total amount

subTotal: is order the sub total

tax: is a value of tax

currency: is actual currency in ISO format

itemList: is an array of objects with the following properties:

Property Name	Property Description

Property Name	Property Description
uniqueid	Unique item identifier. In many cases the uniqueid is different than SKU.
itemPrice	Price of an individual item
quantity	Number of items added to cart

Shopping Cart / Order Confirmation - Multiple Items

The Shopping Cart Page and Order Confirmation Page require a list format of unique identifiers for items that are in the cart at that time. In order to pass the list to the context, please use the key “uniqueidlist”. The value for the key should contain a comma separated string of uniqueids.

Step 5: ‘rate’ tracking event

Hawksearch can provide personalized recommendations to users who rated items on the website. In order to send ‘rate’ event, please call the method below at the time when the rating is submitted:

uniqueId: unique identifier of an item. In many cases the uniqueId is different than SKU.

value: represents a user’s rating for an item. The decimal value must be between 1 and 5.

Step 6: ‘click’ tracking event

Click Tracking may have been implemented during your Hawksearch implementation. If click tracking was not implemented, please add this onclick event to your item links.

Sample Code:

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.

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

Parameter 4: this is the uniqueId

Parameter 5: is always 0 (zero)

Step 7: 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.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

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.

Search Event for full API Implementations

By default Hawksearch JavaScript tracks search events as a user performs a search. In most cases no additional customizations are needed.

However, if you are using the full API implementation, on the Search Results page when the page is loaded you will need to add the following JavaScript.

TrackingId: The ‘TrackingId’ object that is passed in this function is returned in the Hawksearch response. If your page makes AJAX requests to handle facet selection, pagination or sort by request, the function above will also need to be called when the AJAX call has been completed.

How to Test Tracking

Please refer to How to Test Tracking?

Hawksearch Knowledge Base

Event Tracking Code

Tracking Domains

Prerequisite

User Event Based Tracking

Track Method & Context Property

Track Method:

Context Property:

Step 1: ‘pageload’ event

Step 2: ‘add2cart’ event

Step 3: ‘add2cartmultiple’ event

Step 4: ‘sale’ event

Step 5: ‘rate’ tracking event

Step 6: ‘click’ tracking event

Step 7: Tracking Member Logins (if applicable)

Search Event for full API Implementations

How to Test Tracking