Getting Started¶

In this documentation you will find comprehensive guides and documentation to help you start working with the Oorjit AI API.

Oorjit AI has a free version which provide upto 1 Million recommendations per month. Create your free instant account at app.oorjit.ai, if you don’t have one yet.

For paid account which has not limits on number of recommendations, Please contact sales. You can start with free service and upgrade to paid service later.

How to integrate¶

Integration consist of two steps:

Sending interactions between items and users to Oorjit AI
Getting recommendations from Oorjit AI

Sending interactions¶

User interactions are the most valuable information for the algorithms in recommender engine. There are multiple kinds of interactions in the system. Currently we are tracking 3 type of interaction.

Product page view
Add to cart
Purchase

Product page view¶

It will be sent every time a user views detail of a product

A detail view of item PRODUCT_1 by user USER_1 can be send to the recommendation engin using REST call or JavaScript as shown below:

JavaScript

function downloadJSAtOnload() {
    m_k = 'Merchant key' // Merchant key from your https://app.oorjit.ai account
    event_type = "pageview",  // Possible values are pageview, addtocart, sale
    user_hash = "USER_1" // user id
    product = {
                id: 'PRODUCT_1', // Product id
                sku: 'PRODUCT_1_SUK', // Product SKU
                name: 'PRODUCT_1_NAME', // Product name
                price: '13065', // Product price
                quantity : 1,
                stype: "direct" // Possible values are widget, catalog, direct
              }
    var e, t = document.getElementsByTagName("script")[0]
    n = document.createElement("script")
    o = {
        k: m_k,
        t: event_type,
        u: user_hash,
        products: [product]
    }
    r = "https://ai-rec-api.oorjit.ai/track/event?d="+encodeURIComponent(JSON.stringify(o))
    n.defer = "defer", n.type = "text/javascript", n.src = r, t.parentNode.insertBefore(n, t)
}
if (window.addEventListener)
    window.addEventListener("load", downloadJSAtOnload, false);
else if (window.attachEvent)
    window.attachEvent("onload", downloadJSAtOnload);
else 
    window.onload = downloadJSAtOnload;

REST

POST /track/event HTTP/1.0
Host: ai-rec-api.oorjit.ai
Content-type: application/json

Body:
    {
        k: "Merchant key",
        t: "pageview",
        u: "USER_1",
        products: [{
                id: 'PRODUCT_1',
                sku: 'PRODUCT_1_SUK',
                name: 'PRODUCT_1_NAME',
                price: '13065',
                quantity : 1,
                stype: "direct"
            }]
    }

Fields are,

Field	Type	Deatils
m_k	String	Merchant key from your https://app.oorjit.ai account
event_type	String	Possible values are pageview, addtocart, sale. Use 'pageview' for page view interaction. Use 'addtocart' for sending add to cart interaction. Use 'sale' for sending sale interaction.
user_hash	String	Unique identifies for the customer. It is recommended to use hash value of unique identifier so the unique identifier won't get expossed.
product	Array	Multiple items can be added for 'sales' integraction. 'pageview' and 'addtocar' supports one item only.
id	String	Unique id of the product
sku	String	SKU of the product
name	String	Name of the product
price	Float	Price of the product without currency. You can set the currency from your https://app.oorjit.ai account
quantity	Intiger	Set as 1 for product view. This field can be used to specify product quantity while sending 'sale' interaction
stype	String	Use the value 'direct' if the user reached this product not from any recommended item by Oorjit AI. If the customer clicked this product from recommendation widget, use the value 'widget'. If the customer reached this product from the sorted catalog using Oorjit AI recommendation, use the value 'catalog'

JavaScript optimisation

JavaScript integration send the data to the server as GET request. This is for avoiding the overhead of loading additional javascript. stringify() is applied to JSON data and encoded using encodeURIComponent(). Data is send using the GET variable 'd'.

We use a cookie (oorjit_ai_sess) to track users in your website. This cookie will set while user visiting the site first time. System use this cookie to track activities even if the customer not logged in.

Add to cart¶

It will be sent every time a user add products to cart. Sending a add to cart event is very similar to Product page view

User USER_1 add product PRODUCT_1 to the cart can be send as follows.

JavaScript

function downloadJSAtOnload() {
    m_k = 'Merchant key' // Merchant key from your https://app.oorjit.ai account
    event_type = "addtocart",  // Possible values are pageview, addtocart, sale
    user_hash = "USER_1" // user id
    product = {
                id: 'PRODUCT_1', // Product id
                sku: 'PRODUCT_1_SUK', // Product SKU
                name: 'PRODUCT_1_NAME', // Product name
                price: '13065', // Product price
                quantity : 1,
                stype: "direct" // Possible values are widget, catalog, direct
              }
    var e, t = document.getElementsByTagName("script")[0]
    n = document.createElement("script")
    o = {
        k: m_k,
        t: event_type,
        u: user_hash,
        products: [product]
    }
    r = "https://ai-rec-api.oorjit.ai/track/event?d="+encodeURIComponent(JSON.stringify(o))
    n.defer = "defer", n.type = "text/javascript", n.src = r, t.parentNode.insertBefore(n, t)
}
if (window.addEventListener)
    window.addEventListener("load", downloadJSAtOnload, false);
else if (window.attachEvent)
    window.attachEvent("onload", downloadJSAtOnload);
else 
    window.onload = downloadJSAtOnload;

