NAV Navbar
Logo
python javascript

Vue.ai API and Technical Documentation

Vue.ai is an Arificial Intelligence and Computer Vision platform that is geared towards solving problems in the retail domain. This is the technical documentation section of vue.ai that provides all the details that are necessay to get Vue.ai integrated on to your website or app.

Integration Flow

Process Flow

Input Data

Product Catalog

The Product Catalog is a necessary input for the vue.ai engines to work. We use the images from the catalog for all visual processing. The other metadata is used as inputs to our algorithms, as well as for returning as details on the results of the various APIs.

The catalog can be provided in a variety of formats including but not restricted to:

Access methods

Product Information

Below is a list of fields that we use for processing the data and serving recommendations:

Key Type Description
id String Unique ID for the product
parent_id String Parent ID for the product (if multiple variants are available) [optional]
title String Name or Title of the product
brand String Brand name [optional]
image_link String URL for the primary image
small_ image_link String URL for the thumbnail image [optional]
link String URL for the product display page
price Float Listing price of the product
description String Short description of the product [optional]
gender String Gender of the product if available [optional]
category String The top level category for the product
sub_category String The second level category for the product [optional]
sub_ sub_category String The third level category for the product [optional]
available Boolean Shows if the product is in stock/out of stock
ontology String Specifies the ontology hierarchy formed with gender, category, sub_category, sub_sub_category separated by “>” symbol. It is converted into lowercase and all special characters replaced with an underscore. By passing in the “ontology” field, the default setting is overridden. [optional] Eg: gender > cat > sub_cat> sub_sub_cat
date Datetime When the message is enqueued in SQS in “YYYY-MM-DD HH:MM:SS” format. (only if using the SQS queueing method)

Note: Any additional fields can also be sent in addition to the above fields.

Data load

There are two modes in which we can process the catalog data:

Bulk Mode

Bulk mode is when we process the entire feed every day (or at any cadence that is agreed upon) and use this to update the systems. Typically, this is done for small catalogs where the catalog size and the churn is minimal. In this mode, all the products that are available on any given day are sent to our systems for processing. The following rules are applied to make the updates:

Delta Mode

Delta mode is when we process only the delta updates on a daily basis (or on any cadence that is agreed upon). The pre-condition for this mode of catalog processing is that there must have been a one-time bulk load of all products in our system post which the updates to the system will be on a delta mode. The following rules are applied to make the updates:

The vue.ai APIs

Vue.ai’s services are provided through API end points that can be accessed via SSL encrypted HTTPS POST calls. All the responses will be in JSON format.

The Following are the API end points that service the different Products:

API Product
widgets VueCommerce
mail VueMail
tag VueTag

The vuemail API

vuemail is used for personalized recommendations that are sent on emails. The difference between traditional recommendations on mail, and vuemail is that the recommendations are fetched only on open of the email, instead of pre-fetching and appending to the email body. This allows brands to serve the most up-to-date information from the catalog (like price, product availability).

Based on the region, the APIs would be served from one of the following end points:

Region End point
US East (N. Virginia) https://vuemail.madstreetden.com/
AP Southeast (Singapore) https://ap-southeast-1.vuemail.madstreetden.com/

The below are the two end points of the vuemail API:

API Description URL
image Renders the image of the product with the requisite product information displayed in the format defined in a user-defined template http://vuemail.madstreetden.com/mail/v2/image
link Returns the link of the product to which user needs to be redirected when he clicks on the image http://vue,ai.madstreetden.com/mail/v2/link/

Below is a list of the keys used to query the vuemail API with:

