Product Information Query

What is a Product Information Query and when is it used?

Sometimes the product data returned by the ATG Recommendations service is not enough. The preferred way to get more data about a recommended product is through a web service run by the customer site. However, sometimes this data is unavailable or difficult to retrieve and for those times ATG Recommendations provides a mechanism to retrieve product information from its servers.

How is this data retrieved?

Data should only be retrieved from this service through the use of the CleverSet.getProductInfo() function.

• CleverSet.getProductInfo(data_items, product_ids, callback_function)

  Queries the ATG Recommendations servers for more information on a set of products. The callback function is called with the returned data.

Parameters

data_items—an array of the types of data requested

product_ids—an array of product ids to get the information about

callback_function—the name (string) of a function in the CleverSet namespace which is called with the returned product information

Returns

Void—The callback function is called asynchronously with the requested data

What data may be requested?

Only certain data items may be requested from the ATG Recommendations Product Information service. In addition, this list may be shortened if not all of these items are present in the product catalog last uploaded to ATG Recommendations servers. The list of items that may be requested if they have been specified in a product catalog is limited to the following list.

Data Item Name	Description	Type
productUrl	URL of the product detail page	String
imageUrl	URL of the thumbnail image	String
desc	Text description	String
name	Product Title	String
brand	Brand	String
category	Hierarchical category	String
inStock	If product is in stock	Boolean
expire	Date and Time product expires	String
price	Price	Double

Note that some data may not come back exactly the same way it was entered into the product catalog. For example, category will always be returned in all caps. If this is a problem it is suggested you implement your own web service to retrieve the data.

How is data returned?

The callback_function passed to CleverSet.getProductInfo() will be called with a data object as its only paramter. This object is a hash where the keys are the product ids you requested data for and the values are data hashes. The data hashes for each product id contain key/value pairs where the key is the data item you requested and the value is its result.

Please Note: Your callback function must be registered as part of the CleverSet namespace. The string passed to CleverSet.getProductInfo() for the callback function will have the string CleverSet. prepended to it in all cases.

If you request a valid field but it is not found, it will return with a value null.

A return will look something like this:

CleverSet.my_callback_function({
  "pid.1" : {
    "imageUrl" : "http://www.sitename.com/images/pid.1.jpg",
    "inStock" : true,
    "price" : 10.50
  },
  "pid.2" : {
    "imageUrl" : "http://www.sitename.com/images/pid.2.jpg",
    "inStock" : false,
    "price" : 0.50
  }
});

Example

You want to display the description of the products in your renderer below their titles. You are requesting three product recommendations on your page so your renderer needs the descriptions for three products. Because the request happens asyncronously you must create a place for the description without the data to go into it. You must also register a function to handle the returned data.

You write a function like this, which places the returned description into some <div> tags you will create in your renderer. You give the <div> tags easy to locate ids that contain the product id.

CleverSet.my_callback_function = function (returned_object) {
  var destination_div;

  // iterate through the returned product ids
  for (product_id in returned_object) {
    // get the destination for the description by using that easy id you gave them
    destination_div = document.getElementById('description_for_' + product_id);

    // put the returned description field for this product id into the selected DIV tag
    destination_div.appendChild(document.createTextNode(returned_object[product_id]['desc']));
  }
};

Then, in your renderer, once you create your destination <div> tags you call CleverSet.getProductInfo() with the desired information. For the sake of example here, we’ll use constants for the product ids instead of variables.

CleverSet.getProductInfo(["pid.1", "pid.2", "pid.3"], ["desc"], "my_callback_function");