JavaScript

JavaScript is used for client side calls in a browser. All JavaScript calls to Avail are asynchronous.

Invocation

There are four basic steps when using the JavaScript API.
1) Add a script tag

The X:s are replaced with the customer identifier.
2) Create an Emark-object:

var emark = new Emark();

3) Invoke one or several methods:

myResponse = emark.getRecommendations("myTemplate",["ProductId:myProductId"]);

4) Place the code to execute when the response has been returned from the Avail as an argument within a commit method:

emark.commit(function() {
//Get presentation data for the products in return array and render the result
});

Note that as calls are asynchronous, the commit method needs to have triggered for you to be sure that the call has gone trough. See Sample Page tab for sample code. Client side encrypted JavaScript calls are supported (change http to https). The calls are server-side limited to a size of 2000 characters as to comply with the IE restriction of 2083 characters in get-requests. Only one commit is allowed per HTML-page.

Responses

The responses are held in member variables.

For methods that returns Status the variable values holds the status of the operation:

myResponse.values;

For methods that returns Predictions the variable values holds the recommendations as an array:
If ColumnNames are not requested - which is the most common case - value is a single dimensional array:

myResponse.values[0];

If ColumnNames are requested - i.e. predictions meta data such as price and title - values is a two dimensional array:

myResponse.values[0][0];

The TrackingCode - which is used to log user actions - is returned in the variable trackingcode:

myResponse.trackingcode;

Debugging

The constructor takes an optional boolean argument. If set to true debug info is rendered as innerHTML in a tag with the id __avail_log__, for example a div-tag:

For the server error response copy the Fetch URL rendered as debug info and paste it as a URL in a browser.

Arrays

Arrays can be denoted in two ways:

1) ["value1", "value2"]
2) Array("value1", "value2")

If a value contains delimiters such as a comma, then the whole value needs to be enclosed with apostrophes. Example:

["value,1", "value,2"]

The most common scenario where commas are present in arrays are when working with dynamic parameters. Example:

["replace andcat in subtemplate 1 with c14,c7", "append rule in subtemplate 1 with Price > 30"]

Samples

Requesting Recommendations

1) Add a script tag that loads the Avail BEM script - Line 3
2) The body tag must contain an onload event that calls the javascript with the Avail BEM code, for example populatePredictions - Line 15
3) In the Avail BEM function:
  - Create an eMark object. - Line 6
  - Make your recommendations requests. Can be one or several requests. In this case recommendations are made for the product id myProductId - Line 7
  - Call the commit method and in its argument place code for rendering the returned recommendations - Line 8-10

 1 <html>
 2 <head>
 3 <script type="text/javascript" charset="UTF-8" src="http://service.avail.net/2009-02-13/dynamic/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/emark.js"></script>
 4 <script type="text/javascript">
 5 function populatePredictions(){
 6     var emark = new Emark();
 7     var recommendedProducts = emark.getRecommendations("myTemplate", ["ProductIds:myProductId1,myProductId2"]);
 8     emark.commit(function() {     
 9             recommendedProducts //Get presentation data for the products in this array and render the result
10     });
11 }
12 </script>
13 </head>
14 
15 <body onload="populatePredictions();">
16     <b>Test Page</b>
17 </body>
18 </html>

Logging

For logging products clicked on or added to cart Avail BEM requires the tracking code that is returned with the recommendation response ([response object].trackingcode).

Sample 1
Typically a clicked on product takes you to a product detail page. In this case the most common solution is to send the tracking code as a posted variable or a query string to the product detail page and register the click event when the recommendations are requested.

var recommendedProducts = emark.getRecommendations("myTemplate", ["ProductId:myProductId"]);
if (trackingcode.length > 0){
    emark.logClickedOn(myProductId, trackingcode);
}
emark.commit(function() {     
    recommendedProducts //Get presentation data for the products in this array and render the result
}

Sample 2
Typically an add-to-cart uses a JavaScript to submit the data to the server. In this case it is common to log the add-to-cart event to Avail BEM after the add-to-cart JavaScript is finished.

emark.logAddedToCart(myProductId, trackingcode);
emark.commit();

Sample 3
Logs the event that a user makes a purchase.

emark.logPurchase("User1", ["Prod1", "Prod2", "Prod3"], ["Price1", "Price2", "Price3"]);
emark.commit();

Dynamic Parameters

Through the use of dynamic parameters you can pass prediction arguments run-time to templates.

var prodRecs = emark.getRecommendations("myTemplate",["ProductIds:myProductId1,myProductId2","UserId:myUserId","Phrase:Harry Potter"],["append rule in subtemplate 1 with productLeftHanded='Y'", "append orcat in subtemplate 1 with c5"] , ["ProductId", "Title"]);

Rendering Recommendations

Avail BEM can return the recommendations in two ways:

as an ordered set of product ids

as an ordered set of product ids with meta data
Returning the meta data with the recommendations has the advantage that it saves you a trip to your servers. On the negative side the product data in Avail BEM is updated usually every 24 hours, which means that the recommendation meta data can get out of sync with the data on your servers.

Recommendations as a set of product ids

This requires retrieving the presentation data from your servers. There are several ways to accomplish this. Here we will cover two ways to do it.
iframe
Create a small page the renders the recommendations. This page takes of a list of products as argument. Load this page in an iframe placed on the page. Sample
Ajax
Retrieve and present the presentation data using Ajax. Sample

Recommendations with meta data

Let a javascript place the recommendations on the page. Sample