User Interactions Reporting

Introduction

The Twiggle Semantic API enhances search-engine recall and relevance, leveraging its deep understanding of both semantics and product structures to translate search queries and raw catalog data into structured representations. Its proprietary algorithms also analyze key user interactions (presentation of search results; product views; moving products to the shopping cart; and purchases).

This data feed serves a key function—each interaction trains the Twiggle Semantic API, so it can produce high-caliber results that are ever more refined. This unique, data-driven approach also renders the Twiggle Semantic API capable of generating valuable business insights in the form of analytics reports.

The Twiggle Analytics library follows user flows and captures and reports the key user interactions in real time. Built with performance and scale in mind, it is lightweight and asynchronous, cached and compressed.

This guide takes you step by step through the process of using the Twiggle Analytics library.

What is a User Interaction?

An interaction is any type of shopper action aimed at eliciting a response or action from the e-commerce site. The Twiggle Semantic API incorporates four types of interactions:

  • Search-request result - the shopper is presented with a page (e.g., a search-results page, a no-results page, category pages, redirects) in response to a search request;
  • Product view - the shopper is presented with a page that contains a specific product’s specifications, in response to any preceding request for such information, such as clicking on an item in the search-results page;
  • Add to cart - the user adds items to their shopping cart; and
  • Purchase - the user purchases items.

User interactions are reported by calling the tw function, with two arguments:

  • Interaction name - each of the four key interactions has a distinct name (search-req-result, product-view, add-to-cart, and purchase) that uniquely identifies it.
  • Properties object - information fields (some required, some optional) that are relevant to the specific interaction type. These are described in more detail below.

For example:

tw('interaction-name', { property: 'value', ... });

During initialization, the tw function is also called, and receives two arguments:

  • configure command.
  • Configuration object - this object contains important metadata that is later assigned to each interaction reported during the session. The metadata distinguishes the session and enables data slicing, grouping and aggregation. The configuration can be changed later in real time, by re-invoking the tw function, with those two arguments. This is described in more detail below.

For example:

tw('configure', { property: 'value', ... });

Implementation

Set Up


The Twiggle Analytics library doesn't require installing any standalone files; you simply add a JavaScript snippet to your layout template HTML code. This will asynchronously load the library into your pages, without blocking the loading of other elements.

The library loads in two stages:

  • The JavaScript snippet loads a bootstrap script that validates browser features support and initializes the library accordingly.

  • An iframe that communicates with the Twiggle Semantic API is then injected into the page. This is done to prevent the scripts from interfering with the site code.


The Javascript Snippet

Add the following snippet near the closing </body> tag and initialize the configuration object:

<!-- Twiggle Analytics -->
<script>
   (function(i,s,o,g,r,a,m){i['TwiggleApiObject']=r;i[r]=i[r]||function(){
   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
   m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
   })(window,document,'script','https://sdk.interactspace.com/analytics.js','tw');
   tw('configure', {
   partner_id: 'twiggle-partner-id',
   session_id: 'user-session-id',
   user_id: 'user-id-hash' // if a user is connected, otherwise omit user_id
   });
</script>
<!-- End Twiggle Analytics -->

The above code snippet

  • Creates a <script> element that starts downloading the analytics.js JavaScript library from https://sdk.interactspace.com/analytics.js;
  • Initializes a global tw function that will execute the library's commands (queuing them until the library loads); and
  • Initializes the library by sending configuration options in the first command.

Configuration Object

The first call to the tw function must contain a single configuration object with the following information:

tw('configure', { property: 'value', ... });

Configuration Options

Field NameData TypeDescription

partner_id

String (required)

Your Twiggle Partner ID.

session_id

String (required)

The current session ID. You should use the same session_id as used in conjunction with the Twiggle Semantic API queries interpretation requests (/queries).

user_id

String (optional, defaults to null)

The ID of the logged-in user, or null if there isn't one. (The default is null.) You should use the same user_id as used with the Twiggle Semantic API queries interpretation requests (/queries).

environment

String (optional, defaults to production)

The name of the running environment - the default is production. Other available values include staging and development, or any other name that describes the environment. This identifier is used to distinguish between the data sets coming from the different environments, so that data from the production environment will not be mixed with data from other environments. Because the interactions are used to train the Twiggle Semantic API model and for analytics reports generation, a mixture of data can lead to wrong results. This option must therefore be used for any environment other than production.

debug

String (optional, default is false)

Enables debug mode. The default mode is false. It is important to use debug mode during the development and integration phases because it provides various validations and assists with debugging. If it is turned off, the reporting will silently fail when there are errors and exceptions involving invalid formats or wrong usage.

Reconfiguration

It may become necessary to change part of the library configuration after initialization—for example, if your website allows users to connect and disconnect using ajax, the user_id may need to change. This is done by re-invoking the tw function with the configure command and providing the new user_id.

For example:

tw('configure', { user_id: null });

Interaction Types and Properties

The Twiggle Semantic API incorporates four types of interactions, as described above. Each interaction receives a properties object that includes relevant information. The properties that are included with each interaction type are listed below.

All interactions include a property that contains product-listing data; the data type for this property is a listing object that follows this schema:

Listing Example

{ 
 parent_id:'9c398',
 listing_id:'9c398fh',
 title:'Lace-Up Floral Dress',
 currency:'USD',
 price:9.99,
 quantity:2
}

Properties

Field NameData TypeDescription

parent_id

String (optional)

The listing's parent ID, if the listing is one of several product variants.

listing_id

String (required)

The product's unique ID (usually the SKU).

title

String (required)

The product's full title.

currency

String (required)

A three-letter ISO 4217 code (e.g., USD).

price

String (required)

The product's numeric price (without additions such as shipping fee or tax).

quantity

String (optional, defaults to 1)

The number of instances of the product within the listings array. The default value is 1. It should be used when a shopper chooses to add several copies of a product to the cart. The product represents a catalog listing (e.g., if the customer orders one set of four chairs, bearing one price tag, the quantity should be 1). If the quantity is greater than 1, the price should refer to the cost of a single product.

Search-Req-Result

The search-req-result interaction should be reported on any page presented in response to a search request (e.g., a search-results page, a no-results page, a category page, or a redirect page).

For example, if a user searches for "dress" and is redirected to the dresses category page (instead of actually invoking a search), this should be specified in the ref parameter (see more details below).

tw('search-req-result',
{  
   semantic_api_id:'f54a21ddbe6a11e7850842010a80040f',
   query:'red dress',
   query_params: 'length=mini;size=medium',
   listings:[  
      {  
         parent_id:'9c398',
         listing_id:'9c398fh',
         title:'Lace-Up Floral Dress',
         currency:'USD',
         price:24.99
      },
      ...
   ],
   page_number:1,
   test_variant:'B'
});

Properties

Field NameData TypeDescription

semantic_api_id

String (required)

The ID returned by the Twiggle Semantic API in response to the query-interpretation request that yielded this page. The semantic_api_id should be reported even if the API’s response isn’t used as part of your search logic.

query

String (required)

The search query that yielded this page, as typed by the shopper.

query_params

String (optional)

Include any additional search filters or parameters that were used in the search, other than the query term.

listings

Array[Listing] (required)

A list containing the product data returned by the search request that yielded this page, in the form of an array of listing objects, as described above. If there are no results, listings should be an empty array.

page_number

Number (optional)

The current results-page number, if pagination exists. There's no need to report a page if no pagination is available. If infinite scrolling on the front end translates to back-end pagination, a new semantic_api_id interaction should be reported with the updated array of listings objects and the appropriate page_number.

test_variant

String (optional)

If A/B Testing is used, this field should contain the test variant that was assigned to the search request by the Twiggle Semantic API. If A/B Testing is not being used, this field should be omitted.

ref

String

References the page presented in response to a search request. This varies greatly depending on your website. See the list of available values in the Using The Ref Property section.

Product View

The product-view interaction should be reported whenever the shopper is presented with a specific product page.

tw('product-view',
{  
   listing:{  
      parent_id:'9c398',
      listing_id:'9c398fh',
      title:'Lace-Up Floral Dress',
      currency:'USD',
      price:24.99
   }
});

Properties

Field NameData TypeDescription

listing

Listing Object (required)

An object containing the product's data, in the form of the listing object described above.

ref

String (optional)

References the source from which the interaction has been activated. This varies greatly, depending on your website. See the list of available sources in the Using the Ref Property section

Add-to-Cart

The add-to-cart interaction should be reported whenever the shopper simultaneously adds one or more products or makes any other changes to his or her cart.

tw('add-to-cart',
{  
   listings:[  
      {  
         parent_id:'9c398',
         listing_id:'9c398fh',
         title:'Lace-Up Floral Dress',
         currency:'USD',
         price:24.99
      },
      ...
   ]
});
Field NameData TypeDescription

listings

Array[Listing] (required)

A list containing product data for all products currently in the shopper's cart, in the form of an array of listing objects, as described above.

ref

String

References the source from which the interaction has been activated. This varies greatly, depending on your website. See the list of available sources in the Using the Ref Property section.

Purchase

The purchase interaction should be reported whenever a shopper executes a purchase.

tw('purchase',
{  
   listings:[  
      {  
         parent_id:'9c398',
         listing_id:'9c398fh',
         title:'Lace-Up Floral Dress',
         currency:'USD',
         price:24.99,
         quantity: 2
      },
      ...
   ],
   payment_amount: 49.98
});

Properties

Field NameData TypeDescription

listings

Array[Listing] (required)

A list containing product data for all products purchased by the shopper, in the form of an array of listing objects, as described above.

payment_amount

Number

The total amount paid by the shopper, after sales and discounts are applied.

Using the Ref Property

The ref property is used to distinguish between different user flows that could be triggering the same interaction types. The following are the values available and some typical examples of how ref is used.

Ref in Search-Req-Result

On most websites, a search action may result in several different presentations. Use the ref property to differentiate between them (e.g. a no-results page, a category page, or a redirect page, a product details page and so on).


The available values are:

valueDescription
no-results-pagea page presented to the user when no search results are found.
category-pagea page presented to the user following a search request.
product-details-pagea full product description page presented to the user following a search request.
redirect-pagea predefined page presented to the user following a search request.

Ref in Product-View

If your website has more than one product-view interface, such as an overlay view, use the ref property to indicate its type.

ValueDescription
product-pageThe user clicks on an item to view the full product-description page.
product-quick-viewThe user clicks on a "quick view" option to view the product highlights.

Ref in Add-To-Cart
You can use ref to distinguish between different routes taken when placing items in a shopping cart, such as moving it there from a wish list, a quick-view pop-up, or a product view.

ValueDescription
product-pageThe user added a product to their cart from the product page.
product-quick-viewThe user added a product to their cart from the product quick view.
wish-listThe user added a product to their cart from the wish-list/favorites section.
registryThe user added a product to their cart from the registry.

Debug Mode

Debug mode can be used during the development and integration phases to validate the data schema, check for consistency of field values, and handle any errors or warnings.

The following validations are implemented:

  • Schema validations check required properties for expected data types, as described in the interaction section. If a schema violation is found, an exception is reported.

  • Field values are checked, and a warning is reported if any inconsistency is detected (e.g., there is an unexpected change to the session_id, or a mismatch in the listing_id between the search results and the product view).

  • Customized validations can be added to validate data correctness. If a mismatch is detected, a warning is reported.

Note: Debug mode is always disabled when the configuration environment is set to production.

Customization

The Twiggle Analytics library is a very flexible platform that can handle any type of shopper-interaction data. Please contact your Twiggle account manager if there is a need to report additional interaction types for your website or application.