Using the Javascript Client

To make use of the Gravity system on your website, first make sure the header javascript is included on all web pages:

<html> <head> <script type="application/javascript" src="https://recommender.sannsyn.com/ajaxrecapi/1.1/header.js?service=serviceid&cid=customerid" async></script> ... </head> ...

If you already know the basics of the script, you can jump directly to the JavaScript client object overview.

By means of this header javascript, the Gravity system can recognize the client, and it thereby assures that the subsequent updates and recommendation requests work. It also adds some automation for reporting. The customer ID is here given in the cid parameter. If the customer's ID is unknown at HTML build time or when the script URL is constructed, this parameter may be omitted (although this will leave the customer recognition to the script exclusively, and may lead to less accurate recommendations if the user has disabled cookies in the browser).

Note: the script should normally be loaded in an async manner. Make sure you wait for its completion before taking advantage of any of its specialities (by using the jquery construct $(document).ready(function() { ... } ); or similar).

Once the Sannsyn header script is loaded, functions for communicating with Sannsyn through javascript commands are available. You will find all of this in an object named sannsyn, available for inspection in the browser. If you launch the following command in the browser console, you should see a short message from the Recommender giving the current version number of the Javascript module along with its target Recommender API version, which should read 1.1:

sannsyn.version();

Updating Information

Functions for sending updates to Sannsyn are in the javascript sannsyn object.

Customer ID

Often, the customer ID is conveyed with the cid parameter on the header script URL; however if it is not available when your HTML is generated, but the web page gets hold of it while interacting with the user, you inform the Sannsyn script with the setCustomer() function:

sannsyn.setCustomer("customer ID");

This makes all subsequent calls to the Gravity system through javascript aware of the current user ID. The customer ID does not have to be set again unless the user reloads the web page or navigates to a new web page.

Product Browsing

Visits to web shops' product pages is to be logged by the recommender. When users enter a product page, an update must be sent. The command looks like this:

sannsyn.reportProductBrowsing("product ID");

The sannsyn javascript client will then forward an update to the Gravity system.

Purchases

While product browsing is a simple question of stating a relation between a cluster and an entity («this customer looked at this product»), purchases are more complicated. They involve not only a customer and a product, but typically also a price, an invoice ID, one or more order line IDs and often more than one product. This is taken care of by a purchase report, which you can construct with a builder pattern. The building blocks of a purchase report are OrderLineItem objects. Here's a complete example with comments:

// First create an OrderLineItem: let builder = new sannsyn.OrderLineItemBuilder("Item1"); // Constructs an OrderLineItem builder based on an item ID builder.setTaxon("virtualItem"); // Sets the taxon. builder.setUnitPrice(234); // Sets the price for this item. builder.setOrderLineId("orderLine-23"); // Sets the ID of this particular orderLine. builder.setNum(8); // Sets the number of "Item1" items this orderLine represents let item1 = builder.build(); // Finally gets us the OrderLineItem object // It actually is just a javascript object: console.log(item1); // Object { itemId: "Item1", num: 8, unitPrice: 234, orderLineId: "orderLine-23", taxon: "virtualItem" } // The builder also permits chaining the different method calls: let item2 = new sannsyn.OrderLineItemBuilder("Item2").setUnitPrice(199).build(); // Then create a purchase report builder: let prBuilder = new sannsyn.PurchaseReportBuilder(item1, item2); // Vararg argument to constructor. Add as many or as few items as you wish. // Give an invoice ID if there is one: prBuilder.setInvoiceId("invoice-1"); // Oh, did we forget an item? let item3 = new sannsyn.OrderLineItemBuilder("Item3").setTaxon("virtualItem").build(); prBuilder.addItem(item3); // Build the purchase report and send off: let purchaseReport = prBuilder.build(); purchaseReport.send(); // And also the purchase report has this chaining possibility: new sannsyn.PurchaseReportBuilder(item1, item2, item3).setInvoiceId("invoice-2").build().send();

For a schematic overview of these objects and their functions, please refer to the Javascript client specification.

Do send updates frequently! The Gravity system responds in realtime, so updates impact on subsequent recommendations. Do not save up for one big update as the customer leaves your site!

Requesting Recommendations

Recommendations are also requested through the sannsyn javascript object.

The Recommendation Request Builder

First, get a recommendation request builder object:

let reqBuilder = new sannsyn.RecReqBuilder("CustomerItem");

The string parameter is the ID (the name) of the recommender you wish to use. Now supply the input that thi recommender needs:

reqBuilder.setInput("customer", ["anonymous"]);

This function takes the name of an input parameter and a list of string IDs. Even when a parameter (here: «customer») has no values or only one value (here: «anonymous»), a list must be supplied. If more than one input parameter is needed, repeat the requester.input(...) call for each parameter. Then specify a callback function to receive recommendations:

let callbackFunction = function(rec) { console.dir(rec); } reqBuilder.setCallback(callbackFunction);

Finally, build a requester and fire off your request:

let requester = reqBuilder.build(); requester.exec();

Your recommendations will be delivered to the callback method. If something goes wrong, you will be informed in the browser console.

Recommendation Responses

In response to recommendation requests you will get JSON like this:

{ "path": ".", "name": "CustomerItem", "origin": "CustomerItem", "origin_details": [], "result": { "ids": [ "Item45", "Item76", "Item334", "Item2", "Item53" ], "taxon": "item", "type": "simple" }, "source_ids": { "customer": { "ids": [ "anonymous" ], "taxon": "person", "type": "simple" } } }

Marked in red are the most important parts. The result.ids field contains the requested recommendations, and the origin field contains information that you will need when reporting, as described in the following section.

Tracking Exposure and Interaction

For statistics and for enhancement of recommendations and algorithms, exposure of recommendations and clicks thereon must be reported back to the Gravity system. The javascript client is constructed to handle this for you, but it needs two data attributes to be placed in the recommendations' DOM-tree elements:

data-sannsyn-recommendation − with the recommendation itself (the ID of the entity being recommended)
data-sannsyn-recommender-id − with the ID (the name) of the recommender having produced the recommendation in question (given in the recommendation's origin field)

Using the result example above to embed recommendations in our HTML, we could construct something like this (again with the important parts in red):

<html> <head> <script type="application/javascript" async="true" src="https://recommender.sannsyn.com/ajaxrecapi/1.1/header.js?service=serviceid"></script> </head> <body> <h1>Recommended for you</h1> <ul> <li data-sannsyn-recommendation="Item45" data-sannsyn-recommender-id="CustomerItem"> <a href="clickOnItem45">Item45</a> </li> <li data-sannsyn-recommendation="Item76" data-sannsyn-recommender-id="CustomerItem"> <a href="clickOnItem76">Item76</a> </li> <li data-sannsyn-recommendation="Item334" data-sannsyn-recommender-id="CustomerItem"> <a href="clickOnItem334">Item334</a> </li> <li data-sannsyn-recommendation="Item2" data-sannsyn-recommender-id="CustomerItem"> <a href="clickOnItem2">Item2</a> </li> <li data-sannsyn-recommendation="Item53" data-sannsyn-recommender-id="CustomerItem"> <a href="clickOnItem53">Item53</a> </li> </ul> ...

The javascript client will detect the recommendations becoming visible on screen. If any of them are clicked on, that too is registered. If the data-sannsyn- attributes are properly applied, both of these events are automatically reported back to the recommender.