|<REC_SERVER_ADDR>||Recommendations server address (see environment page for recommendation server address)|
|<PORT>||Port recommendation server is listening on. Currently 80 or 443. <br> NOTE: use 80 for HTTP requests, and 443 for HTTPS requests.|
|<VERSION>||API version. Currently only ’1’ is supported|
|<SITE>||Customer site name|
|url||URL||Context document entity ID. Used to order candidates "best" first, and for filtering candidates for selection. May be multi-valued: "…&url=URL1&url=URL2&…".
Only one "url" or "ProductId" should be used. |
An alias for "Document.id", see "
|ProductID||product id||Context product entity id. Used to order candidates "best" first, and for filtering candidates for selection. May be multi-valued: "…&ProductId=URL1&ProductId=URL2&…".
Only one "url" or "ProductId" should be used. |
At this time productId’s are converted to urls, and added to the list of urls.
An alias for "Product.id", see "
|UserId||bnuid||User id for the user making the call. It is the value in bn_u cookie.|
|Dynamic attribute value that will overwrite whatever is persisted in the data store for that context attribute.||"Dynamic Attributes" feature provides a way to overwrite whatever is known (or not known) about a particular context attribute. Be it Product attribute, User attribute or attribute of some other entity. |
- In Thor you specify a dynamic attribute value instead of specifying a filter on the API call. You must create a filter in VUE that will reference the attribute so that the system recognizes the dynamic attribute.
- To specify product entity attributes, use the following format:
|pageTemplate||page template name||Used to group a number of widgets together.|
|widget||widget name||Widgets allow you to specify a recommendation type and recommendation constraints (filters, pins, etc.). |
Note: Direct widget calls give you more flexibility (compared to page template or automatic routing calls) at the expense of complexity. See Tracking Data Quick Setup for details.
|attrs||Recommendable entity’s attributes to include in reply. May be either canonical or catalog.||For each recommended entity, the response will include the entity’s ID attribute, plus any attributes named by the attrs parameter. The attribute names may be either canonical or catalog names. The response uses the same name, in the same case, as specified by the attrs parameter. Use "*" to request that all attributes be returned. |
To request multiple attributes, use the attrs parameter multiple times: attrs=attribute1&attrs=attribute2&…
|query||Query string for TermGuide||Individual query terms are separated by "+", for example: "query=duct+tape". If you specify query terms other than null, the system ignores all other contexts (url, productid) as well as configured widget objectives, and uses TermGuide instead. See Term Based Recommendations documentation to understand how to configure and use TermGuide.|
|source||location of the page from where the RS request is generated||Denotes the source of the rest recommendation server call made, and includes the location of the page as its value. The system uses this parameter for routing.|
Used only when routing is needed and is ignored for every other call.
- When routing is triggered, routing uses the source parameter value as the routing context.
- When routing is triggered, URL context is ignored.
- When routing is triggered and source is not present, the URL parameter is used for routing. (URL should be treated as source)
- When routing is triggered and source is not present and there are multiple URL parameters present, first URL parameter is treated as the source for routing.
- When routing is triggered and both source and URL parameters are not present, no recommendations will be served.
|visitstrail||Browsing history in the form of CSV of URLs||Used to pass the browsing history of the user to the recommendation server. The system takes what you pass in and echoes it back to the caller from the "Last Viewed" Recommendation Type. That is, given recommendations are driven by a widget that is configured to use "Last Viewed" RT. visitstrail will be ignored otherwise.|
If the user visited URLs 1, 2, 3, 4 (4 being the last one) then:
- visitsrail (input): 4, 3, 2, 1
- Last Viewed (output): 4, 3, 2, 1
See more details at Design and Specification of ’visitsrail’ parameter
|pagetype||page type needed for routing||Used to pass page type for routing. For exam Home, Cart, ProductDetail. This can be used in association with the source to pick the correct PT. Only that PT will be picked whose page type matches with the supplied value is this param while evaluating the rules. If not present the first PT found after a rule is satisfied is picked.|
|format||XML or json||Used to specify the format of the response: either XML, or json. Used as an alternative to using the HTTP "Accept" header.|
|User.cmnState=California||Defines the User entities’ attribute cmnState to have the value "California". Will be passed to the XPU to make better selections, and can be used in filters|
|Request.Luxury=true||Defines the User entities’ attribute cmnState to have the value "California". Can be used in normal filters, and as the antecedent of a conditional filter for rules based targetting. "Request.Luxury implies price > 200".|
|User.||external user id||User before DOT indicates Entity User and uid for external user ID attribute as named for the site in configuration.|
- The parameter name is case insensitive (i.e. User.ext_uid is same as USER.EXT_UID)
- The value of external user ID is case sensitive. (i.e. User.ext_uid=e123 is NOT same as User.ext_uid=E123 ) MAG-115 - Ensure that RS treats external user id value as case insensitive
- Here ext_uid is just example external user id attribute name configured in Entity Config for this site. it can be different for each site.
|recResult||Root-level element. A single complete response that contains all of the results.|
|responseId||Unique identifier of the response|
|merchModel||MerchModel checkpoint id of the MerchModel for which this response is generated.|
|trackingData||trackingData is an opaque base 64 encoded string token which is used to decode all meta information about recommendations like widget info, test info, slot info and page info. It is generated using all this info and then encoding it. This element is important in genera,l and more important from an AB test perspective. The test info from the tracking data is used for analysis by the Data Science team.|
|type||Indicates if the response is for a widget or a page template. Allowed values - widget or pageTemplate|
|Id||Widget name or the page template name associated with the response|
|widgetResults||Top level element for containing all the results associated with one widget. A response can have multiple widgetResults when the type is "pageTemplate" or request is made for multiple widgets.|
For information on elements found within the widgetResults element, see Elements Within widgetResults.
|abTest||Top level element that contains all information about the ab test i.e Id, testname, variant name and merchModel|
|context||Top level element that contains information about the context present in the request. Contains information about single or multiple contexts.|
For information on elements contained within the context element, see the Elements within Context table.
|affinity||A dynamic attribute used by filters to determine which item to evaluate first. For more information on the affinity attribute, see Affinity.|
|Id||Unique widget name|
|displayName||Customers will see this on the site. Can be used for displaying titles like "You may also like" or "Customers Also Viewed" in customer site.|
|placeholderName||You can use the Placeholder Name to explicitly identify where to render the results from corresponding widget. This allows the rendering to be abstracted from widget name. For example, you typically specify the exact website HTML div Id that will be used to render the results on your web site.|
|algoName||Algo executed to give results for the widget|
|slotResults||Top level element which contains the actual recommendation. Each slotResult contains one recommendation (url and all attributes). Each widget can have multiple slotResults depending on the configuration.|
For information on elements contained within the slotResults element, see the slotResults table.
|slot||Slot number the recommendation is associated with|
|rank||Rank is the rank of the entity form the catalog that filled the slot. This will help to answer how effective are the recs.|
If no filters are applied, then the ranks will be 1, 2, 3 for a widget with 3 slots
If a filter is applied that is not restrictive, the ranks may look like 1, 6, 46
For restrictive filter the ranks may look like 4, 68, 1092343 (first two slots have been filled pretty quickly, while it took 1092343 entities to scan in order to fill out the third one)
|scanTime||The time in milliseconds elapsed in selecting the candidate. This time says how much was spent after the previous candidate was selected.|
|url||url of the product recommended|
|attrs||Attributes associated with the product. (Canonical/Catalog name as requested with its values)|
|Explanation||Top level element that contains the meta data of the recommendation, concisely, the reason a candidate is selected like pin, blacklist etc. For now only 3 items are supported - ItemPin, FilterPin and PairPin. It is mainly for debugging purpose.|
|Context||Similar to explanation, says about the context of the recommendation|
|Entity||Type of context - Document or product|
|attrs||Attributes associated with the product. (Canonical/Catalog name as requested with its values). Similar to attrs for slotresults.|