Name Description
mad_uuid Unique user ID generated by vue_ai.js to be used as the basis for all personalization
product_id Product for which recommendations are required (for all product-based recommendations like Similar Products, Complete the Look etc.)
api_key Customer specific API key (unique to each of vue.ai’s customers)
num_results The number of results that are to be returned on the API. Can be a scalar or a list matching the number of widgets. (Default = 6)
widget_id Widget ID that needs to be displayed
image_no Image number (the index goes from 0 to (num_results - 1).
For eg: If num_results is 6
- first image: the image_no is 0
- second image, image_no is 1
width Width of image in pixels
height Height of image in pixels
ts Timestamp
template Image configuration template file name (reverts to the default template if the template name is not mentioned)
campaign Unique ID/string for this particular email campaign
filters A list of filters to be applied on the results can also be added as GET params to the image. It will be a JSON list of filter objects to be applied on the recommendations.
utm_* This parameter should be passed on the redirected url. It will help in tracking the clicks on the links

vuemail allows for templates to be defined to render the images. Below parameters are configurable to render the image:

Example for Image API:


https://vuemail.madstreetden.com/mail/v2/image/?api_key=8783ef1459dfdsd5919d35
&widget_id=0
&mad_uuid=14175980
&image_no=0
&width=230
&height=400
&product_id=MP0000000002850sdf7
&campaign=msd_test
&num_results=6
&ts=123344545
&template=template123

Example for Link API:

https://vuemail.madstreetden.com/mail/v2/link/?api_key=8783ef1459dfdsd5919d35
&widget_id=0
&mad_uuid=14175980
&image_no=0
&width=230
&height=400
&product_id=MP0000000002850sdf7
&campaign=msd_test
&num_results=6
&ts=123344545
&template=template123

The image rendered will look like:

Vuemail image

The Widgets API

The widgets API serves all of Vue.ai’s VueCommerce recommendations, and the results of VueFind. Based on your region, the APIs would be served from one of the following end points:

Region End point
US West (N. California) https://us-west-1-api.madstreetden.com/widgets
US West (Oregon) https://us-west-2-api.madstreetden.com/widgets
US East (N. Virginia) https://us-east-1-api.madstreetden.com/widgets
AP Southeast (Singapore) https://ap-southeast-1-api.madstreetden.com/widgets
EU Central (Frankfurt) https://eu-central-1-api.madstreetden.com/widgets

Below is a list of the keys that are available to query the widgets API with:

Key: M : Mandatory ; O : Optional ; C : Conditional

Name Value M/O/C Description
mad_uuid String M Unique user ID to be used as the basis for all personalization. Typically, the one that is generated by vue_ai.js would be used for this
user_id String O Internal User ID that is maintained by you (typically, this comes out of your internal identity management system)
product_id String C Product for which recommendations are required
api_key String M Customer specific API key (unique to each of vue.ai’s customers)
num_results int Array O The number of results that are to be returned on the API. Can be a scalar or a list matching the number of widgets. (Defaults to 16)
widget_list int Array M List of widgets IDs for which recommendations are required
product_list String Array O List of product IDs for each widget (where applicable)
details String O true - returns metadata along with the results
false - results are returned with no additional metadata (defaults to false)
source String O This is used to distinguish the source of the API calls:
staging - if the call is from the staging servers.
production - if the call is from the production servers
country String O Name of the country that the API calls are made from(in case of multiple countries served by your site)
fields String Array O A list of extra metadata that is to be returned (in addition to the standard fields returned when details is true)
filters JSON Array O A list of filters to be applied on the results
search_query^^ String O The term(s) being searched for
sort_by^^ JSON Object O The field that the search results are to be ordered by
page_num String O The page number of the results. In each page, the number of results that are to be returned is determined by num_results. ( Eg: if num_results is 10 and page_num is 2, results 11 to 20 are returned)

^^Applicable only to VueFind (widgetID = 42)

Notes

Filters

Enable you to filter the results that are returned on the API. Any field that is indexed can be used for filtering. filters is a JSON encoded string having a list of filter objects. Each filter object has three keys:

Key Description
field This is the field that the filter needs to be applied to
value The actual value to be used to filter by
type Determines what kind of filtering is applied on the field:
contains - match all products which has substring [default]
not-contains - match all products which doesn’t have the substring
exact- exact string/int/float match.
range - match all values between [x, y] (both inclusive)
gt - match all values greater than value.
lt - match all values lesser than value.
gte - match all values greater equal to value.
lte - match all values less than equal to value.

Example

[
    {    
        "field": "title",
        "value": "shoes",
        "type": "contains"
    },
    {
        "field": "availability",
        "value": true
    },
    {
        "field": "price",
        "type": "range",
        "value": [500, 700]
    }
]

For filtering for multiple values of same field, the values can be wrapped into a list.

Example 


[
    {
        "field": "title",
        "value": "['tops', 'jeans']",
        "type": "contains"
    },
    {
        "field": "availability",
        "value": true
    },
    {
        "field": "brand",
        "value": "['foo', 'bar', 'baz', 'loreum epusm']"
    },

    {
        "field": "price",
        "type": "range",
        "value": [50.0, 70.0]
    }
]

Note: : If type is range , there cannot be more than two entries in that list.

Fields

The output fields can be customized by using the fields parameter, which is a JSON list of strings. Any field name that was sent in the catalog can be returned. Below are the fields that are returned by default:

Example

"['brand', 'title', 'image_link', 'price']"

sort_by

Key Description Values
field the field that the results are sorted by trending : Sorts the results by what is trending on the store
random : Randomized sort
order determines the sorting order ascending: Sorts the results in ascending order
descending : Sorts that results in descending order

Response JSON

The response for the API call will produce the following JSON object in response.

Name Value Description
status String Success or failure
message String Error message when status equals ‘failure’
data Array of JSON objects JSON array of widget responses

Widget List

Both VueCommerce and VueFind are delivered throught the widgets API

VueCommerce

ID Widget Name Description
0 Similar Product Recommendations A list of recommendations for a given product.
- For fashion and lifestyle categories, these recommendations will be based on visual similarity
– For other categories, these will be based on user behaviour
1 Browsing History Based Recommendations A list of products based on recently browsed products
3 Trending Products Top-selling products (at category level if breadcrumb is specified)
4 Complete Your Purchase A list of products from complementary categories that can be cross-sold with the given product
5 Frequently Bought Together A curated list of products that are co-bought with the product frequently (typically these are bundles that can be added to cart / bought together at one go)
7 Recently Viewed Products A list of the user’s most recently viewed products
8 AI Stylist Recommendations Ensembles of products to Complete the Look
11 Recommended For You A list of recommended products based on user’s visual and behavioral preferences

VueFind

ID Widget Name Description
25 Personalized Category Listing Page Personalized sorting of products on category landing pages
42 VueFind
Personalized Site Search		 Personalized Search powered by Computer Vision and NLP

Errors

The following errors may be thrown if the appID, appSecret or product ID is incorrect, or if a product has not been digested yet.

The Mad Street Den API uses the following error codes:

Error Code Message
0 Unauthorized API key
400 Bad Request – You should modify your request and try again
401 Unauthorized – Your API key is wrong
403 Forbidden
404 Not Found
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable
409 Product Not Digested
429 Too Many Requests
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable

Pixel for Personalization and Analytics

Tracking pixels provide user behavior data that power our personalization algorithms. The pixels also help us monitor the performance of the recommendations, and build analytics reports for your store.

Before we get into the implementation, below listed is the data dictionary (of the various parameters in the pixels) and the list of events themseleves. These parameters and pixels remain the same regardless of the platform that they are implemented on.

Data Dictionary

Parameter Definiton Example
event Name of the event to be triggered pageView
userID unique ID to identify a user (if vue_ai.js is not used, then this ID can be the same as that provided in the uuid parameter) 12344567
uuid unique ID that is used to identify a user :
- if vue_ai.js is used, this is automatically generated and can be got using this: MSDreadCookie('MADid')
- if vue_ai.js is not used, this can be the unique ID that you use		 12344567
clicked the epoch time of the event’s occurance 1542481128
url url of the current page https://madstreetden.com/shoes/52231/
referrer url of the referring page For Websites - https://madstreetden.com/shoes/
For Apps - App, iOSApp, AndroidApp
sourceProdID productID of the product that the event is triggered on 52231
destProdID productID of the recommendation that the user has clicked on 12234
sourceCatgID category of the product page that the user is currently on 402
destCatgID category of the recommendation that the user has clicked on 402
prodPrice price of the product 79.99
posOfReco position of the recommendation on the recommendation carousel / grid that the action occurs on 1
widgetID ID of the recommendation widget (Eg: 0 for Similar Products) 0
pageType the type of page that the event is triggered on (‘home’, ‘cart’, ‘product display’, ‘category listing’ etc.) home
socialMedium the social network that the action occurs through (Eg: ‘twitter’ / ‘facebook’) facebook
currency underscore separated language and currency (Eg: for a Spanish language site in the US, this will be Esp_USD) Esp_USD

List of events

Event name Trigger Parameters
pageView on load of any page event
userID
pageType
sourceProdID (for product pages)
sourceCatgID (for product pages)
prodPrice
currency
addToCart on click of the ‘add to cart’ button or the equivalent action event
userID
pageType
sourceProdID
sourceCatgID
prodPrice
currency
buy on load of the order confirmation page event
userID
pageType
sourceProdID
sourceCatgID
prodQty
prodPrice
currency
Note: underscore separated for events with multiple products
carouselClick on click of a recommendation on the carousel event
userID
pageType
sourceProdID sourceCatgID
prodPrice
destProdID destCategID
prodPrice
posOfReco
widgetID
currency
carouselSwipe on swipe (or euivalent action) on a recommendation carousel event
userID
pageType
sourceProdID
sourceCatgID
widgetID
currency
addToWishlist on click of the ‘add to wishlist’ button or the equivalent action event
userID
pageType
sourceProdID
sourceCatgID
prodPrice
currency
placeOrder on click of the button that proceeds to the payment page event
userID
pageType
sourceProdID
sourceCatgID
prodQty
prodPrice
currency
Note: underscore separated for events with multiple products
removeFromCart on click of the ‘remove from cart’ button or the equivalent action on the cart event
userID
pageType sourceProdID
sourceCatgID
prodPrice
currency
removeFromWishlist on click of the ‘remove from wishlist’ button or the equivalent action on the wishlist event
userID
pageType
sourceProdID
sourceCatgID
prodPrice
currency
socialShare on click of the social share app icon event
userID
pageType
sourceProdID
sourceCatgID
prodPrice
socialMedium
currency

Below are the ways in which the pixels can be implemented on the web (desktop or mobile) and the iOS and Android apps.

Web Implementation (Desktop and Mobile)

The pixels can be triggered using one of the following methods:

Using vue_ai.js

Please include this script in all your product HTML pages:

<script type="text/javascript" src="http://<your-cloudfront-key>.cloudfront.net/vue_ai.js"> </script>

MSDtrack() is the function to be called for all the tracking pixel events. The arguments to be passed to this function is a javascript object (in key-value pairs). Each tracking event has its own arguments as shown below:

Examples

<body onload = "MSDtrack( 
   {    
    'event' : 'pageView', 
    'sourceProdID' : 'XYZ1234', 
    'sourceCatgID' : 'Tunics', 
    'prodPrice' : '499',
    'pageType' : 'PDP',
    'userID' : '1234'
   }
)">
</body>

