Search analytics

tracking

The analytics reports page is located in your ViSenze Dashboard and allows you to conveniently see a high-level view of the performance of each of the solutions through click metrics as well as usage statistics. You can also drill down into the details or download the raw data for integration into other analyses.

With the analytics reporting tool, you can easily track the performance to quantify the value-add of our solutions through metrics such as click-through rate, add-to-cart rate, conversion rate and click rank. You can also quickly see and track changes in these metrics if you tweak your user-facing interface or as algorithm updates are released.

Here is the list of actions that our analytics reports support:

Action recorded Description
product_click When user clicks or taps on a product
product_view When a product is in view on the screen of the device
add_to_cart When a product is added to the shopping bag or cart
transaction When this product is purchased by the user

By integrating with our solution widgets, the implementation of tracking product_view and product_click actions are already included. However, if you would like to track actions being performed outside of the widgets UI or you want to customize your own UI, the action tracking needs to be implemented explicitly. It takes only a few steps for you to integrate our Javascript SDK / Mobile SDK with your application and implement the event tracking.

Server-side tracking

If you want to get started quickly, the fastest option is to enable server-side tracking. Collecting search analytics requires no extra effort on your side - No coding is required. You will be able to view computed metrics such as click-through rate, average click position.

Limitation

Server-side Tracking is limited and will only capture searches, product impressions, and product clicks. We would recommend you to use client-side tracking if possible to make better data-driven decisions. Please disable server-side tracking if you are already using client-side tracking to prevent duplicate events being recorded.

Configure triggers

For ViSenze to capture product clicks and impressions, we would need your permission to configure which schema fields are referring to the product URL and image URL. In the background, we will then rewrite those URLs and return the tracking URLs in ViSearch API response. When user visits the product URL via the tracking link, they will first be redirected to ViSenze server which will capture search query ID and click position before returning to the original product URL. Impression tracking works in the same way by rewriting the image URL which will trigger the event when the image is first loaded.

tracking

Web (JS) integration

Setup and initialization

First, paste the following snippet into the header of your site. This snippet will load visearch.js onto the page asynchronously, so it won’t affect your page load speed. Replace YOUR_APP_KEY with the app key under client-side integration page. It is recommended to initialize the client when the SDK is loaded into the page.

To understand search performance and gain useful data insights such as click-through / conversion rate, you can initialize the Event Tracker by setting tracker_code. The tracking code or ID can be found under ViSenze dashboard's tracking integration page.

<script type="text/javascript">

   !function(e,r,t,s,a){e.__visearch_obj=a;var c=e[a]=e[a]||{};c.q=c.q||[],c.factory=function(r){return function(){var e=Array.prototype.slice.call(arguments);return e.unshift(r),c.q.push(e),c}},c.methods=["idsearch","uploadsearch","colorsearch","set","send","search","recommendation","out_of_stock","similarproducts","discoversearch"];for(var o=0;o<c.methods.length;o++){var n=c.methods[o];c[n]=c.factory(n)}var i=r.createElement(t);i.type="text/javascript",i.async=!0,i.src="//cdn.visenze.com/visearch/dist/js/visearch-1.6.0.min.js";var h=r.getElementsByTagName(t)[0];h.parentNode.insertBefore(i,h)}(window,document,"script",0,"visearch");

    visearch.set('app_key', 'YOUR_APP_KEY');
    visearch.set('tracker_code', 'YOUR_TRACKER_CODE');

</script>

Alternatively, if you are using a JavaScript build system, you can install our SDK using NPM:

npm install visearch-javascript-sdk --save

To init the visearch client, please replace YOUR_APP_KEY / YOUR_TRACKER_CODE with your ViSearch app key and tracking ID. It is recommended to initialize the client when the SDK is loaded into the page.

// import module
import visearch from 'visearch-javascript-sdk';

// setup keys
visearch.set("app_key", "YOUR_APP_KEY");
visearch.set('tracker_code', 'YOUR_TRACKER_CODE');

Send events

User action(s) can be sent through an event callback such as a button click. Register an event callback to the element in which the user will interact. In the callback, the event can be sent using visearch.send method.

visearch.send(action, {
  queryId: '<search request ID>',
  pid: '<product ID> ',
  pos: <product position in Search Results>,
  imUrl: 'product image URL'
  ...
  ...
});

Get query ID

To send events, first retrieve the search query ID (the reqid) found in the search results response call back.

visearch.search({
  // request parameters
}, (res) => {
  // get search query ID
  const { reqid } = res;
  // send events
});

