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 Name | Comments | Options |
| url | Customer’s page that contains items for generating recommendations. Accepts multiple URL parameters. | Optional, but Recommended |
| ProductId | The contextual product for generating recommendations. Accepts multiple ProductId parameters. | Optional |
| UserId | Kibo 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 |
| widget | A 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 |
| pageTemplate | A widget that allows you to group other widgets together. | Required |
| attrs | To request multiple attributes, use the attribute multiple times: attrs=attribute1&attrs=attribute2 | Optional |
| query | Individual 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 Name | Description | Options |
| ie | Input 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 |
| height | Height 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. | |
| width | Width 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. | |
| orient | Horizontal (H) or vertical (V) layout of multiple items when using imagemap | |
| bgColor | Background color for entire rendered image, specified with a 6-digit RGB hex code excluding the “#” character (for example: 33AABB). | |
| imgStyle | Used 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 |
| textStyle | Global 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. | |
| attrStyle | Used 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). | |
| text | Used to display static text per recommendation. Formatted as a comma-separated list of styling arguments (see below). | |
| imgSrc | Name 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 |
| fallback | In 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 |
| startingDocNum | Determines 1-based rank of the recommendation item to start rendering, usually 1. Should not be used for multiple IMG tags. | Optional when using imagemap |
| resultsPerPage | Required 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.
| Argument | Description |
| name | Name 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. |
| url | URL for static image to use as source. Multiple imgStyle parameters can be specified for static images. |
| borderWidth | border width in pixels (if omitted or if 0, no border will be drawn) |
| borderColor | border color, specified with 6-digit RGB hex. |
Text Styling Arguments
These apply to textStyle, attrStyle, and text parameters.
| Argument | Description |
| font | Name of font to use (Arial, Times, ArialUnicode). NOTE: ArialUnicode should be used for international character support. |
| size | Size of font in pixels. |
| color | Element color, specified with 6-digit RGB hex e.g. 33AABB. No pound sign should be present. |
| style | Font style of element: BOLD, ITALIC, STRIKE, UNDERLINE. Multiple styles can be specified, separated by a space character. |
| align | Alignment: l, r, c for LEFT, RIGHT, CENTER. |
Attribute Styling Arguments
These apply only to the attrStyle parameter.
| Argument | Description |
| name | Name of attribute to display. |
| label | Label 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= |
| labelPlural | If 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. |
| labelEmpty | If present, this label is applied to attributes with an empty or zero value. |
Static Text Styling Arguments
These apply only to the text parameter.
| Argument | Description |
| value | Static text value to display. |
Position and Size Styling Arguments
To be used on textStyle, attrStyle, imgStyle and text parameters.
| Argument | Description |
| h | Height in pixels. |
| w | Width in pixels. |
| x | Horizontal position within item box in pixels. |
| y | Vertical 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 Name | Description | Options |
| fallback | Fallback 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 |
| passThru | URL-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 |
| linkSrc | linkSrc 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 Name | Description | Options |
| index | 1-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 code | Customer code | Required |
| cn or customerId | Customer name | Required |
| url | URL 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 Name | Description | Options |
| cn or customerId | Customer name | Required |
| cc or code | Customer code | Required |
| index | 1-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 |
| url | URL 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 Name | Description | Options |
| fallback | Fallback 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 |
| passThru | URL-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 |
| linkSrc | LinkSrc 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 |