KIBO RTI DOCUMENTATION

Image Server API

GuideRender Thor RS API

GuideRender is the service that renders an image with either one recommendation item or a set of recommendation items. The GuideRender request parameters are described in the ‘Rendering Parameters’, ‘Styling Parameters’ and ‘Additional Guide Parameter’ tables below.

Render API Parameters

The Image Server component supports both Thor RS API Syntax, and Iron Chef (IC) Syntax, for performing its calls.

You can also send all the values configured through the URL, or use a predefined skin stored on Config.

Render Thor RS Syntax

URL: http://:/render//?&
Method: GET
Example:
- /render/1/dhc_www?widget=mail_guide_Recentpopular&index=2&url=http%3A%2F%2Fwww.hersheysstore.com%2F
&bgColor=FFFFFF&height=250&width=250&imgStyle=name:ImageURL,borderWidth:0,borderColor:FFFFFF,h:210,w:210,x:0,y:0
&attrStyle=name:Price,h:20,w:100,x:0,y:0,font:Arial,size:12,color:000000,style:none,align:left,label:$$1
&attrStyle=name:ProductTitle,h:20,w:20,x:0,y:220,font:Arial,size:12,color:000000,style:none,align:left

NOTE: GuideRender service can also be consumed using the original GuideRender implementation syntax version, for further reference look at the end of this document, GuideRender Legacy.

Call using skin stored in Thor Config

-/render/1/?renderskin=blueskin
-/render/1/?renderskin=blueskin&attrStyle=name:newAttribute

 

The Skin option also allows the user to specify additional parameters. imgStyle, attrStyle will add an additional image or attribute instead of replacing the default.

For further detail in configuration’s usage, refer to ImageServer Configuration

Rec Parameters <recParameters>

This section depends on the syntax type utilized, either Thor Syntax Parameters or Original Syntax Parameters are to be used. Thor RS Syntax recommendations are obtained using the same parameters as Thor RS API. Please refer to Thor RS API documentation for a more detailed/updated version of the valid parameters.

Parameter NameCommentsOptions
urlCustomer’s page that contains items for generating recommendations. Accepts multiple URL parameters.Optional, but Recommended
ProductIdThe contextual product for generating recommendations. Accepts multiple ProductId parameters.Optional
UserIdKibo User ID for the user making the call. Refers to the value in bn_u cookie.Optional
User.Context user attribute used to pass user attributes on the REST call if a context user attribute is specified together with UserId.Optional
widgetA widget that serves as a container for recommendation properties. It contains algorithms and filters.

If you use a widget parameter in RS API, you cannot use other parameters (algor, filter, maxresults, etc). The system picks up all recommendation properties from specified widget. Widget filter is part of the merchmodel config file and must be defined in compliance with filter XML grammar. Merchmodel CLT enables the system to create XML formatted filter based on simple expression provided. See section 3 in MerchModel Validation Procedure (sanity check)
Required
pageTemplateA widget that allows you to group other widgets together.Required
attrsTo request multiple attributes, use the attribute multiple times: attrs=attribute1&attrs=attribute2Optional
queryIndividual query terms are separated by "+", e.g., "query=duct+tape". If specified and is not null, all other contexts (url, productid) as well as configured widget objective will be be ignored and TermGuide will be used instead. See TermGuide documentation to understand how to configure and use TermGuide.Optional

Rendering Parameters <renderingParameters>

Parameter NameDescriptionOptions
ieInput encoding, the character encoding that was used to encode the incoming request. An optional parameter set to ISO-8859-1 by default.

NOTE: To properly display international characters in the output, you must specify ArialUnicode as the font in the text styling parameters.
Optional
heightHeight in pixels of the box for one recommendation item.

NOTE: When using imagemaps, the box size specified should directly correlate to the AREAs defined in the client-side imagemap to keep the hyperlink positioning accurate.
widthWidth in pixels of the box for one recommendation item.

NOTE: When using imagemaps, make sure the box size specified here directly correlates to the AREAs defined in the client-side imagemap, so that hyperlink positioning is accurate.
orientHorizontal (H) or vertical (V) layout of multiple items when using imagemap
bgColorBackground color for entire rendered image, specified with a 6-digit RGB hex code excluding the "#" character (for example: 33AABB).
imgStyleUsed to display an image.

Can be specified once for document attribute-based thumbnail (using the name argument), and multiple times for static images (using the URL argument). Formatted as a comma-separated list of image styling arguments (see below). e.g. imgStyle=h:100,w:100,x:0,y:0,name:PictureUrl.
Required
textStyleGlobal text styling arguments, formatted as a comma-separated list. For details on arguments, see below.

NOTE: Any styling specified here will be used for all text in the guide unless overridden by a specific attrStyle. Specifying positional styling here creates a text box area in which all text attributes will be written.
attrStyleUsed to display a document attribute. Formatted as a comma-separated list of styling arguments (see below) and can be specified multiple times (for multiple attributes).
textUsed to display static text per recommendation. Formatted as a comma-separated list of styling arguments (see below).
imgSrcName of the document attribute that contains the thumbnail image URL. If this parameter is not specified, the thumbnail will not be rendered.