Send linked query events

Events which are linked to this search query ID can then be sent.


// send product click
visearch.send("product_click", {
                queryId: "<search reqid>",
                pid: "<your im_name>",
                pos: 1, // product position in Search Results, start from 1
                imUrl: "<product image URL e.g. im_url>"
            });

// send product impression
visearch.send("product_view", {
                queryId: "<search reqid>",
                pid: "<your im_name>",
                pos: 1, // product position in Search Results, start from 1
                imUrl: "<product image URL e.g. im_url>"
            });

// send Transaction event e.g order purchase of $300
visearch.send("transaction", {
                name: "<optional event name>" // optional event name
                queryId: "<search reqid>",
                transId: "<your transaction ID>"
                value: 300
         });

// send Add to Cart Event
visearch.send("add_to_cart", {
                queryId: "<search reqid>",
                pid: "<your im_name>",
                pos: 1, // product position in Search Results, start from 1
                imUrl: "<product image URL e.g. im_url>"
            });

// send custom event
visearch.send("click", {
                queryId: "<search reqid>",
                name: "click_on_camera_button",
                cat: "visual_search"
            });


Event parameters

Here's an explanation of various parameters:

Params Description Required
queryId The request id of the search. This reqid can be obtained from the search response callback:res.reqid Yes
action Event action. Currently we support the following event actions: click, view, product_click, product_view, add_to_cart, and transaction. Yes
pid Product ID ( generally, this is the im_name) for this product. Can be retrieved via im_name in result. Required for product_view, product_click and add_to_cart events
imUrl Image URL ( generally this is the im_url) for this product. Required for product_view, product_click and add_to_cart events
pos Position of the product in Search Results e.g. click position/ view position. Note that this starts from 1 , not 0. Required for product_view, product_click and add_to_cart events
transId Transaction ID Required for transaction event.
value Transaction value e.g. numerical order value Required for transaction event.
uid Unique user/device ID. If not provided, a random (non-personalizable) UUID will be generated to track the browser. No
cat A generic string to categorize / group the events in related user flow. For example: privacy_flow, videos, search_results. Typically, categories are used to group related UI elements. Max length: 32 No
name Event name e.g. open_app , click_on_camera_btn. Max length: 32. No
label label for main interaction object such as product title, page title. This together with action can be used to decide whether an event is unique e.g. if user clicks on same product twice, only 1 unique click . Max length: 32. No
fromReqId Generic request ID field to specify which request leads to this event e.g. click request ID that leads to the purchase. The chain can be like this queryId → clickId → purchase. Max length: 32. No
source Segment the traffic by tagging them e.g. from camera, from desktop. Max length: 32. No
brand Product brand. Max length: 64. No
price Product price. Numeric field, if provided must be >=0 and is a valid number. No
currency ISO 3 characters code e.g. “USD”. Will be validated if provided. No
productUrl Product URL. Max length: 512 No
c Advertising campaign. Max length : 64. No
cag Ad group name (only relevant for campaign) No
cc Creative name (only relevant for campaign) No
n1 Custom numeric parameter. No
n2 Custom numeric parameter. No
n3 Custom numeric parameter. No
n4 Custom numeric parameter. No
n5 Custom numeric parameter. No
s1 Custom string parameter. Max length: 64. No
s2 Custom string parameter. Max length: 64. No
s3 Custom string parameter. Max length: 64. No
s4 Custom string parameter. Max length: 64. No
s5 Custom string parameter. Max length: 64. No
json Custom json parameter. Max length: 512. No

iOS (Swift) integration

Setup and init Swift SDK

You can use CocoaPods to install the SDK. Edit the Podfile as follows:

platform :ios, '9.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'ViSearchSDK', '~>1.5.0'
end
...

Install the ViSearch SDK:

pod install

The Demo.xcworkspace project should be created.

ViSearch must be initialized with an app key before it can be used.

import ViSearchSDK
import ViSenzeAnalytics

...
// init ViSearch client with app key
ViSearch.sharedInstance.setup(appKey: "YOUR_APP_KEY")

// init Event Tracker to send Analytics events
let tracker = ViSearch.sharedInstance.newTracker(code: "YOUR_TRACKING_ID", forCn: false)

Please refer to the developer guide for more details of our Swift SDK.

Get Query ID

To send events, first retrieve the search query ID found in the search results call back:

successHandler: {
                    (data : ViResponseData?) -> Void in
                       if let data = data {
                           let queryId = data.reqId
                       }

}

