Events Tracking API Integration
- Lukasz Bargiel (Deactivated)
- Pawel Madurski
- Akanksha Shukla (Deactivated)
Applicable Hawksearch Versions: All
Applicable Integration types: Hawksearch V4.0 API and API - front end integration
Development
Configurations for an engine in this location are maintained in the Hawksearch Workbench at dev.hawksearch.net.
Test
Configurations for an engine in this location are maintained in the Hawksearch Workbench at test.hawksearch.net.
Production
Configurations for an engine in this location are maintained in the Hawksearch Workbench at dashboard-na.hawksearch.com.
Tracking ID
Important!
TrackingId is unique to every search request and required in tracking requests.
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 identifyAPI 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:
Scope of User Id (identify api) > Scope of VisitorId > Scope of VisitId > Scope of QueryId
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.
Identifier | Value Range | Generated By | Typical Persistence Location | Scope | Expiry (reset when) | Usage (sent to Hawk during) |
|---|---|---|---|---|---|---|
Query Id | Valid GUID | Website | Page Viewstate/Viewbag/temporary | Keyword | User searches for different keyword (search term) | Tracking API requests |
Visit Id | Valid GUID | Website | Browser Cookie | Browser specific tab/window | Opening a new browser tab/window | Search and Tracking API requests |
Visitor Id | Valid GUID | Website | Browser Cookie | Browser - all tabs and windows | Browser cache is cleared | Search and Tracking API requests |
UserId/MemberId/AccountId with | Alphanumeric - individual website specific | Website | Website’s backend database (Userid) and Hawksearch’s database (Mapping between website’s User id and Hawksearch’s visitor id & visit id) | Website level | Never | One time mapping request through Tracking API |
TrackingId | Valid GUID | Hawksearch | Page Viewstate/Viewbag/temporary | Keyword | User searches for different keyword (search term) | Sent by Hawksearch in search response, to be sent back by website to Hawksearch for the corresponding tracking API request (see Tracking Id section above) |
TypeId | 1 or 2 | Website | Page Viewstate/Viewbag/temporary | Keyword | Reset to 1 when - User searches for different keyword (search term) Change to 2 upon - faceting/pagination/sorting changes by the user for the same search result set (keyword hasnt changed yet and user is clickign on facets/sorting/etc.) | Tracking API requests |
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
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)
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
Search Event
To track search events in web application you should call tracking API using this type of event.
Event Data Model
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
Add To Cart Event
This type of tracking should be populated by events of adding items to the cart.
Event Data Model
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 singe event with multiple items.
Event Data Model
Item Info Model
Sale Event
In order to track sales events, call the tracking API using the following event eg. on your confirmation page.
Event Data Model
Sale Item Info Model
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
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
Banner Click Event
To track banner clicks in web application you should call tracking API using this type of event.
Event Data Model
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
Banner Info Model
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
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
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
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
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.
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.