<a onclick = "MSDtrack(
   {
    'event' : 'carouselClick', 
    'sourceProdID' : 'XYZ1234', 
    'sourceCatgID' : 'Tunics', 
    'destProdID' : 'ABC3456', 
    'destCatgID' : 'Tunics', 
    'posOfReco' : '4',
    'widgetID' : '0',
    'pageType' : 'PDP',
    'userID' : '1234'
   }
)">
</a>

Constructing the URL without using vue_ai.js

The following base url is to be hit using a GET call:
https://<your-cloudfront-key>.cloudfront.net

This base url is appended with the individual event name and it’s parameters separated by an ‘&’ (that are described in each inidividual pixel’s call below).

For instance, in the pageView pixel, the url will be in the following format:

https://<your-cloudfront-key>.cloudfront.net/pageView? url=<>&referrer=<>&uuid=<>&clicked=<>&sourceProdID=<>&sourceCatgID=<>& pageType=<>&prodPrice=<>&userID=<>

The Pixel Checker

We also provide a tool to check the pixel implementation during and after the integration. To use the pixel checker:

iOS Implementation

There will be an SDK that will be provided to the customer on request. The below documentation will be in reference to the SDK.

Note: Please refer to the PixelSDKIntegration branch as an example to see how you can implement the pixel into your code.