NOTE: this parameter is deprecated, instead specify imgStyle with a name argument to designate the document attribute containing the image URL.
Deprecated
fallbackIn case index is not found in guiderest api results, fallback behavior will be triggered. Fallback parameter should be sent over the url using the following format: fallback:=< imageUrl >

The following sequence will be performed:
1. The image obtained in url will be returned to the user.
2. In case the image doesn’t exist for current request then a blank image will be returned.

A system config structure is recommended for storing default fallback (this is recommended for a future implementation).
Optional
startingDocNumDetermines 1-based rank of the recommendation item to start rendering, usually 1. Should not be used for multiple IMG tags.Optional when using imagemap
resultsPerPageRequired when using imagemap. Determines maximum number of items to render. Should not be used for multiple IMG tags.Required when using imagemap

imgStyle, textStyle, attrStyle, and text parameters

The following describes usage guidelines for imgStyle, textStyle, attrStyle, and text parameters.

Image styling arguments

These apply only to the imgStyle parameter.

ArgumentDescription
nameName of document attribute from which image URL will be obtained, which is the source of the image. Only one imgStyle parameter with name can be specified. If this argument is used, url will be ignored.
urlURL for static image to use as source. Multiple imgStyle parameters can be specified for static images.
borderWidthborder width in pixels (if omitted or if 0, no border will be drawn)
borderColorborder color, specified with 6-digit RGB hex.

Text Styling Arguments

These apply to textStyle, attrStyle, and text parameters.

ArgumentDescription
fontName of font to use (Arial, Times, ArialUnicode). NOTE: ArialUnicode should be used for international character support.
sizeSize of font in pixels.
colorElement color, specified with 6-digit RGB hex e.g. 33AABB. No pound sign should be present.
styleFont style of element: BOLD, ITALIC, STRIKE, UNDERLINE. Multiple styles can be specified, separated by a space character.
alignAlignment: l, r, c for LEFT, RIGHT, CENTER.

Attribute Styling Arguments

These apply only to the attrStyle parameter.

ArgumentDescription
nameName of attribute to display.
labelLabel to apply to display text. This is a string that will be displayed instead of the raw attribute value. The string can embed the attribute value by using =$1=
labelPluralIf present, this label is applied to attributes with an integer value of more than one, while label is applied to attributes with an integer value of one.
labelEmptyIf present, this label is applied to attributes with an empty or zero value.

Static Text Styling Arguments

These apply only to the text parameter.

ArgumentDescription
valueStatic text value to display.

Position and Size Styling Arguments

To be used on textStyle, attrStyle, imgStyle and text parameters.

ArgumentDescription
hHeight in pixels.
wWidth in pixels.
xHorizontal position within item box in pixels.
yVertical position within item box in pixels.

Output

ImageServer Render returns an image built based on the specified parameters. Several images can be rendered onto one canvas, several attributes can be rendered over images, and the order of rendering is the same order as the attributes are being specified onto the URL.

For example, a call made using the following request:

http://suresource-hershey.baynote.net/baynote/guiderender?index=1&cn=suresource&cc=hershey&guide=HomeRec&bgColor=FFFFFF&height=250&width=250&url=http%3A%2F%2Fwww.hersheysstore.com%2F&imgStyle=name:ImageURL,borderWidth:0,borderColor:FFFFFF,h:210,w:210,x:0,y:0&attrStyle=name:Price,h:20,w:100,x:0,y:0,font:Arial,size:12,color:000000,style:none,align:left,label:$$1&attrStyle=name:ProductTitle,h:20,w:200,x:0,y:220,font:Arial,size:12,color:000000,style:none,align:left

Returns an image such as:

Considering the image referenced into the attribute imageURL and attributes recalled Price and ProductTitle.

GuideLink Thor RS

GuideLink is the Kibo service that dynamically redirects the user to the appropriate product page based on which image or area in the imagemap was clicked. Note that the same basic guide parameters (not rendering parameters) used in GuideRender should also be used in GuideLink, to make sure the same recommendations information is used. The index parameter is used to indicate the recommendation order number, an example of this is given at the end of this section.

Link API Parameters

Link Syntax:

URL: http://:/link//?&
Example:
- /link/1/dhc_www?widget=mail_guide_Recentpopular&index=2&url=http://www.dhc.co.jp/main/main.jsp&pass_thru=bnec%3DCRM_201008

NOTE: Guidelink service can also be consumed using the original GuideLink implementation syntax version.

RecParameters

Link service’s Rec Parameters are dependent on syntax type utilized, either Thor Syntax Parameters or Original Syntax Parameters are to be used.

Thor RS Syntax Parameters

Thor RS Syntax recommendations are obtained using the same parameters as Thor RS API.

Please refer to Thor RS API documentation, for a more detailed / updated version of the valid parameters.

- /link//?widget=&index=&url=&passthru=&fallback=

GuideParameters

Parameter NameDescriptionOptions
fallbackFallback URL to go to in case the given index does not exist (there is no result for the index).

