visearch-javascript-sdk v4.1.0

visearch-javascript-sdk

ViSenze's Javascript SDK provides accurate, reliable and scalable image search APIs within our catalogs. The APIs included in this SDK aims to provide developers with endpoints that executes image search efficiently while also making it easy to integrate into webapps.

Note: In order to use any of our SDKs, you are required to have a ViSenze developer account. You will gain access to your own dashboard to manage your appkeys and catalogs. Visit here for more info.

Table of Contents

• visearch-javascript-sdk
  • Table of Contents
  • 1. Quickstart
    • 1.1 Installation
    • 1.2 Setup
      • 1.2.1 Import and initialization
      • 1.2.2 Configure keys
    • 1.3 Demo
  • 2. API
    • 2.1 Search by Image
    • 2.2 Recommendations
    • 2.3 Multisearch
    • 2.4 Multisearch Autocomplete
  • 3. Search Results
    • 3.1 ErrorData
    • 3.2 ProductType
    • 3.3 Product
      • 3.3.1 Data
    • 3.4 ProductObject
    • 3.5 Facet
    • 3.6 FacetItem
    • 3.7 FacetRange
  • 4. Advanced Search Parameters
    • 4.1 Example - Retrieving Metadata
    • 4.2 Example - Filtering Results
    • 4.3 Example - Automatic Object Recognition
  • 5. Event Tracking
    • 5.1 Setup Tracking
    • 5.2 Send Events
      • 5.2.1 Getting session Id
      • 5.2.2 Getting user Id
      • 5.2.3 Getting query Id
    • 5.2 Send Batch Events
  • 6. Resize settings
  • 7. Migration from v3

1. Quickstart

Follow these simple steps to get familiarized with how the SDK can be integrated and how it actually works by exploring our demos included in the main repo.

1.1 Installation

If you are using the project provided directly from the main repo, you can simply run the following command from the root directory of this project:

npm install

If you are trying to include this SDK into your own project via npm, run the following command from the root directory of your project:

npm install visearch-javascript-sdk

1.2 Setup

1.2.1 Import and initialization

• In Node

  import ViSearch from 'visearch-javascript-sdk';
  
  ...
  
  const visearch = ViSearch();

  • Create multiple instances

  If you have multiple placements or if you want to run placements with different configurations, you would need to create multiple ViSearch instances.

  const visearch1 = ViSearch();
  const visearch2 = ViSearch();

• In browser

  If you wish to include the SDK directly onto your webpage, add this to the header of your site

  <script type="text/javascript">
  !function(e,t,r,s,a){if(Array.isArray(a))for(var n=0;n<a.length;n++)o(e,t,r,s,a[n]);else o(e,t,r,s,a);function o(e,t,r,s,a){var n=e[a]||{};e[a]=n,n.q=n.q||[],n.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);return t.unshift(e),n.q.push(t),n}},n.methods=["set","setKeys","sendEvent","sendEvents","productMultisearch","productMultisearchAutocomplete","productSearchByImage","productSearchById","productRecommendations","productSearchByIdByPost","productRecommendationsByPost","setUid","getUid","getSid","getLastQueryId","getSessionTimeRemaining","getDefaultTrackingParams","resetSession","resizeImage","generateUuid",];for(var o=0;o<n.methods.length;o++){var i=n.methods[o];n[i]=n.factory(i)}if(e.viInit)viInit(e,a);else{var c,d,u,f,g,m=(c=t,d=r,u=s,(f=c.createElement(d)).type="text/javascript",f.async=!0,f.src=u,(g=c.getElementsByTagName(d)[0]).parentNode.insertBefore(f,g),f);m.onload=function(){viInit(e,a)},m.onerror=function(){console.log("ViSearch Javascript SDK load fails")}}}}(window,document,"script","https://cdn.visenze.com/visearch/dist/js/visearch-4.1.0.min.js","visearch");
  </script>

  • Create multiple instances

  Copy the same code but change the keyword "visearch" into an array of your desired instances names.

  <script type="text/javascript">
  ...(window,document,"script",0,["visearch", "visearch2"]);
  </script>