REST

POST /track/event HTTP/1.0
Host: ai-rec-api.oorjit.ai
Content-type: application/json

Body:
    {
        k: "Merchant key",
        t: "addtocart",
        u: "USER_1",
        products: [{
                id: 'PRODUCT_1',
                sku: 'PRODUCT_1_SUK',
                name: 'PRODUCT_1_NAME',
                price: '13065',
                quantity : 1,
                stype: "direct"
            }]
    }

Purchase¶

It will be sent every time a user complete a purchase.

User USER_1 purchase 1 quntity of product PRODUCT_1 and 2 quntity of product PRODUCT_2 can be send as follows.

JavaScript

function downloadJSAtOnload() {
    m_k = 'Merchant key' // Merchant key from your https://app.oorjit.ai account
    event_type = "sale",  // Possible values are pageview, addtocart, sale
    user_hash = "USER_1" // user id
    products = [{
                id: 'PRODUCT_1', // Product id
                sku: 'PRODUCT_1_SUK', // Product SKU
                name: 'PRODUCT_1_NAME', // Product name
                price: '13065', // Product price
                quantity : 1,
                stype: "direct" // Possible values are widget, catalog, direct
              },
              {
                id: 'PRODUCT_2', // Product id
                sku: 'PRODUCT_2_SUK', // Product SKU
                name: 'PRODUCT_2_NAME', // Product name
                price: '130.66', // Product price
                quantity : 2, // Quantity purchased
                stype: "direct" // Possible values are widget, catalog, direct
              }
              ]
    var e, t = document.getElementsByTagName("script")[0]
    n = document.createElement("script")
    o = {
        k: m_k,
        t: event_type,
        u: user_hash,
        products: products
    }
    r = "https://ai-rec-api.oorjit.ai/track/event?d="+encodeURIComponent(JSON.stringify(o))
    n.defer = "defer", n.type = "text/javascript", n.src = r, t.parentNode.insertBefore(n, t)
}
if (window.addEventListener)
    window.addEventListener("load", downloadJSAtOnload, false);
else if (window.attachEvent)
    window.attachEvent("onload", downloadJSAtOnload);
else 
    window.onload = downloadJSAtOnload;

REST

POST /track/event HTTP/1.0
Host: ai-rec-api.oorjit.ai
Content-type: application/json

Body:
    {
        k: "Merchant key",
        t: "addtocart",
        u: "USER_1",
        products: [{
                id: 'PRODUCT_1',
                sku: 'PRODUCT_1_SUK',
                name: 'PRODUCT_1_NAME',
                price: '13065',
                quantity : 1,
                stype: "direct"
            },{
                id: 'PRODUCT_2',
                sku: 'PRODUCT_2_SUK',
                name: 'PRODUCT_2_NAME',
                price: '13.66',
                quantity : 2,
                stype: "direct"
            }]
    }

Getting recommendations¶

Once the tracking API get enought data (Interactions from aleast 2K customers), You can use recommendation API to get recommendation for each users.

Get recommendation for the user USER_1

REST

POST /serve HTTP/1.0
Host: ai-rec-api.oorjit.ai
Content-type: application/json

Body:
    {
        merchant_id: 'Merchant key'
        user_id: "USER_1" 
    }

Request fields are,

Field	Type	Deatils
merchant_id	String	Merchant key from your https://app.oorjit.ai account
user_id	String	Unique identifies for the customer. It is recommended to use hash value of unique identifier. For a specific user, this should be same as the user_id send to tracking API

Sample Response

   {
   "status":"Success",
   "message":"",
   "results":[
        {
         "product_seq_id": 123,
         "product_id": "1234", 
         "score": .88
         },        
         {
         "product_seq_id": 456,
         "product_id": "1235", 
         "score": .85
         },        
         {
         "product_seq_id": 1000,
         "product_id": "1236", 
         "score": .75
         }
    ]
   }

Response fields are,

Field	Type	Deatils
status	String	Possible values are 'Success' & 'Error'
message	String	If 'status' field is 'Error', This field contain error message, Otherwise empty
results
product_seq_id	Intiger	No use for now. It is used by the recommendations engin to identify the product
product_id	String	Actual product id which you have send to tracking API
score	Float	A value between 0 and 1. Greater the value, the customer more likely to love the product. The product listing is already sorted based on this value in decenting order

Info

It is reommended to call this API from your server and render the result to browser. We are activily working on creating SDK for commmon languages.

Conversion tracking¶

You can view detailed reports on Clicks & Conversion from recommendations in the Oorjit AI dashboard. To get this information in dashboard you need to send 'stype' field with tracking API call.

Click tracking¶

To implement this in product page view, you can append a GET varible (Eg. rec_source=widget/catalog) to the url of products listed in the recommendation widget and sorted catalog. For recommendation widget, use the value 'widget'. For sorted catalog, use the value 'catalog'. Then use this GET varible (rec_source) to assign value to 'stype' while sending data to tracking API.

Cart tracking¶

We can use the same GET varbile that used for click tracking and set 'stype'.

Sale tracking¶

The GET varible used in click & cart tracking is not available at the checkout stage. So we need to keep the list of products clicked from recommendation widget or sorted catalog in browsers's local storage and use that information to set 'stype' while sending sales tracking.

Info

We are activily working on JavaScript SDK to add sales conversion tracking using Browser's Local storage.