REST API Implementation
There are several steps to implementing RTI with Kibo’s REST API:
- Observe site,
- Provide Product Catalog Feed,
- (Optional) Other Offline Sources of Information, and
- Deploy Kibo RTI Recommendations
Step One: Observe Site
Deploying Standard Kibo RTI Observer Tag on the Site
To implement the observer tag, add the baynote.js include tag to the website’s footer template to ensure that it is placed on all the web pages. In most content management systems, information added to the template will propagate to all the web pages in the system.
- Download a copy of baynote.js from the Kibo RTI servers. The Kibo project team can provide the location of the script and customer observer tag for download.
- The website must have the file hosted on the web server.
- Insert the file towards the bottom of the webpage (preferably immediately before the closing BODY tag).
More detailed steps can be found here.
Additional Observer Tag Configurations
- Purchase Observations
- Product ID Capture (REQUIRED)
- Search Term Capture (OPTIONAL)
- User Information Variables (OPTIONAL)
Note the following when defining the purchase information variables:
- The price must not have a comma as a separator (e.g. “2099.32” NOT “2,099.32”).
- Only a “.” is supported for fractions of a monetary unit. The product ID should match the unique identifier that is provided to Kibo RTI in product catalog attribute “ProductId”.
- Each cell in the bnOrderDetails array can have only 2 colons. This means that the productID cannot contain a colon because the colon is a parsing character.
- The product quantity in the bnOrderDetails array must be an integer.
- Quantity must be an integer and should not contain fractions or decimals.
Product ID Capture (REQUIRED)
Kibo RTI needs to be able to capture the product id of the product on a product detail page. The product id needs to be mapped to the product id that is in the catalog. The product level being sent in the catalog (parent vs. variant vs sku vs etc) is the same product level id that needs to be on the product detail page.
The following is a sample of the code to include.
Search Term Capture (OPTIONAL)
Kibo RTI needs to be taught the difference between a normal content page on a website and a search-results page. A search-results page is any page that was reached after a visitor types a query into a search box or search form.
User Information Variables (OPTIONAL)
<<CUSTOMER>> external user ID – bnExtUserId Geo Location (country code, state, and/or city) – bnCountry, bnState, bnCity New vs Return Visitor – bnReturn etc.
The following is a sample of the code to include.
Step Two: Provide Product Catalog Feed
A feed defining the attributes for each product in the catalog should be uploaded to Kibo’s SFTP server at ftp.baynote.com. Attributes are name-value pairs that store additional information about a product. Kibo RTI uses the attributes of products for two purposes:
- To be displayed as part of the Kibo RTI results. Examples include references to thumbnail images, prices, titles, etc.
- To use in a filter expression on Kibo RTI results. For example, results will include only products if the content is tagged with an attribute identifying products.
Following is a list of suggested attributes which may be included in the catalog. Attribute names may vary, and hierarchical as well as multi-valued attributes are supported.
- Product URL: The product url
- ProductTitle: Title of the product (To be displayed in Results)
- Price : Price (To be displayed in Results. Do not include currency symbol.)
- ProductId: Unique Identifier for product (should be same as order confirmation productId)
- Description: Explanation on the product.
- ContentType: Content for Kibo RTI to filter on – show only promos for the promo personalization zone. Can be multi-valued attribute (Example – promo,offer). Please use consistent delimiter
- ImageURL: Thumbnail of product (Used for displaying an image in returned Results)
- Location: The location of the promo/musician/lesson/etc.
- Availability: Can either be true/false or a number to filter on.
- Segments: What segment this product falls under. For example, Student, Teacher, both, etc.
- IsBlackList: Mark as “True” to blacklist an item globally, otherwise “False”
- PageType: mark as “Product” for products.
- onSale: Y/N. If the product is on sale on the website.
Here’s a sample catalog in Kibo RTI format XML:
<document name="http://www.yoursite.com/sale/saxophone-AA002"> <ProductId>AA002</ProductId> <PageType>Product</PageType> <ImageURL>http://images.yoursite.com/mgen/master:AA002.jpg?is=400,400</ImageURL> <ProductTitle>Saxophone Lacquer</ProductTitle> <ContentType>Instrument</ContentType> <Price>338.40</Price> <IsBlacklist>True<IsBlacklist> <onSale>N</onSale> <Description>Saxophone</Description> <Location>US</Location> <Availability>True</Availability> <Segments>Student</Segments> </document>
Here’s a sample catalog in CSV:
Name,ProductId,PageType,ImageURL,ProductTitle,ContentType,Price,IsBlacklist,onSale,Description,Location,Availability,Segments “http://www.yoursite.com/sale/Saxophone-AA002”, “AA002”,”Product”, “http://images.yoursite.com/mgen/master:AA002.jpg?is=400,400”, “Saxophone Lacquer”, “Instrument”,”333.40”,”True”,”N”,”saxophone instrument”,”SG”,”True”,”Student” ****Pipe or commas as separators are preferred*****
It is important that the XML be well formed. Common mistakes in formatting include:
- All special symbols need to be in UTF-8 format. For example, the copyright symbol needs to be passed in as: © instead of “©” in the feed.
- Malformed xml/csv: Either the elements are not ending properly in an xml file or there are not enough columns per row in a csv file.
A common mistake is manually ensuring that the data is properly formatted for a test catalog but failing to add validity checks to future catalog exports. Ensure that the XML in the automated catalog export is well-formed and validated. To learn more about XML validation, refer to http://en.wikipedia.org/wiki/XML_validation.
Please note that a FULL load must be provided every time – which means a complete product feed.
Please configure the product feed and schedule automated updates based on the details provided in the questionnaire. Please notify a Kibo RTI Representative with location of the feed once complete.
Kibo RTI will then schedule regular updates (as defined by the questionnaire response) to pull the feed.
Step Three: (Optional) Other Offline Sources of Information
Kibo RTI can also optionally accept other off-line sources of information, such as purchase data or user related data. Note that user related data (non-purchase data) would either require the Kibo RTI user ID as part of the upload or have the corresponding Customer external ID available on the site in order for Kibo RTI to associate the upload information with the observed data.
If off-line user or purchase data uploads will be used, refer to the Kibo RTI User Import Document as a reference.
Step Three: Deploy RTI Recommendations
Recommendation Deployment via REST API
This Kibo RTI deployment method gives more control over the appearance of the Kibo RTI content on the website but requires more initial configuration effort. The web server communicates with Kibo RTI and sends requests via a REST API. Kibo RTI then returns the data in XML or JSON, and the web server converts this data to HTML before sending the results to the browser.
To deploy Kibo RTI Personalization Zones, do the following:
- Ensure that “baynote.js” tag is included on all web pages. See Deploying Standard Observer tag on the site.
- Make an API call to Kibo RTI to get back results as explained in Recommendations API section below.
- Ensure Kibo RTI tracking parameters are added to the rendered recommendations as explained in Recommendations Tracking.
This output API provides a REST-based interface to retrieve results from Kibo RTI. When the web server sends a request in the following format, Kibo RTI uses this information to return the relevant content.
A request will look similar to the following
http://@customerid-@code@.baynote.net/recs/1/@customerid_@code@?pageTemplate=@pageTemplate &attrs=@attrb1&attrs=@attrb2...&productId=[productId]&url=[productUrl]&userId=[bn_u cookie value]&query=[search term]
When using GET, requests must be 7,830 characters or less.
The following table lists the request parameters for the Recommendations API.
URL for context sensitive Templates and Widgets. Required for recommendations contextually relevant to a web page. Can be used for page template routing function if source parameter is not present. Optional if widget or pageTemplate.Multiple url params may be used in a single REST call in certain cases, such as Shopping Cart where the recommendations should be contextual to all the items currently in a user’s cart. Urls should be encoded.
|Optional but recommended. Required for recommendations based on context.|
|pageTemplate||A container of widgets defined in the Web Recommendations Page Templates tab.||Optional but recommended if the url parameter is not used.|
|query||Query string for TermGuide. 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 ignored and TermGuide will be used instead.||Optional but required for TermGuide.|
|userId||Kibo RTI user id for the user making the call. It is the value in bn_u cookie.||Optional.|
|attrs||List of document or product attributes defined in the catalog feed to be returned in the result. If set to * all attributes will be returned. To request multiple attributes, use the attrs parameter multiple times: attrs=attribute1&attrs=attribute2||Optional.|
Similar to url parameter but specific to recommendations contextual to a particular product ID defined in the product catalog feed.
Multiple productId params may be used in a single REST call in certain cases, such as Shopping Cart where the recommendations should be contextual to all the items currently in a user’s cart.
|Optional. Not needed if url parameter is used.|
|source||Location of the page from where the RS request is generated. Needed if url parameter is a value other than the current page AND routing is being used.||Optional.|
|visitstrail||Browsing history in the form of CSV of urls. Include when the bn_documentVisitsTrail cookie is being used. Content of cookie passed via this parameter.||Optional, but should be included on all REST requests where applicable.|
|pagetype||Page type needed for routing. Used for routing if different page types in use AND routing varies by page type.||Optional.|
|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. Example: format=json||Optional. Default is XML.|
The results are returned in the HTTP response body in XML format, unless the output format was specified to be HTML or JSON.
Note the following in relation to Kibo RTI responses:
- Each result document is returned in an <slotResults> element. Basic details about the document are returned as XML attributes of <slotResults> element.
- Document attributes requested in the request parameter attrs are returned as <attrs> child element.
The following are Kibo RTI response elements and their associated attributes.
- recResult – Required element containing all results. This is the root element. The table below outlines recResult related item data.
|recResult||Root level element. Contains all the results. It is a single complete response.|
|responseId||Unique identifier of the response.|
|merchModel||MerchModel checkpoint id of the MerchModel for which this response is generated.|
|type||Indicates if the response is from a widget or page template. Allowed values – widget or pageTemplate.|
|Id||Widget name or the page template name associated with the response.|
|trackingData||trackingData is an opaque base 64 encoded string token which is used to bcp 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 general and more from AB test perspective. The test info from the tracking data is used for analysis by the Data Science team.|
|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.|
|ABTest||Top level element containing information on an AB Test, if running.|
- widgetResults – Required element containing all results for that widget. The table below outlines widgetResults related item data:
|Id||Unique widget name.|
|algoName||Algorithm executed to give results for the widget.|
|widgetId||Unique system generated internal identifier associated with the widget.|
|displayName||User controlled output to be used for the display name for the widget, such as “You may also like”. Can be updated via VUE console.|
|placeholderName||Value to consistently assign output to proper element on the page, typically a div ID. This can be updated/controlled via the VUE console. This is to be used to map the output onto the page for display purposes.|
|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.|
- slotResults – Optional element containing one recommendation item. The table below outlines slotResults related item data:
|slot||Slot number the recommendation is associated with.|
|url||url of the recommended item. NOTE: This is the Kibo RTI internal identifier and has normalization rules applied to it. Best practice is not to use this for links on the site, but to use the “sourceUrl” parameter (confirm attribute name) that contains the document url provided to Kibo RTI..|
|attrs||Attributes associated with the product. Kibo RTI recommends using the “sourceUrl” or “productID” attribute for the sake of identifying the item. This information can be used to look-up the content from the local system, or the other required attributes can be identified via this parameter in the REST request|
|Explanations||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 purposes.|
|context||Similar to Explanations, providing information contextual to the candidate item’s inclusion in recommendation response.|
- ABTest – Optional element containing information regarding any active AB Test. Typically will not be present, but should be recognized if it is running.
|mrechLabel||Internal Kibo RTI identifier for the merchandizing version.|
|testName||Name of the AB Test.|
|variantName||Version of the test that is returned.|
The following is a sample response.
<recResult> <responseId>5285702529109-1</responseId> <merchModel>185317b0a80126f4bfa71177f1e7ec91ffc8a186726ad08eb998e3026cdc0fff:1402609439388</merchModel> <trackingData>37879384693486460498640694050694045</trackingData> <type>widget</type> <id>testCase1</id> <widgetResults> <id>testCase1</id> <displayName>You May Also Like</displayName> <placeholderName>DivID_1</placeholderName> <algoName>engagementrec</algoName> <slotResults slot="1"> <url>http://www.mysite.com/crystal-bridesmaid-tank.aspx</url> <attrs> <name>Price</name> <values>18</values> </attrs> <attrs> <name>Title</name> <values>crystal bridesmaid tank</values> </attrs> <Explanations/> <Context/> </slotResults> </widgetResults> <ABTest> <merchLabel>538957395730398</merchLabel> <testName>Sample Test Name</testName> <variantName>B</variantName> </ABTest> </recResult>
To view the response in JSON format, add the parameter: format=json in the REST call.
REST API Calls
Templates should be set-up with placeholders that correspond to the “div ID’s” or placement of the recommendations. Templates should also include Display Names that can be shown to users when viewing the content. More information follows.
Generic REST call (values surrounded by @..@ represent where the specific values associated with the site would be included).
Based on an instance where the customerid is “acme”, the code is “www”, there is one context url which is the same as the page source, the user is on a page that generally does NOT have query terms, and there are two items in the bn_documentVisitsTrail cookie.
The placeholder element allows the user to map a standard output value for multiple Page Templates. For example, if the Kibo RTI Page Template will have more than one widget output and the content will be injected into particular Div ID’s in the page, the placeholder values can be set to the name of the appropriate Div ID’s. This is particularly helpful when routing is being used, as the user could add new Page Templates to use under certain circumstances (different contexts), but the same rendering code could be used to inject the content without any modification to the code. The placeholder element is the preferred way to determine where to place recommended content. Do NOT use displayName or algoName elements for this purpose. The widgetResults id element should also not be used as this limits where routing can be used.
Tracking the usefulness of Kibo RTI results is critical for making the necessary algorithm and filter modifications to meet business needs. For Kibo RTI to track result usage, include several specific parameters in the link that is displayed on the site. These parameters are outlined in the following table. These values, BNData in particular, are also required in order for AB tests to work and be reported on properly.
|Anchor Tag Attribute||API Response Element/Attribute||Description/Usage|
|data-baynote-slot||/recResult/widgetResults/slotResults/@slot||The value of what number the result is in the returned content (i.e. 1 if the first result, 2 if the second result, 3 if 3rd result, etc.).|
|data-baynote-widget||/recResult/widgetResults/id||The name of the type of widget requested (i.e. the name passed as the “widget” parameter in the request).|
|data-baynote-pid||/recResult/widgetResults/slotResults/attrs[name=’ProductId’]/values||Applicable to ecommerce only: the product ID of the item being recommended.|
|data-baynote-variant||/recResult/ABTest/variantName||Only defined when AB Test running. Should be included in tracking to denote variant of AB test when running. If element does not exist in the returned REST request results, then this tracking tag can either be suppressed or populated with “undefined.”|
|data-baynote-href||/recResult/widgetResults/slotResults/url||The value of the canonical url.|
Follow the below sample code to show how to include data on the webpage for tracking.
REST API Best Practices
The following best practices are applicable to all Kibo RTI REST APIs. Kibo RTI recommends following these best practices guidelines whenever possible.
Make APIs Viewable for Debugging
When people outside of the deployment group ask why certain products are recommended or search results displayed, it is important to know what API calls were made to Kibo RTI to produce those results. If APIs are made available to select users, more people can help answer these questions and debug other issues.
To allow a select few people to view the API calls made for any specific page, do one of the following:
- Add support to the webserver such that when someone is viewing a page on the website and adds a URL parameter such as bnapi=true or bndbg=1, then the API call is shown. As this is strictly coded for the site, any URL parameter can be chosen. The API call can be displayed on the page or added to a hidden div in the HTML of the page.
- Write the API call into a hidden div on the page.
Handle API Errors and Timeouts
It is possible that the REST API may return an error code or timeout. Code the API call to handle these situations. Specifically, be aware of 404 errors and 503 errors.
See the full list of HTTP error codes on Wikipedia.
Additionally, write the code to handle a server that is unresponsive. Wait no longer than 1,000ms for the Kibo RTI API to respond. If it does not, then the code should continue rendering the page. Page rendering should not be blocked by a slow API response.
Include User ID in API Call
Kibo RTI recommends including the userId parameter in REST API calls. This parameter can be found in the bn_u cookie and is useful for AB testing and supporting some recommendation types.
- Use placeholders to determine where to inject content on the page
- Ensure Recommendation Tracking parameters are in place in the rendered content.
- Use “sourceUrl” or productId for product look-ups or creating links on the site. Do not use the “url” parameter.
- Use the value from the “displayName” element for the widget display text. This way users can update/reconfigure the name without assistance from the technical team.
- Include the “query” parameter with associated value in REST requests where possible, as that allows using the added context of the query term.
- Include the “visitstrail” parameter with associated value by collecting the value from the bn_documentVisitsTrail cookie. If the cookie is undefined or empty, no value needs to be passed.
- Only include attributes that will be used for display or post processing in REST requests attr parameters. Additional elements will only require more data to be transmitted with each call.