1.2.2 Configure keys

Before you can start using the SDK, you will need to set up . Most of these keys can be found in your account's dashboard.

Please take a look at the table below to understand what each key represents:

Set up the ViSearch instance(s) with the keys from console.

visearch.set('app_key', 'YOUR_APP_KEY');
visearch.set('placement_id', 'YOUR_PLACEMENT_ID');
visearch.set('timeout', TIMEOUT_INTERVAL_IN_MS);

or

visearch.setKeys({
  'app_key': 'YOUR_APP_KEY',
  'placement_id': 'YOUR_PLACEMENT_ID'
});
visearch2.setKeys({
  'app_key': 'YOUR_APP_KEY_2',
  'placement_id': 'YOUR_PLACEMENT_ID_2'
});

or

if you are in a Node env, you can pass the configs in directly when creating the ViSearch client.

const visearch = ViSearch({
  'app_key': 'YOUR_APP_KEY',
  'placement_id': 'YOUR_PLACEMENT_ID'
})

1.3 Demo

The demo is only applicable to those who work directly off the main repo. You are required to have a Node.js environment and remember to fill up the relevant files.

Create a .env file and fill in the relevant app key and placement id

SEARCH_APP_KEY = 
SEARCH_PLACEMENT_ID = 
SEARCH_IM_URL = 
REC_PID = 
REC_APP_KEY = 
REC_PLACEMENT_ID = 
ENDPOINT = 

• To run the webpage demo:

  npm run start-demo

  After the above command, you should see that the server is running locally on your device. You can then access the different demo webpages in your browser by using this format http://localhost:3000/examples/*.html.

  • E.g. Product recommendation:

  http://localhost:3000/examples/product_search_by_id.html

  • E.g. Product search by image:

  http://localhost:3000/examples/product_search_by_image.html

  • E.g. Tracking:

  http://localhost:3000/examples/tracking.html

2. API

2.1 Search by Image

POST /product/search_by_image

Searching by Image can happen in three different ways - by url, id or File.

