JavaScript API v0.97

From Easyrec Wiki
Jump to: navigation, search


Contents

Initialization

The easyrec API-JS is able to receive actions from or send recommendations to your web application via the JSON API by integrating a small snippet of javascript code:

<script
  src='http://demo.easyrec.org:8080/api-js/easyrec.js'
  type='text/javascript'>
</script>

The API Key can be defined using the code snippet below. In the management section you can create an easyrec instance specifically for your webpage and choose an arbitrary name for it. Insert this name as tenantId in the code snippet below:

<script type='text/javascript'>
  var apiKey      = "YOUR_APIKEY";
  var tenantId    = "YOUR_TENANT_ID";
</script>


Sending Actions

To send actions to easyrec the javascript function 'easyrec_sendAction' has to be called with the following parameters:

<!--
Useage : easyrec_sendAction(actionType,parameters);
         easyrec_buy(parameters);    // same as easyrec_sendAction("buy",parameters);
         easyrec_view(parameters);   // same as easyrec_sendAction("view",parameters);
         easyrec_rate(parameters);   // same as easyrec_sendAction("rate",parameters);
Example:
-->
 
<script type='text/javascript'>
           easyrec_sendAction("buy",{userId:"",
                                    itemId:"1222",
                                    itemUrl:"http://example.com/item/1222",
                                    itemDescription:"Easyrec Fan Poster",
                                    itemImageUrl:"http://example.com/pics/poster.png"});
</script>

Parameters

The first parameter actionType specifies the Action Type:

view
This action should be used whenever a user views an item.
buy
This action should be used whenever a user buys an item.
rate
This action should be used whenever a user rates an item.
%YOUR_ACTION_TYPE%
If you created your own action type in the Admin GUI you can use this function to send actions for it. Just set the first parameter of the easyrec_sendAction Function to your action type.

The second parameter parameters specifies the Action parameters for the JSON API call:

itemId
required

A requried item Id to identify an item on your website. (e.g. "ID001")

itemDescription
required

A required item description that is displayed when showing recommendations on your Website. (e.g. "Snakes on a Plane")

itemUrl
required

A required item url that links to the item page on your Website.

userId
optional

An optional anonymised id of a user. (e.g. "24EH1723322222A3")

sessionId
optional

A optional session id of a user. If this parameter is not provided the script will create a session id and use it for the rest of the user's session.

itemImageUrl
optional

An optional item image URL that links to a image of the item.

actionTime
optional

An optional action time that overwrites the current timestamp of the action. The time/date format is "dd_MM_yyyy_HH_mm_ss" (e.g."01_01_2009_23_59_59").

itemType
optional; default:ITEM

An optional name for the item type if that name does not exist on your easyrec tenant the action will not be saved. If you dont use this parameter the item type ITEM will be used. This item type is created automatically when you create the tenant.

actionValue
optional

When you use custom action types with values you can use this parameter to send the value.

Receiving Recommendations

To receive recommendations from easyrec the javascript function 'easyrec_getRecommendations' has to be called with the following parameters:

<!--
Usage : easyrec_getRecommendations(recommendationType,parameters);
 
// same as easyrec_getRecommendations("otherusersalsoviewed",parameters);
easyrec_otherUsersAlsoViewed(parameters);

// same as easyrec_getRecommendations("otherusersalsobought",parameters);
easyrec_otherUsersAlsoBought(parameters);

// same as easyrec_getRecommendations("itemsratedgoodbyotherusers",parameters);
easyrec_itemsRatedGoodByOtherUsers(parameters);

// same as easyrec_getRecommendations("recommendationsforuser",parameters);
easyrec_recommendationsForUser(parameters);

// same as easyrec_getRecommendations("relateditems", parameters);
easyrec_relatedItems(parameters);

Example:
-->

<script type='text/javascript'>
            easyrec_getRecommendations("otherusersalsoviewed",{userId:"USER48",
                                       itemId:"1222",
                                       drawingCallback:"drawRecommendationList"});