Send Linked Query Events

Events which are linked to this search query ID can then be sent.

// send product click
let productClickEvent = VaEvent.newProductClickEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(productClickEvent) { (eventResponse, networkError) in

}

// send product impression
let impressionEvent = VaEvent.newProductImpressionEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(impressionEvent)

// send Transaction event e.g order purchase of $300
let transEvent = VaEvent.newTransactionEvent(queryId: "xxx", transactionId:"your trans id", value: 300)
tracker.sendEvent(transEvent)

// send Add to Cart Event
let add2Cart = VaEvent.newAdd2CartEvent(queryId: "ViSearch reqid in API response", pid: "product ID", imgUrl: "product image URL", pos: 3)
tracker.sendEvent(add2Cart)

Event Parameters

Params Description Required
queryId The request id of the search request. This reqid can be obtained from the search response handler:ViResponseData.reqId Yes
action Event action. Currently we support the following event actions: click, view, product_click, product_view, add_to_cart, and transaction. Yes
pid Product ID ( generally this is the im_name) for this product. Can be retrieved via ViImageResult.im_name Required for product view, product click and add to cart events
imgUrl Image URL ( generally this is the im_url) for this product. Can be retrieved via ViImageResult.im_url Required for product view, product click and add to cart events
pos Position of the product in Search Results e.g. click position/ view position. Note that this start from 1 , not 0. Required for product view, product click and add to cart events
transactionId Transaction ID Required for transaction event.
value Transaction value e.g. order value Required for transaction event.
uid Unique user/device ID. If not provided, a random (non-personalizable) UUID will be generated to track the browser. No
category A generic string to categorize / group the events in related user flow. For example: privacy_flow, videos, search_results. Typically, categories are used to group related UI elements. Max length: 32 No
name Event name e.g. open_app , click_on_camera_btn. Max length: 32. No
label label for main interaction object such as product title, page title. This together with action can be used to decide whether an event is unique e.g. if user clicks on same product twice, only 1 unique click . Max length: 32. No
fromReqId Generic request ID field to specify which request leads to this event e.g. click request ID that leads to the purchase. The chain can be like this queryId → clickId → purchase. Max length: 32. No
source Segment the traffic by tagging them e.g. from camera, from desktop. Max length: 32. No
brand Product brand. Max length: 64. No
price Product price. Numeric field, if provided must be >=0 and is a valid number. No
currency ISO 3 characters code e.g. “USD”. Will be validated if provided. No
productUrl Product URL. Max length: 512 No
campaign Advertising campaign. Max length : 64. No
adGroup Ad group name (only relevant for campaign) No
creative Creative name (only relevant for campaign) No
n1 Custom numeric parameter. No
n2 Custom numeric parameter. No
n3 Custom numeric parameter. No
n4 Custom numeric parameter. No
n5 Custom numeric parameter. No
s1 Custom string parameter. Max length: 64. No
s2 Custom string parameter. Max length: 64. No
s3 Custom string parameter. Max length: 64. No
s4 Custom string parameter. Max length: 64. No
s5 Custom string parameter. Max length: 64. No
json Custom json parameter. Max length: 512. No

iOS (Objective-c) integration

Setup and init Objective-c SDK

You can use CocoaPods to install the SDK. Edit the Podfile as follow:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '7.0'
...
pod 'ViSearch', '~>1.5.0'
...

Install the ViSearch SDK:

pod install

ViSearch must be initialized with an app key before it can be used.

#import <ViSearch/VisearchAPI.h>
...
// using default ViSearch client. The client, by default,
// connects to Visenze's server
static NSString * const appKey = @"your_app_key";

[ViSearchAPI setupAppKey:appKey];
ViSearchClient *client = [ViSearch defaultClient];
...
// OR using customized client, which connects to your own server
static NSString * const privateKey = @"your_url";
ViSearchClient *client = [[ViSearchClient alloc] initWithBaseUrl:url
    appKey:appKey];
...

Please refer to the developer guide for more details of our Objective-c SDK.

Send Events

To improve search performance and gain useful data insights, it is recommended to send user interactions (actions) with our visual search results. Our tracking SDK (Swift) is located at https://github.com/visenze/visenze-tracking-swift.

Android integration

Setup and Initialize the Android SDK

You can include the dependency in your project using gradle:

compile 'com.visenze:visearch-android:1.5.0'

In the build.gradle file under your app module, add the packaging options to ensure successful compilation:

android {
    ...

    packagingOptions {
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/LICENSE'
    }
    ...
}

ViSearch Android SDK requires these user permissions to work. Add the following declarations to the AndroidManifest.xml file. Network permission allows the app to connect to network services. Writing/reading to external storage permissions allow the app to load and save images on the device.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.visenze.android.visenze_demo_test">

    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

    <application>
    ...
    </application>
</manifest>

ViSearch must be initialized with an app key before it can be used. In order for it to be notified of the search result, ViSearch.ResultListener must be implemented. Call viSearch.setListener to set the listener. Please also provide your Tracking ID (found under Tracking Integration page of ViSenze dashboard) to initialize event tracker.

public class MyActivity extends Activity implements ViSearch.ResultListener{
    //Please change to your app key
    private static final String APP_KEY = "your_app_key";
    private static final String TRACKING_ID = "your_tracking_id";
    ...

     @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        ViSearch viSearch = new ViSearch.Builder(APP_KEY).build(this);
        viSearch.setListener(this);

        // init Event Tracker to send Analytics event
        Tracker tracker = visearch.newTracker(TRACKING_ID, false);

        ...
    }
    ...
}

Please refer to the developer guide for more details of our Android SDK.

Using the Android SDK

Setup tracking

As mentioned above, the tracker needs to be initialized before sending events:

Tracker tracker = visearch.newTracker(code, false);

Send events

To send events, first retrieve the search query ID found in the search results listener:


@Override
public void onSearchResult(ResultList resultList) {
    String queryId = resultList.getReqid();
}

Then, create the event using 1 of the helper methods Event.createXXXEvent(). For product_click, product_view events, queryId, pid, imgUrl and pos are all required.

Event.createProductClickEvent(String queryId, String pid, String imgUrl, int pos)
Event.createProductImpressionEvent(String queryId, String pid, String imgUrl, int pos)
Event.createAddCartEvent(String queryId, String pid, String imgUrl, int pos)
Event.createTransactionEvent(String queryId, String transactionId, double value) 
// custom event with arbitray action
Event.createCustomEvent(String action) 

Finally send the event via the tracker:

tracker.sendEvent(event);

Request parameters

Params Description Required
queryId The request id of the search request. This reqid can be obtained from all the search result:resultList.getReqid() Yes
action Event action. Currently we support the following event actions: click, view, product_click, product_view, add_to_cart, and transaction. Yes
pid Product ID ( generally this is the im_name) for this product. Can be retrieved via ImageResult.getImageName() Required for product view, product click and add to cart events
imgUrl Image URL ( generally this is the im_url) for this product. Can be retrieved via ImageResult.getImageUrl() Required for product view, product click and add to cart events
pos Position of the product in Search Results e.g. click position/ view position. Note that this start from 1 , not 0. Required for product view, product click and add to cart events
transactionId Transaction ID Required for transaction event.
value Transaction value e.g. order value Required for transaction event.
uid Unique user/device ID. If not provided, a random (non-personalizable) UUID will be generated to track the device. No
category A generic string to categorize / group the events in related user flow. For example: privacy_flow, videos, search_results. Typically, categories are used to group related UI elements. Max length: 32 No
name Event name e.g. open_app , click_on_camera_btn. Max length: 32. No
label label for main interaction object such as product title, page title. This together with action can be used to decide whether an event is unique e.g. if user clicks on same product twice, only 1 unique click . Max length: 32. No
fromReqId Generic request ID field to specify which request leads to this event e.g. click request ID that leads to the purchase. The chain can be like this queryId → clickId → purchase. Max length: 32. No
source Segment the traffic by tagging them e.g. from camera, from desktop. Max length: 32. No
brand Product brand. Max length: 64. No
price Product price. Numeric field, if provided must be >=0 and is a valid number. No
currency ISO 3 characters code e.g. “USD”. Will be validated if provided. No
productUrl Product URL. Max length: 512 No
campaign Advertising campaign. Max length : 64. No
campaignAdGroup Ad group name (only relevant for campaign) No
campaignCreative Creative name (only relevant for campaign) No
n1 Custom numeric parameter. No
n2 Custom numeric parameter. No
n3 Custom numeric parameter. No
n4 Custom numeric parameter. No
n5 Custom numeric parameter. No
s1 Custom string parameter. Max length: 64. No
s2 Custom string parameter. Max length: 64. No
s3 Custom string parameter. Max length: 64. No
s4 Custom string parameter. Max length: 64. No
s5 Custom string parameter. Max length: 64. No