For example, if the email recommendation tags that are set up for the customer expect four results, there will be HTML tags for four images with corresponding links. If the dynamic recommendation only comes back with three actual results, then there will be three blocks (index 1-3) with actual recommendations and one block (index 4) with a blank image. Clicking on the image corresponding to index #4 will go to the fallback URL.
Optional
passThruURL-encoded string to add to the target product URL. Usually a set of parameters to pass to the target page.
Text added with this function to the URL gets added after a ’&’ character in case the resultant URL has parameters on it and responds adding a ’?’ character in case there were no parameters on the resultant URL.
Optional
linkSrclinkSrc allows guidelink REST request to return a link other than the url that the document is stored as. User should specify the source field from where this url is going to be taken for redirection. In case link Src specified attribute is not found on source, Link will proceed using regular URL.Optional

Output

ImageServer Link returns a 302 HttpResponse to the User redirecting to a product URL that was taken from the Rec Server.

The url that will be returned depends on the index parameter specified on the URL, and the specific Rec Component that is being used.

The output can be manipulated by using parameters such as passThru, that adds a certain string to the returned URL, or linkSrc that obtains the URL from a different attribute from the source. (See guide parameters for additional detail).

GuideRender Legacy API

In this section Image Server GuideRender Legacy syntax is explained.

Render API Parameters

GuideRender Legacy Syntax

URL: http://:/baynote/guiderender?&

Method: GET
Example:
Example URL to render image+text:

-/baynote/guiderender?cn=CUSTOMER&cc=CODE&guide=ALSOUSED
&renderMode=DEFAULT&index=1&attrList=Title,Price&imgSrc=ImageUrl
&url=http://test.com

Call using skin stored in Thor Config

-/baynote/guiderender?cn=CUSTOMER&cc=CODE&guide=ALSOUSED&renderskin=blueskin

Skin option also allows the user to specify additional parameters. imgStyle, attrStyle will add an additional image or attribute instead of replacing the default.

For further detail in configuration’s usage refer  to ImageServer Configuration.

Recommendation Parameters <recParameters>

Legacy Syntax Parameters

GuideRender request URLs utilize the same parameters as GuideRest.

- /baynote/guidelink?cn=&cc=&guide=&index=&passThru=&fallback=&linkSrc=
Parameter NameDescriptionOptions
index1-based rank of recommendation item to render. Required when using multiple IMG tags. If using multiple IMG tags, then each tag should request an increasing index starting with 1. Should not be used when using imagemap.Required
cc or codeCustomer codeRequired
cn or customerIdCustomer nameRequired
urlURL for context-sensitive algorithms like AlsoUsed and NextStep. (For Collections APIs, this parameter can be used ot specify items present in the user’s collection).Optional, but Recommended

Rendering Parameters <renderingParameters>

All rendering parameters in Thor RS API syntax can be used here too. Rendering Parameters are common parameters.

GuideLink Legacy API

Format for using GuideLink with legacy format will be provided.

Link API Parameters

GuideLink Original Syntax

URL: http://:/baynote/guidelink?&
Example:

- /baynote/guidelink?cn=suresource&cc=hershey&guide=HomeRec&index=1&url=http%3A%2F%2Fwww.hersheysstore.com%2F&passThru=bnec%3DHomeRec

Original Syntax RecParameters

GuideRender request URLs utilize the same parameters as GuideRest

- /baynote/guidelink?cn=&cc=&guide=&index=&passThru=&fallback=&linkSrc=
Parameter NameDescriptionOptions
cn or customerIdCustomer nameRequired
cc or codeCustomer codeRequired
index1-based rank of recommendation item to render. Required when using multiple IMG tags. If using multiple IMG tags, then each tag should request an increasing index starting with 1. Should not be used when using imagemap.Required
urlURL for context-sensitive algorithms like AlsoUsed and NextStep. (For Collections APIs, this parameter can be used to specify items present in the user’s collection).Optional, but Recommended

GuideParameters

The same parameters considered on Thor RS Syntax are shared and can be used with Legacy Syntax.

Parameter NameDescriptionOptions
fallbackFallback URL to go to in case the given index does not exist (there is no result for the index).

For example, if the email recommendation tags that are set up for the customer expect 4 results, there will be HTML tags for images with corresponding links. If the dynamic recommendation only comes back with 3 actual results, then there will be 3 blocks (index 1-3) with actual recommendations and 1 block (index 4) with a blank image. Clicking on the image corresponding to index #4 will go to the fallback URL.

Optional
passThruURL-encoded string to add to the target product URL. Usually a set of parameters to pass to the target page. Text added with this function to the URL gets added after a ’&’ character in case the resultant URL has parameters on it and responds adding a ’?’ character in case there were no parameters on the resultant URL.

Note: The resultant url is formed based on the attribute passed in linkSrc. If linkSrc parameter is empty or not passed, url attribute is used from the resultant url. In case of any redirection of the resultant url, the passThru parameters will be lost hence the target page will not receive those parameters.

Optional
linkSrcLinkSrc allows guidelink REST request to return a link other than the url that the document is stored as. User should specify the source field from where this url is going ot be taken for redirection. In case linkSrc specific attribute is not found on source, Link will proceed using regular URL.

Optional

ProductRTI Dev: Image Server API