Serverside Use

A Note About Javascript

Even for serverside implementations, it is recommended to include the Gravity javascript on all web pages: The script adds automation for reporting exposures and clicks on recommendations. Details about this is found in the JavaScript client specification.

Authentication

Authentication is handled with basic HTTP authentication. Using curl, it looks like this: Failing to authenticate will give a 401 Unauthorized response.

Updating Information

Sending updates from the server involves constructing a JSON payload to convey the needed information. The payload must be sent to the server using the POST method over HTTPS. Here's an example of reporting that a user has bought a pair of shoes: The above example payload transmits this information to Gravity:

• The update is targeted for a service named shoeshop
• An item with ID DrMartens-90 has been purchased by customer 12345 (the cluster)
• An item with ID DrMartens-90 has been purchased on invoice 274965b

All IDs in the Gravity system are treated as unique identifier strings. If any of the IDs in this update is already in use in the shoeshop service, these IDs will have their information updated. Otherwise, the newly arrived IDs will be added to the aggregated information.

Retrieving Recommendations

Here is a very straightforward example of a recommendation request: The parameters are specified in the recommendation request API schema. This example payload transports the following information:

• The request is for the shoeshop service
• Recommendations should be generated from a recommender named ItemToItemRecommender
• Basis for the recommendations is Adidas-102
• The user that these recommendations are meant for, is somecustomerid.
• We would like a total of four recommendations returned.

The recommendation response will have a structure as described in the JSON payloads description.

Some recommendations rely on more than one ID. They could e.g need both the user's ID and some product ID. Submitting multiple IDs is just a matter of adding them in the input field, which is an object with named JSON lists. Here is an example of retrieving recommendations to fit the contents of a shopping basket with six items in it: Why is the customer's ID duplicated in the payload? The inner customer field is an input parameter to the recommender. It tells it to base calculations not only on the six items in the shopping basket but also on the current customer. The outer consumer field is for the system on a wider level (not only entering it into an algorithm), used to adapt to the current customer. And this last field is compulsory in all update and recommend communication with the system.

Tracking Exposure and Interaction

For statistics and for continuous enhancement of recommendations and algorithms, exposure of recommendations and clicks thereon must be reported back to the Gravity system. On a web page, this is automated (if you include the Gravity header javascript and populate some HTML tag attributes as described on the javascript client page). But when using Gravity from a server or in telephone or tablet apps, you need to send the reports yourself.

These reports really are just another sort of updates, however, so you can use your update implementation if you pay special attention to the what and the origin fields in your payload. The what field is to describe the event: it should be RECCLICK or RECEXPOSURE. The origin field is to contain the id (name) of the recommender instance that produced the recommendation in question. This is not always the same as the id (name) of the recommender that you requested, so copy into the origin field of your payload the value received in the recommendation JSON (in a field equally named origin, see the JSON payloads descriptions for details).

Here is what you could send e.g. from a telephone app: This tells the system that recommendations of product-1 and product-3 have been shown to customerid, and that customerid has clicked on the recommendation of product-3. It also says that the recommendations were produced by a recommender named ItemForCustomerRecommender, and that the exposure took place in an app.

     Recommender REST Interface Documentation, version 3.0.9
     Copyright © 2013-2019 Sannsyn AS
     Don't hesitate to contact us