• Using image id:

  const parameters = {
    im_id: 'your-image-id'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productSearchByImage(parameters, onResponse, onError);

• Using image url:

  const parameters = {
    im_url: 'your-image-url'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productSearchByImage(parameters, onResponse, onError);

• Using image file:

  <form>
    Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
    <input type="submit" value="Submit">
  </form>

  const parameters = {
    image: document.getElementById('fileUpload')
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productSearchByImage(parameters, onResponse, onError);

The request parameters for this API can be found at ViSenze Documentation Hub.

2.2 Recommendations

GET /product/recommendations/{product_id}

Search for visually similar products in the product database giving an indexed product’s unique identifier.

const product_id = 'your-product-id';

const parameters = {
};

const onResponse = (response)=> {
  // TODO handle response
}

const onError = (error)=> {
  // TODO handle error
}

visearch.productRecommendations(product_id, parameters, onResponse, onError);

The request parameters for this API can be found at ViSenze Documentation Hub.

2.3 Multisearch

POST /product/multisearch

Multisearch can happen in four different ways - by text, url, id or File.

• Using text:

  const parameters = {
    q: 'your-text-query'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearch(parameters, onResponse, onError);

• Using image id:

  const parameters = {
    im_id: 'your-image-id'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearch(parameters, onResponse, onError);

• Using image url:

  const parameters = {
    im_url: 'your-image-url'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearch(parameters, onResponse, onError);

• Using image file:

  <form>
    Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
    <input type="submit" value="Submit">
  </form>

  const parameters = {
    image: document.getElementById('fileUpload')
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearch(parameters, onResponse, onError);

The request parameters for this API can be found at ViSenze Documentation Hub.

2.4 Multisearch Autocomplete

POST /product/multisearch/autocomplete

Multisearch autocomplete can happen in four different ways - by text, url, id or File.

• Using text:

  const parameters = {
    q: 'your-text-query'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearchAutocomplete(parameters, onResponse, onError);

• Using image id:

  const parameters = {
    im_id: 'your-image-id'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearchAutocomplete(parameters, onResponse, onError);

• Using image url:

  const parameters = {
    im_url: 'your-image-url'
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearchAutocomplete(parameters, onResponse, onError);

• Using image file:

  <form>
    Upload image: <input type="file" id="fileUpload" name="fileInput"><br>
    <input type="submit" value="Submit">
  </form>

  const parameters = {
    image: document.getElementById('fileUpload')
  };
  
  const onResponse = (response)=> {
    // TODO handle response
  }
  
  const onError = (error)=> {
    // TODO handle error
  }
  
  visearch.productMultisearchAutocomplete(parameters, onResponse, onError);

The request parameters for this API can be found at ViSenze Documentation Hub.

3. Search Results

Javascript does not contain type definitions and the REST API response for all our APIs will instead just convert straight into javascript objects. Here are some of the API's response object's keys to take note of:

3.1 ErrorData

3.2 ProductType

3.3 Product

3.3.1 Data

The fields returned under here are dependent on the product metadata requested through the attrs_to_get params and the fields indexed in your catalog.

Other than that, we return 2 default fields.

3.4 ProductObject

When using the search_all_objects is set to true, the search response will return the results in a list of ProductObject instead of a list of Product directly. The difference is that ProductObject will split the products according to type.

3.5 Facet

Facets are used to perform potential filtering of results.

To check usage guideline, please refer here

3.6 FacetItem

Facet for distinct value filtering.

3.7 FacetRange

Facet for value range filtering.

4. Advanced Search Parameters

There are many parameters that our API support and we will be showing you a few examples of how to use them in this section.

You can find all of the supported advance search parameters for ProductSearch API here.

4.1 Example - Retrieving Metadata

To retrieve metadata of your image results, provide the list of metadata keys for the metadata value to be returned in the attrs_to_get property:

visearch.productSearchByImage({
  im_url: 'your-image-url',
  attrs_to_get: ['price', 'brand', 'im-url'], // list of fields to be returned
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

Note that only the indexed attributes can be retrieved with this parameter. You may go the the Edit App page in the Discovery Suite console to review which attributes have been included in the app index.

4.2 Example - Filtering Results

To filter search results based on metadata values, provide a string array of metadata key to filter value in the filters property. Only price, category, brand, original_price support filter parameter.

visearch.productSearchByImage({
  im_url: 'your-image-url',
  filters: ['brand:my_brand'],
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

For more details, check out Filters and Text Filters section in the ViSenze Documentation Hub.

4.3 Example - Automatic Object Recognition

With Automatic Object Recognition, ViSearch Search by Image API is smart to detect the objects present in the query image and suggest the best matched product type to run the search on.

You can turn on the feature in upload search by setting the API parameter detection=all. We are now able to detect various types of fashion items, including top, dress, bottom, shoe, bag, watch. The list is ever-expanding as we explore this feature for other categories.

visearch.productSearchByImage({
  im_url: 'your-image-url',
  detection: 'all',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

You could also recognize objects from a paticular type on the uploaded query image through configuring the detection parameter to a specific product type as detection={type}. Our API will run the search within that product type.

Sample request to detect bag in an uploaded image:

visearch.productSearchByImage({
  im_url: 'your-image-url',
  detection: 'bag',
}, (res) => {
  // TODO handle response
}, (err) => {
  // TODO handle error
});

The detected product types are listed in product_types together with the match score and box area of the detected object. Multiple objects can be detected from the query image and they are ranked from the highest score to lowest. The full list of supported product types by our API will also be returned in product_types_list.

5. Event Tracking

To improve search performance and gain useful data insights, it is recommended to send user interactions (actions) with the visual search results.

5.1 Setup Tracking

To send the events, we will initialize the event tracker with a tracking ID generated from your app key and placement ID for you. There are two different endpoints for tracker (1 for China and another for the rest of the world). If the SDK is intended to be used in China region, please set is_cn parameter to true.

// optional, send events to global or China server
visearch.set("is_cn", false);

5.2 Send Events

User action(s) can be sent through an event handler. Register an event handler to the element in which the user will interact.

visearch.sendEvent(action, {
  queryId: '<search request ID>',
  pid: '<product ID> ',
  pos: <product position in Search Results>,
  ...
  ...
}, (action, params) => {
  // success callback
}, (err) => {
  // error callback
});

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

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

5.2.1 Getting session Id

var onSuccess = (sid) => {
  /* do something */
};
var onError = (err) => {
  /* do something */
}

visearch.getSid(onSuccess, onError);

5.2.2 Getting user Id

var onSuccess = (uid) => {
  /* do something */
};
var onError = (err) => {
  /* do something */
}

visearch.getUid(onSuccess, onError);

5.2.3 Getting query Id

var onSuccess = (query_id) => {
  /* do something */
};
var onError = (err) => {
  /* do something */
}

visearch.getLastQueryId(onSuccess, onError);

This will fetch the last query Id from any request made by replacement, and if none is found retrieved from the last value saved in local storage.

Currently, we support the following event actions: product_click, product_view, add_to_cart, and transaction. The action parameter can be an arbitrary string and custom events can be sent.

// send product click
visearch.sendEvent("product_click", {
                queryId: "<search reqid>",
                pid: "<your im_name>",
                pos: 1, // product position in Search Results, start from 1
            });
            
// send product impression
visearch.sendEvent("product_view", {
                queryId: "<search reqid>",
                pid: "<your im_name>",
                pos: 1, // product position in Search Results, start from 1
            });
            
// send Transaction event e.g order purchase of $300
visearch.sendEvent("transaction", {
                name: "<optional event name>" // optional event name
                queryId: "<search reqid>",
                transId: "<your transaction ID>"
                value: 300
         });

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

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

5.2 Send Batch Events

User action(s) can be sent through an batch event handler.

A common use case for this batch event method is to group up all transaction by sending it in a batch. This SDK will automatically generate a transId to group transactions as an order.

visearch.sendEvents('transaction', [{
  queryId: '<search request ID>',
  pid: '<product ID - 1> ',
  value: 300,
  ...
  ...
},{
  queryId: '<search request ID>',
  pid: '<product ID - 2> ',
  value: 400
  ...
  ...
}], (action, params) => {
  // success callback
}, (err) => {
  // error callback
});

Below are the brief description for various parameters. Please note that invalid events (such as missing required fields or exceed length limit) will not be captured by server.

6. Resize settings

When performing upload search, you may notice the increased search latency with increased image file size. This is due to the increased time spent in network transferring your images to the ViSearch server, and the increased time for processing larger image files in ViSearch.

To reduce upload search latency, by default the product search by image method makes a copy of your image file and resizes the copy to 512x512 pixels if both of the original dimensions exceed 512 pixels. This is the optimized size to lower search latency while not sacrificing search accuracy for general use cases

If your image contains fine details such as textile patterns and textures, you can set a different default maximum dimension to get better search results:

visearch.set('resize_settings', {maxHeight: 1024, maxWidth: 1024});

You can also call the resizeImage method to resize the image yourself. The method takes in returns image in Data URL form.

var resizedImage = visearch.resizeImage(imgAsDataURL, resizeSettings, onSuccess, onFailure);

7. Migration from v3

The v4 SDK introduces a number of breaking changes, so if you're migrating from v3 you can refer this guide for a smoother transition.