Device Support

  1. Drag the framework into your project and Xcode populates below dialog
  2. If you need to separate copy of framework within your Project directory, then make sure that you have selected “Copy items if needed”
  3. Make sure the framework appear in below places,
    • Clear the Search Path settings in Build Settings before adding the Framework, to avoid linker error
    • After successful integration of framework, We move on to Using the framework into existing application

Using Framework into Existing application:

Import the framework into your custom class as below, 

#!objective-C

    #import <MSDPixelSDK/MSDPixelSDK.h>

Code Snippet for configure Tracking Event Base URL:

#!objective-c

[[SDKUtilities sharedInstance] configuareSDKWithtrackingEventBaseURL:@"http://<insert your cloudfront key here>.cloudfront.net"];

Running SDK for iOS 9.0:

The app running on iOS 9 will no longer connect to a Meteor server without SSL. To connect to Meteor server without SSL, please use below instruction.

#!objective-c

In the app's info.plist, NSAppTransportSecurity [Dictionary] needs to have a keyNSAllowsArbitraryLoads [Boolean] to be set to YES

Below is a sample call for a pixel for the addToWishList event:

#!objective-c

 NSDictionary *paramDict = [NSDictionary dictionaryWithObjectsAndKeys: @"sourceProductID",@"sourceProdID",@"price",@"prodPrice", @"catagory Name", @"sourceCatgID", nil];
