Rest API Based Event Tracking for Chatbots

This document describes the steps to be followed to integrate FirstHive Analytics into your application.

─

Prerequisite

• A site ID (idsite)  needs to be created for your APP in your FirstHive account to map the tracking to your account. Contact your FirstHive rep for the Site ID if not already provided.

Tracking HTTP API

To track page views, events, visits, you have to send an HTTP request (GET or POST) to FH Tracking HTTP API endpoint with the correct query parameters set.

Supported Query Parameters

This section lists the various query parameters that are supported by the Tracking API. The data for some of these fields will not be available in your app/software which is expected, but you should provide as much information as you can.

Required Parameters

Event Tracking info

• e_c — The event category. Must not be empty. The value should be as defined by FirstHive. Refer FH event structure section for the value to be passed.
• e_a — The event action. Must not be empty. The value should be as defined by FirstHive. Refer FH event structure section for the value to be passed.
• e_n — The event name. This is the name of the action/Intent. This can be custom defined.
• e_v — The event value. Must be a float or integer value (numeric), not a string. Pass value as 1.

Recommended Parameters

• url (recommended) — The full URL for the current action. E.g., page URL on which the action occurred.
• rand (recommended) — Meant to hold a random value that is generated before each request. Using it helps avoid the tracking request being cached by the browser or a proxy.
• ua — An override value for the User-Agent HTTP header field. The user agent is used to detect the operating system and browser used.
• lang — An override value for the Accept-Language HTTP header field. This value is used to detect the visitor’s country.
• dimension[1-15] — A custom dimension value. This can be used to pass attributes/values associated with an event.  Please refer to the last section for an example.
• send_image — If set to 0 (send_image=0) FH will respond with a HTTP 204 response code instead of a GIF image. This improves performance and can fix errors if images are not allowed to be obtained directly (e.g., Chrome Apps).
• _idts — The UNIX timestamp of this visitor’s first visit. This could be set to the date where the user first started using your software/app, or when he/she created an account. This parameter is used to populate the Goals > Days to Conversion report.

FH Event Structure for ChatBot

Below is the FH Event structure for capturing events for Chatbot:

Event Category: Chatbot 

Event Action: ChatIntent

Event Name: <Name of the Intent>

The category and action for the chatbot should be passed as defined above. The event name can be the name of the intent.

The parameter in which you will pass the above values are:

• e_c — The event category i.e., ChatBot
• e_a — The event action. ChatIntent
• e_n — The event name. (e.g., Get Account Statement, Get SIP Status, Add Bank Account etc.)
• e_v — The event value. Pass it as 1.

Dimensions: This is an optional parameter. It captures the attribute of the intent. FirstHive supports up to 10 dimensions per event.

Below is the breakup of dimensions:

The dimension[1-5] are reserved for below values. These values can be passed for post logged in chat interaction.

dimension1: <Email>

dimension2: <Mobile>

dimension3: <key param – e.g., unique account id>

dimension4: <key param>

dimension5: <key param>

dimension[6-10]: Can be used to pass other values relevant only for that event (e.g., product id, no. of product, color etc.)

For example: 

• dimension1=[email protected]
• dimension2=9123456789
• dimension3=233574
• dimension6=SKU23084
• dimension7=Red

Example Tracking Request

Here is an example of a real tracking request when anonymously tracking an event:

https://analytics.firsthive.com/piwik.php?e_c=ChatBot&e_a=ChatIntent&e_n=Review_Submitted&e_v=1&idsite=31&rec=1&url=https://xxx.com&_id=210f7b0501355461&_idts=1586238021&dimension1=[email protected]&dimension3=34524&dimension6=Delivered Account Statement&dimension7=Single Folio