</script>

At most 15 items are returned, results are sorted by relevance.

Parameters

The first parameter recommendationType specifies the Action Type:

otherusersalsoviewed
Users who viewed the specified item also viewed the returned items.
otherusersalsobought
Users who bought the specified item also bought the returned items.
itemsratedgoodbyotherusers
Users who rated the specified item high did the same with the the returned items.
recommendationsforuser
This recommendation shows items to a given user id.(so the userId parameter is mandatory) The latest items that where viewed by the given user are used to find items that where also viewed by other users. If a user has no viewing history or the viewed items have no items that where viewed by other users, an empty list is returned.
relatedItems

This API is used to return rules generated by easyrec Plugins. At most 15 items are returned, results are sorted by relevance.

The second parameter parameters specifies the recommendation parameters for the JSON API call:

itemId
required

A requried item id to identify an item on your Website. (e.g. "ID001")

drawingCallback
required

The name of the Drawing Callback Function for the Json Request

numberOfResults
optional; default:10

An optional parameter to determine the number of results returned. (Default: 10)

userId
optional

An (optional) anonymised id of a user (e.g. "24EH1723322222A3").
If this parameter is provided items viewed by this user are suppressed.

itemType
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.) you are looking for. If not supplied the default value ITEM will be used.

requestedItemType
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

basedOnActionType
optional; default:VIEW

An optional type of an action (e.g. VIEW, BUY, RATE, etc.) used for filtering recommendations for user. The recommendations you will get are only based on this actions.

assocType
optional

If you want to get recommendations for a specific assoc type you can use the relatedItems recommendationType and set this value to the assoc type you want to load.

Receiving Cluster Related Information

load all cluster

If you want to load all clusters of your tenant you can use the following function:

<!--
Usage : easyrec_cluster(parameters);

Example:
-->

<script type='text/javascript'>
            easyrec_cluster{drawingCallback:"drawRecommendationList"});
</script> 

The parameter parameters specifies the recommendation parameters for the JSON API call:

drawingCallback
required

The name of the Drawing Callback Function for the Json Request

load items of cluster

If you want to load all items of a Cluster you can use the following function:

<!--
Usage : easyrec_itemsInCluster(parameters);

Example:
-->

<script type='text/javascript'>
            easyrec_itemsInCluster({clusterId:"SUMMERSALE", drawingCallback:"drawRecommendationList"});
</script> 

The parameter parameters specifies the recommendation parameters for the JSON API call:

clusterId
required

The response will contain the items of the cluster with the required id used here. Note: the clusterId is the name of the cluster.

drawingCallback
required

The name of the Drawing Callback Function for the Json Request

numberOfResults
optional

An optional parameter to determine the number of results returned. (e.g. 10)

strategy
optional

An optional parameter that allows you to specify a strategy based on which the items are selected from the given cluster. Valid values are RANDOM, NEWEST and BEST.

RANDOM: returns random items that belong to the given cluster
NEWEST: returns the items of a cluster sorted that the items added more recently are at the top of the list
BEST: returns the items with the highest association to the given cluster at the top of the list (Note: currently only useful with plugin generated clusters; items added via the Admin GUI or CSV upload all have the same association to a cluster)

The default strategy is NEWEST.

useFallback
optional

Clusters can be organized in a hierarchical way in the Admin GUI to take the form of a tree. If this useFallback is set to 'true', easyrec tries to traverse the cluster hierarchy and adds items from sibling and parent clusters to the returned recommendation in case the given cluster only has less that 'numberOfResults' matching items.

requestedItemType
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.). If not supplied the default value ITEM will be used.

Receiving Itemtypes

load all item types

If you want to load all item types of your tenant you can use the following function:

<!--
Usage : easyrec_itemtypes(parameters);

Example:
-->

<script type='text/javascript'>
            easyrec_itemtypes{drawingCallback:"drawRecommendationList"});
</script> 

The parameter parameters specifies the recommendation parameters for the JSON API call:

drawingCallback
required

The name of the Drawing Callback Function for the Json Request


Receiving Rankings

To receive rankings from easyrec the javascript function 'easyrec_getRankings' has to be called with the following parameters:

<!--
Useage : easyrec_getRankings(rankingType,parameters);

// same as easyrec_getRankings( "mostvieweditems",parameters);
easyrec_mostViewedItems(parameters);

// same as easyrec_getRankings( "mostboughtitems",parameters);
easyrec_mostBoughtItems(parameters);

// same as easyrec_getRankings( "mostrateditems",parameters);
easyrec_mostRatedItems(parameters);

// same as easyrec_getRankings( "bestrateditems",parameters);
easyrec_bestRatedItems(parameters);

// same as easyrec_getRankings( "worstrateditems",parameters);
easyrec_worstRatedItems(parameters);

Example:
-->

<script type='text/javascript'>
            easyrec_getRankings("mostvieweditems",{numberOfResults:10,
                                       timeRange:"DAY",
                                       drawingCallback:"drawRecommendationList"});
</script>

Parameters

The first parameter rankingType specifies the Ranking Type:

mostvieweditems
This community ranking shows the items that were viewed the most.
mostboughtitems
This community ranking shows items that were most frequently bought.
mostrateditems
This community ranking shows items that were most frequently rated.
bestrateditems
This community ranking shows the items that received the best ratings. Rating values range from 1 to 10. The ranking only includes items that have an average ranking value greater than 5.5.
worstrateditems
This community ranking shows the items that received the worst ratings. Rating values range from 1 to 10. The ranking only includes items that have an average ranking value less than 5.5.

The second parameter parameters specifies the recommendation parameters for the JSON API call:

drawingCallback
required

The name of the Drawing Callback Function for the Json Request

numberOfResults
optional; default:50

An optional parameter to determine the number of results returned. (Default: 50)

timeRange
optional; default:ALL

An optional parameter to determine the time range. This parameter may be set to one of the following values:
• DAY: only takes actions within the last 24 hours into consideration.
• WEEK: only takes actions within the last week into consideration.
• MONTH: only takes actions within the last month into consideration.
• ALL (default): all actions are used.

itemType
optional; default:ITEM

An optional item type that denotes the type of the item (e.g. IMAGE, VIDEO, BOOK, etc.) you are looking for. If not supplied the default value ITEM will be used.

requestedItemType
optional; default:ITEM

An optional type of an item (e.g. IMAGE, VIDEO, BOOK, etc.) to filter the returned items. If not supplied the default value ITEM will be used.

Drawing Callback Functions

We implemented three drawing callback functions you can use to display your recommendations. You can write your own drawing functions easily. The provided drawing callback functions write recommendations to the HTML <DIV> element with the id recommenderDiv that must be present in your html code:

<div id="recommenderDiv" >&nbsp;</div>


drawRecommendationList
This drawing callback function shows recommendations as a list. (Feel free to style with your own CSS)
drawRecommendationListWithPictures
This drawing callback function shows recommendations as row of pictures.


easyrec_getRecommendations("otherusersalsoviewed",{
       userId:"24EH1723322222A3",
       itemId:"42",
       drawingCallback:"[drawbackname]"
       });


If you need more information about creating your own drawing callbacks, this Guide should get you started.

Here is an example of a drawing callback function:


function drawRecommendationList(json){drawRecommendationListToDiv(json,"recommenderDiv");}
function drawRecommendationListToDiv(json,recommenderDiv){
 	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) {
                              listString ="<ul>";

                    for (x=0;x<15 && x <items.length;x++) {
                           listString +=
                              "<li><a href='"               + items[x].url + "'>"
                                                        + items[x].description +
                              "</a>" +
                              "</li>";
                    } 


                    document.getElementById(recommenderDiv).innerHTML += listString+"</ul>";

                }

         }

}
Personal tools
Namespaces

Variants
Actions
easyrec documentation
Navigation
Toolbox