Writing Your Own Drawing Callback

From Easyrec Wiki
Jump to: navigation, search

This guide explains how to implement a drawing callback for the JavaScript API. The drawing callback is used to display recommendations fetched from the easyrec server in JSON.


Setup a Test Environment

First of all, it is assumed that you have a browser that provides a debugging console and allows inspecting HTTP traffic. For example, use Google Chrome or Firefox with the Firebug plugin.

You also need an easyrec Tenant for which rules have already been created. If you don't already have one, create a DEMO tenant on your easyrec server or in our demo instance.

If there aren't any rules present for that tenant, use this JavaScript code to setup a test environment.

<!-- change this block to your tenants value, also change the javascript location when you are not localhost -->
<script type="text/javascript" src="http://localhost:8080/api-js/easyrec.js"></script>
<script type="text/javascript">
   var apiKey = "8ab9dc3ffcdac576d0f298043a60517a";
   var tenantId = "JS_API_TEST";
</script>

<script>
   for (var x = 1; x <= 12; x++) {
       var userID = x;

       easyrec_sendAction("view", {userId:userID,itemId:"1",
           itemUrl:"http://example.com/item/1222",
           itemDescription:"easyrec Fan Poster",
           itemImageUrl:"http://example.com/pics/poster.png"});


       easyrec_sendAction("view", {userId:userID,itemId:"2",
           itemUrl:"http://example.com/item/1220",
           itemDescription:"easyrec DVD",
           itemImageUrl:"http://example.com/pics/dvdcover.png",
       });

       easyrec_sendAction("view", {userId:userID,itemId:"3",
           itemUrl:"http://example.com/item/1220",
           itemDescription:"easyrec T-Shirt",
           itemImageUrl:"http://example.com/pics/tshirt.png",
       });
   }
</script>

Save this script to a TEST.html file and open it in a browser. Now go to the easyrec administration interface and check if everything worked. You should see a graph similar to this one:

Action count.png

If you are working on your own server, you can trigger the calculation of rules. Navigate to the easyrec administration interface of the easyrec web application and click the "start plugin" button for your tenant. On our demo instance you have to wait for the daily rules calculation job.

Now you have some rules to start developing a drawing callback.


Test the Environment

create a html file with this content to get started:

<!-- change this block to your tenants value, also change the javascript location when you are not localhost -->
<script type="text/javascript" src="http://localhost:8080/api-js/easyrec.js"></script>
<script type="text/javascript">
   var apiKey = "8ab9dc3ffcdac576d0f298043a60517a";
   var tenantId = "JS_API_TEST";
</script>

<script>
   easyrec_getRecommendations('otherusersalsoviewed', {itemId:"1", drawingCallback:'myCustomDrawingCallback'});
   
   function myCustomDrawingCallback(json) {
       console.log(json);
   }
</script>


When you open this file in a browser with a console like Firefox with firebug or Chrome with the chrome console you will see the response of the API call. This is a very useful piece of information because it tells you that this call returns a recommendation. Recommendations response.png

Writing the Actual Callback

Now you can start coding the callback. In this tutorial we will not use jQuery or other frameworks which would make the scripting a lot easier. Check their documentation about processing JSON if you use any of them.

Use the following code as a template for your drawing callback:

   function myCustomDrawingCallback(json) {
       if ("undefined" == typeof(json.error)) { // if no error show recommendations

           try {
               var items = json.recommendeditems.item;
           } catch(e) {
               return;
           }

           /* when the object is already in array format, this block will not execute */
           if ("undefined" == typeof(items.length)) {
               items = new Array(items);
           }

           // display recommendations in the DIV layer 'recommendation'
           if (items.length > 0) {
               for (x = 0; x < 15 && x < items.length; x++) {
                   //send actions of a known item 
                   console.log(items[x]);
               }

           }
       }
   }

It will log every single recommended item to your debug console. Now you only have to adjust the console.log(items[x]); line. items[x] contains all information about the x-th recommended item. Use firebug to see the available fields you can use. On the firebug screenshot you can see that my recommendation object has the following fields:

The final document looks like this and simply lists the recommended items.

<!-- change this block to your tenants value, also change the javascript location when you are not localhost -->
<script type="text/javascript" src="http://localhost:8080/api-js/easyrec.js"></script>
<script type="text/javascript">
   var apiKey = "8ab9dc3ffcdac576d0f298043a60517a";
   var tenantId = "JS_API_TEST";
</script>


<script>
   easyrec_getRecommendations('otherusersalsoviewed', {itemId:"1", drawingCallback:'myCustomDrawingCallback'});
   function myCustomDrawingCallback(json) {
       if ("undefined" == typeof(json.error)) { // if no error show recommendations

           try {
               var items = json.recommendeditems.item;
           } catch(e) {
               return;
           }

           /* if the object is already in array format, this block will not execute */
           if ("undefined" == typeof(items.length)) {
               items = new Array(items);
           }
           var recommendationHTML= "Things you should buy:";
           // display recommendations in the DIV layer 'recommendation'
           if (items.length > 0) {
               for (x = 0; x < 15 && x < items.length; x++) {
                   //send actions of a known item
                   recommendationHTML += "<a href='"+items[x].url+"'>" + 
                         items[x].description+"</a><br>";
               }
               document.getElementById("recommendations").innerHTML =recommendationHTML;
           }
       }
   }
</script>

<div id="recommendations"></div>
Personal tools
Namespaces

Variants
Actions
easyrec documentation
Navigation
Toolbox