GuidesDiscussions
Guides

Web personalization

Suggest Edits

Prerequisites

Description

Recommendation Request/Response Anatomy

Request ParametersDescription
scenarioIdUsed to select the most appropriate algorithm and to filter settings for the current page type and box location.
userIdIdentifier of the current user.
cookieIdIdentifier for guests or users that are not logged in.
numberLimitThe number of requested items.
currentItemIdUsed on item pages to pass the ID of the current item to the engine.
<custom_parameters>Any additional parameter used for filtering e.g.
- current category
- search string
- list of items already visible on the page
- list of items which can be recommended
- ...
<item_properties>Gravity can return selected properties of the recommended items to make the generation of recommendations easier. These properties has to be listed in the request:
- url
- imageUrl
- title
- ...
Response ParametersDescription
recommendationIdUnique identifier for every recommendation response.
itemIdsThe list of IDs of the recommended items.
itemPropertiesThe value of each property listed in the request for the recommended items.

Injected Recommendation Box

If you don't want the hassle of implementing the recommendation boxes yourself, Gravity is able to render it on your site. After including our JS on your site, you just need to approve the box design, and the recommendations will be displayed with no further work needed.

JavaScript initialization

The communication between the recommendation engine and the customer's site is implemented by asynchronous JavaScript calls directly between the user's browser and the recommendation engine.
First, you need to bootstrap our system by adding the following code to the webpage (this will load and setup our JS library). Paste this snippet into your website template page so that it appears before the closing tag.

<head>
    [...]
<script>
    (function(g,r,a,v,i,t,y){
        g[a]=g[a]||[],y=r.createElement(v),
        g=r.getElementsByTagName(v)[0];y.async=1;
        y.src='//'+i+'/js/'+t+'/gr_reco5.min.js';
        g.parentNode.insertBefore(y,g);y=r.createElement(v),y.async=1;
        y.src='//'+i+'/grrec-'+t+'-war/JSServlet4?cc=1';
        g.parentNode.insertBefore(y,g);
    })(window, document, '_gravity','script', '<CUSTOMERID>-<SERVERLOCATION>.gravityrd-services.com', '<CUSTOMERID>');
</script>
</head>

You should replace CUSTOMERID with your partner identifier and SERVERLOCATION with the gravity cluster name!

(The library will register a global object named "GravityRD". Except this object, which is necessary we don't pollute your namespace.)

📘

For debugging reasons, a non-minimized version of the library is also available, named: gr_reco5.js

JS API call

If you want more control over the rendering of the recommendations, or you would like to display recommendations in existing elements, you can use our JS library for handling asynchronous recommendation requests.

Example request:

_gravity.push({type : 'recommendation', callback: callback_fn, numberLimit: 5, scenarioId: "ITEM_PAGE", currentItemId: "28080"});

You can find detailed information here.

Server-side API call

🚧

IMPORTANT NOTE

Please keep in mind that trough network error or through other unexpected issues may an error occurs while getting the recommendation from or while adding events to the recommendation engine. This error can cause a program exception which always has to be handled in the proper way. Without handling the possible exceptions your code may terminate at an unexpected place and your site will operate abnormally. Even if you do not get a valid list of recommended items as a result of the recommendation request take care about hiding the recommendation widget or filling it with relevant items. Please ensure the safe error handling. Gravity does not take any responsibility for any damages caused by the lack or deficiency of error handling

If, for some reason, JS is not a possibility for you, Gravity also provides server-side API for recommendation requests.

For more details please visit the following pages:

Scenario examples

E-commerce examples

Scenario nameDescription
MAIN_PAGERecommended items are displayed on the main page.
CATEGORY_PAGERecommended items are displayed on a category browsing page where usually only items from the specific category are displayed.
LISTING_PAGERecommended items are displayed on a page where several items are listed e.g. as a result of a search query.
ITEM_PAGE_RELATEDRecommended items are displayed on an item details page where detailed information can be found about an exact item. Emphasize items from related categories.
ITEM_PAGE_SIMILARRecommended items are displayed on an item details page where detailed information can be found about an exact item. Emphasize similar items.

Classified example

Scenario nameDescription
MAIN_PAGERecommended items are displayed on the main page.
CATEGORY_PAGERecommended items are displayed on a category browsing page where usually only items from the specific category are displayed.
LISTING_PAGERecommended items are displayed on a page where items several item is listed e.g. as a result of a search query.
ITEM_PAGE_RELATEDRecommended items are displayed on an item details page where detailed information can be found about an exact item. Emphasize items from related categories.
ITEM_PAGE_SIMILARRecommended items are displayed on an item details page where detailed information can be found about an exact item. Emphasize similar items.
AFTER_ADREPLYRecommended items are displayed on item details page after succesful contact has been estabilished with the vendor.

Video streaming example

Scenario nameDescription
MAIN_PAGERecommended videos are displayed on the main page.
CATEGORY_PAGERecommended videos are displayed on a category browsing page where usually only items from the specific category are displayed.
LISTING_PAGERecommended videos are displayed on a page where several videos are listed e.g. as a result of a search query.
VIDEO_RELATEDRecommended videos are displayed on an video page where detailed information can be found about an exact item. Emphasize items from related categories.
VIDEO_PAGE_SIMILARRecommended videos are displayed on an video page where detailed information can be found about an exact item. Emphasize similar items.
PLAYER_RELATEDRecommended videos are displayed on an video page where detailed information can be found about an exact item. Results are displayed after finishing the video.

Updated about 6 years ago