Action tracking overview

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-wishlist rate, add-to-cart 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
click When user click to view the detail of the product
add_to_cart When user click the button to add the product to cart
add_to_wishlist When user click the button to add the product to wishlist

By integrating with our solution widgets, the implementation of tracking all these 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.

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 your ViSearch API credentials. It is recommended to initiate the client when the SDK is loaded into the page.

<script type="text/javascript">

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

   visearch.set("app_key", "YOUR_APP_KEY");
</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 with your ViSearch API credentials. It is recommended to initiate 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");

After successfully installing the SDK, you can follow either of the two methods below to implement the tracking. Refer to Method I for only tracking product clicks and Method II for tracking product, add-to-cart, and add-to-wishlist clicks. Method II is the recommended method that is more straightforward and flexible.

Method I: append tracking information on product url to track click

To track users' clicks on the search result, you can append the following URL parameters into the product url where the user will be redirected to:

<a href="your_domain/path?reqid={reqid}&im_name={im_name}">click to product detail</a>

It is very important that the code snippet used for visearch sdk initialization to be placed at the html head of targeting page in order for the action to be tracked automatically.

tracking

Please note that this implementation works only for click action tracking. If you want to track other actions like add_to_wishlist or add_to_cart, please follow the method II to implement.

Method II: track user action with event handler

You can also send the user action through an event handler provided by the SDK. You need to register an event handler to the element in which the user will interact:

visearch.send({
  reqid: "xxxxxx",
  im_name: "xxxxx",
  action: "click"
});

The value for action parameter can also be add_to_cart or add_to_wishlist depending on which action you are tracking.

tracking

Explanation of the request parameters

Here's an explanation of the three required parameters:

Params Description
reqid The request id of the search request. This reqid can be obtained from any of the solution search responses. Please refer to the code snippet below
im_name The im_name of the image which the user has clicked on. im_name is the unique identifier of the indexed image, in this case the result of the search.
action This parameter is required for the second method, and it must be one of the supported actions: click, add_to_wishlist, add_to_cart

Code snippet for getting reqid:

visearch.uploadsearch({
  // request parameters
}, function(res) {
  // some response handler
  var reqid=res.reqid
});

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.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
...
// init ViSearch client with app key
ViSearch.sharedInstance.setup(appKey: "YOUR_APP_KEY")

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

Using Swift SDK

When a user performs the action that you want to track, the action can be sent in this way:

let params = ViTrackParams(reqId: recentReqId, action: "click" )
params.imName = "example_clicked_im_name"

// send tracking request to server
ViSearch.sharedInstance.track(params: params!, handler: nil)

Here's an explanation of the three required parameters:

Params Description
reqid The request id of the search request. This reqid can be obtained from any of the solution search responses. Please refer to the code snippet below
im_name The im_name of the image which the user has clicked on. im_name is the unique identifier of the indexed image, in this case the result of the search.
action This parameter is required for the second method, and it must be one of the supported actions: click, add_to_wishlist, add_to_cart

Code snippet for getting reqId:

ViSearch.sharedInstance.uploadSearch(params: params,
    successHandler: {
        (data : ViResponseData?) -> Void in

        let recentReqId = data.reqId!
    },
    failureHandler: {
        (err) -> Void in
        // Do something when request fails e.g. due to network error
        print ("error: \\(err.localizedDescription)")
    })

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.1.1'
...

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.

Using Objective-c SDK

When a user performs the action that you want to track, the action can be sent in this way:

ViSearchClient *client = [ViSearchAPI defaultClient];
TrackParams* params = [TrackParams reqId:recentReqId andAction:@"click"];

// You can also append an im_name field
parmas.withImName(@"example_clicked_im_name");

// send tracking request
[client track:params completion:^(BOOL success) {}];

Here's an explanation of the three required parameters:

Params Description
reqid The request id of the search request. This reqid can be obtained from any of the solution search responses. Please refer to the code snippet below
im_name The im_name of the image which the user has clicked on. im_name is the unique identifier of the indexed image, in this case the result of the search.
action This parameter is required for the second method, and it must be one of the supported actions: click, add_to_wishlist, add_to_cart

Code snippet for getting reqId:

[[ViSearchAPI defaultClient]
    searchWithImage: uploadSearchParams
    success:^( NSInteger statusCode, ViSearchResult *data, NSError *error) {

        // get recent request id
        NSString* recentReqId = data.reqId ;

    } failure:^(NSInteger statusCode, ViSearchResult *data, NSError *error) {
        // Do something when request fails
}];

Android integration

Setup and Initialize the Android SDK

You can include the dependency in your project using gradle:

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

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.

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

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

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

        ...
    }
    ...
}

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

Using the Android SDK

Setup tracking

It is important that a unique device ID is provided for user action tracking. ViSearch Android SDK uses Google Advertising ID as the default unique ID. Add this tag to your <application> in the AndroidManifest.xml to use Google Play Service:

<meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version">

In the case where Google Advertising ID is not available, a server-generated UID will be returned. This UID is automatically stored with your app that integrates with ViSearch Android SDK and will be refreshed only when the user uninstall your app.

Send action for tracking

viSearch.track(new TrackParams().setAction(action).setImName("example_clicked_im_name").setReqid(reqId));

Here's an explanation of the three required parameters:

Params Description
reqid The request id of the search request. This reqid can be obtained from any of the solution search responses. Please refer to the code snippet below
im_name The im_name of the image which the user has clicked on. im_name is the unique identifier of the indexed image, in this case the result of the search.
action This parameter is required for the second method, and it must be one of the supported actions: click, add_to_wishlist, add_to_cart

Code snippet for getting reqId:

@Override
public void onSearchResult(ResultList resultList) {
    String reqId = resultList.getTransId();

    //some other actions
}