[[SDKUtilities sharedInstance] trackEvents:EVENTaddToWishlist withParams:paramDict];

Note: The other events need to be triggered in the same manner with the respective parametes as defined above (List of Events section)

Android Implementation

Initialising the SDK

Step 1

Initialize the SDK is to mention the cloudfront url and base url shared by MSD, in the manifest file. <meta-data android:name= "com.madtstreetden.baseUrl" android:value = "http://client.madstreetden.com/"/> <meta-data android:name= "com.madstreetden.logUrl" android:value = "http://<<insert your cloudfront key here>.cloudfront.net"/>

Step 2

Call the function MSDsdk.init with the application context as parameter

MSDTrackSdk.init(this.getApplicationContext());

Logging events

The parameter for logging the event is MSDPixel. Below is the sample for how to create the MSDPixel and add the key value to it. MSDPixel pixel = new MSDPixel(MSDEvents.PAGE_VIEW); pixel.setKeyValue(MSDKeys.SOURCE_PRODUCT_ID, "id"); pixel.setKeyValue(MSDKeys.SOURCE_CATEGORY_ID, "Tops"); The logEvent function can be called in three ways, as below:

  1. Log the event and receive the result in the callback ​
    public static void logEvent(@NonNull final MSDPixel data, @NonNull final MSDTrackInterfaces.LogListener listener)

    Example:

    MSDTrackSdk.logEvent(pixel, new MSDTrackInterfaces.LogListener() { @Override public void onSuccess(String result) { }

    @Override public void onFailure(String msg) { } });

  2. Log the event and check the result by enabling the result

    public static void logEvent(@NonNull final MSDPixel data)

    Example:

    MSDLog.setDebug(true); MSDTrackSdk.logEvent(pixel, new MSDTrackInterfaces.LogListener() { @Override public void onSuccess(String result) { }

    @Override public void onFailure(String msg) { } });

  3. Log the event in synchronous manner and receive the result as JSONObject (Note: This function should be called from a workerThread)

    @WorkerThread public static JSONObject logEventSync(@NonNull final MSDPixel data)

    Example:

    JSONObject obj = MSDTrackSdk.logEventSync(pixel);

    The result JSON Object will be in the following format,

    In case of success, {status: ‘success’} In case of Failure, { status: ‘failure’, error_code:‘101’, message:‘errorMessage’ }

Note: The other events need to be triggered in the same manner with the respective parametes as defined above (List of Events section)

python javascript