Docs

Unbxd Recommendations - Java SDK

The Java SDK lets you easily configure Unbxd APIs in your website and accomplish the 3-step process to integrate Unbxd Recommendations in your eCommerce store.

Prerequisites

Before you start integrating, make sure that you have:
  • An Unbxd Recommendations account
  • Set up your console

Installing the SDK Library

If you are using Maven, you can simply install the SDK library by including the following dependency in the pom.xml file of your existing project:

<dependency>  
    <groupId>com.unbxd</groupId>
    <artifactId>unbxd-java-sdk</artifactId>
    <version>2.2</version>
</dependency>
  • version: this specifies the version of Maven.

Initializing the SDK

You can initialize the SDK using your Unbxd in the following manner:

Unbxd.configure ("<Site_Key>", "<API_Key>", "<Secret_Key>");  

If your store is on HTTPS, initialize in the following manner:

Unbxd.configure("Site_Key", "API_Key", "Secret_Key", true);
  • true: specifies an HTTPS protocol.

1. Uploading your Feed

Once your console is set up, you can upload your Product Feed.

A Product Feed contains information about all products in your store. All Unbxd algorithms work around the Product Feed which must be sent to us in a specific format.

Learn more about Product Feed.

Full Feed Upload

To replace the existing Product Feed with a new one, or if you are uploading your Product Feed for the first time, you need to make a .push(true) call as shown below:

Format:

FeedResponse response=Unbxd.getFeedClient().addSchema("fieldname", Datatype.DATATYPENAME).addProduct(newFeedProduct("sku id1",pid1).addProduct(newFeedProduct("skuid2", pid2).push(true);  
  • addSchema: adds a custom field to the schema.
  • fieldname: name of the custom field.
  • Learn about Unbxd schema.
  • DATATYPENAME: the datatype.
  • addProduct: adds new products or pid.
  • newFeedProduct: denotes a new product.
  • skuid1: SKU ID of a product.
  • pid1: product ID of the added product.
  • push(true): specifies a full feed upload.
Example:
FeedResponse response=Unbxd.getFeedClient().addSchema("color", Datatype.TEXT).addProduct(newFeedProduct("whit2243211",nik0122).addProduct(newFeedProduct("blck2443211", adi4321).push(true);  

Learn more about Full Feed Upload.

Incremental Upload

For incremental changes or updates, you can perform Incremental uploads to your existing Product Feed.

You can perform the following incremental actions:
  • Add
  • Update
  • Delete

Learn more about Incremental Feed Upload.

Adding your products

Once you have successfully uploaded your Product Feed, you can add products to it by making a call as shown below:

Format:
Map<String, Object> pid1 = new HashMap<String, Object>();  
pid1.put("fieldname1", "field value");  
pid1.put("fieldname2", "field value");  
  • .put: is used to adds fields to the corresponding products
Example:

The below lines of code will upload products pid1 and pid2. Here, a custom field "color" is added.

Map<String, Object> pid1 = new HashMap<String, Object>();  
pid1.put("title", "Nike Men's Flex 2015 Running Shoe"); //Title of the product  
pid1.put("color", "black"); //A custom field  
pid1.put("brand", "Adidas");  
pid1.put("category", "Sports Shoes");  
pid1.put("price", 1195);  
Map<String, Object> pid2 = new HashMap<String, Object>();  
pid2.put("title", "biker jacket");  
pid2.put("color", "brown");  
pid2.put("brand", "Louis Vuitton ");  
pid2.put("category", "jackets");  
pid2.put("price", 5499);
Response

Once you are done uploading your products, Unbxd server will return you a response similar to the one shown below:

FeedResponse response = Unbxd.getFeedClient().addSchema("color", DataType.TEXT).addProduct(new FeedProduct("skuid1", pid1)).addProduct(new FeedProduct("skuid2", pid2)).push(false);

Here,

  • .push(false): specifies an incremental upload.
addproduct function is the default feed action employed in a Full feed upload.

Updating your Product

To update your product field, you need to make an update call as shown below:

Format:
Map<String, Object> pid1=new HashMap<String,Object();  
pid1.put("fieldname", "new fieldname");
Example:
Map<String, Object> pid1=new HashMap<String,Object();  
pid1.put("title", "white shirt");  

Response
FeedResponse response = Unbxd.getFeedClient().updateProduct(newFeedProduct("skuid1", pid1).push(false);  

.updateProduct: is used to update the field values.

Here, the field "title" of pid1 is replaced with "white shirt". Usually, this action is used for updating the quantity field of a product.

Deleting Products

To delete a product from your existing Product Feed, you need to make a delete call. This feed action also allows you to delete multiple products from your Product Feed. You can delete an existing product as shown below:

Format:
FeedResponse response = Unbxd.getFeedClient().deleteProduct("skuID").push(false);
  • .deleteProduct(): deletes the product using its SKU ID.

Configuring Multi-valued Fields

Custom fields are those fields that are not a part of Unbxd Feature fields. While uploading your feed, you can configure custom fields to accept multiple values as shown below:

Learn more about multi-valued fields.

Format:
.addSchema("fieldname", DataType.DATATYPENAME, multivalue, autosuggest)
Here,
Example:
.addSchema("color", DataType.TEXT, true, false)

Understanding Feed Response

Understanding the feed response is as essential as making an API call. The API response will give you processing status and message about every request call.

Parameter() Description
.getStatusCode() 200 if success.
.getMessage() Get error message if any.
.getUploadID() ID for the upload request.
.getUnknownSchemaFields()List of fields whose schema was unknown if any.
.getfieldErrors Errors that occurred at a field level. This consists of .getfieldName, .getfieldValue, .getdataType, and .ismultiValued.
.getfieldName() Name of the field.
.getfieldValue()The field value with validation error.
.getdataType()The datatype of the field.
.ismultiValue()Identifies if the field is single valued or multi-valued.
.getErrorCode()Identifies if the field is single valued or multi-valued. True if field is multi-valued.

2. Integrating Analytics

Once you have successfully uploaded your Product Feed, your next step is to integrate Unbxd Analytics in your store. This can be done in two ways:

  1. HTML metatags.
  2. RESTful APIs.

Learn more about Unbxd Analytics APIs.

Integrating Recommendation Widgets

You can integrate Unbxd Recommendations and generate product recommendations for each widget by configuring the UnbxdRecommendation client. This client helps you make recommendation API calls to our servers. In the following sections, you will learn how to configure API calls for each recommendation widget:

It is highly recommended that you avoid integrating the Viewed also Viewed and Bought also Bought widget on the same PDP (Product Detail Page). This would prevent the widgets from showing duplicate products in the widgets. This scenario may arise right after integrating the widgets, due to the lack of analytics data.

Recently Viewed

The following code will configure the UnbxdRecommendation client to fetch products that were recently viewed by the visitor:

RecommendationResponse response = Unbxd.getRecommendationsClient().getRecentlyViewed(uid,"100.0.0.1");  

Here,

  • uid: value of the cookie : "unbxd.userId"

  • "100.0.0.1": IP address

Recommended For You

The following code will configure the UnbxdRecommendation client to fetch recommended products for your visitor:

RecommendationResponse response = Unbxd.getRecommendationsClient().getRecommendedForYou(uid, "100.0.0.1");  

More Like This

The following code will configure the UnbxdRecommendation client to fetch products similar to the product being viewed by the visitor:

RecommendationResponse response = Unbxd.getRecommendationsClient().getMoreLikeThis("sku1", uid, "100.0.0.1");  

Here,

  • sku1: the SKU ID of the product

Viewed Also Viewed

The following code will configure the UnbxdRecommendation client to fetch products viewed by other visitors who were previously on the current (Product Detail Page) PDP:

RecommendationResponse response = Unbxd.getRecommendationsClient().getAlsoViewed("sku1", uid,"100.0.0.1"); 

Bought Also Bought

The following code will configure the UnbxdRecommendation client to fetch products bought by other visitors:

RecommendationResponse response = Unbxd.getRecommendationsClient().getAlsoBought("sku1", uid, "100.0.0.1");  

Homepage Top Sellers

The following code will configure the UnbxdRecommendation client to fetch top selling products on the Homepage:

RecommendationResponse response = Unbxd.getRecommendationsClient().getTopSellers(uid, "100.0.0.1");

Category Top Sellers

The following code will configure the UnbxdRecommendation client to fetch top selling products of a particular category:

RecommendationResponse response = Unbxd.getRecommendationsClient().getCategoryTopSellers("Shoes", uid, "100.0.0.1");  

Here,

  • shoes: is the category

Brand Top Sellers

The following code will configure the UnbxdRecommendation client to fetch top selling products of a particular brand:

RecommendationResponse response = Unbxd.getRecommendationsClient().getBrandTopSellers("Adidas", uid, "100.0.0.1");  

Here,

  • Adidas: is the Brand

PDP Top Sellers

The following code will configure the UnbxdRecommendation client to fetch top selling products on a particular Product Detail Page (PDP):

RecommendationResponse response = Unbxd.getRecommendationsClient().getPDPTopSellers("sku1", uid, "100.0.0.1");  // uid is value of the cookie : "unbxd.userId"  

Cart Recommendation

The following code will configure the UnbxdRecommendation client to fetch recommended products for the products added to cart:

RecommendationResponse response = Unbxd.getRecommendationsClient().getCartRecommendations(uid, "100.0.0.1");