RESOURCE CENTERRTI DOCUMENTATION

This page is a dedicated section of our RTI documentation to get step by step help for using the Single Page Application Implementation(s)

REST API Implementation

There are several steps to implementing RTI with Kibo’s REST API:

  1. Observe site,
  2. Provide Product Catalog Feed,
  3. (Optional) Other Offline Sources of Information, and
  4. Deploy Kibo RTI Recommendations

Step One: Observe Site

Deploying an Observer Tag is the most efficient and simple way of gathering the necessary collective intelligence data from the website. The JavaScript tag is placed within the site’s global footer template, which will propagate the tag throughout the site. When people visit the website, the JavaScript tag is executed on their browsers and sends navigation observations to Kibo RTI. Depending on the website’s traffic volume, the observer tag needs to run for at least 7 days to collect sufficient data for Kibo RTI to identify trends and affinities.  Actual initialization phase duration will vary depending on site traffic and number of documents to process.

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.

  1. 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.
  2. The website must have the file hosted on the web server.
  3. 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

Additional configurations need to be made to the Observer Tag to further define the observation process or content. JavaScript variables to be used by the Observer Tag need to be defined before the RTI observer is called. The following additional configurations (JS Variables) are required:

  • Purchase Observations
  • Product ID Capture (REQUIRED)
  • Search Term Capture (OPTIONAL)
  • User Information Variables (OPTIONAL)

Purchase Observations

Purchase information such as amount and order ID can be captured by the observer tag. This configuration is required to measure the monetary performance of Kibo RTI. When customers complete a purchase, additional information such as the purchase amount and order ID need to be captured by the observer tag. To do this, please define JavaScript variables on the purchase confirmation page.For example, if the order ID is 123 with 2 items for the total amount of $2099.99, then information passed to Kibo RTI will look similar to the following:

<script type="text/javascript">
var bnOrderId = '123';
var bnOrderTotal = '2100.99';
var bnOrderDetails = new Array();
// Product ID 1001 x 2 @ $50.00 each (productid:quantity:price)
bnOrderDetails[0] = "1001:2:50.00";
// Product ID 1002 x 1 @ $2000.99 each
bnOrderDetails[1] = "1002:1:2000.99";
</script>

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. 

On ALL Product Detail Pages, the productid must be exposed via a JavaScript variable. The variable name needs to be bnProductId. This variable needs to be populated before the observer file executes on the page.

The following is a sample of the code to include.

<script type="text/javascript">
var bnProductId = “7987sadg97”;
</script>

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.

To do this, include a JavaScript variable like bn_SearchTerm that contains the query term added by customers. Kibo RTI will read this variable to capture search terms from the site. The following is a sample of the code to include.

<script type="text/javascript">
var bn_SearchTerm = “careers”;
</script>

User Information Variables (OPTIONAL)

In Order for Kibo RTI to show relative page content to the user, Kibo RTI needs to know some information on the user. To do this, include JavaScript variables. Some examples are below.

<<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.

<script type="text/javascript">
var bnExtUserId = “A4585”;
</script>

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:

  1. To be displayed as part of the Kibo RTI results. Examples include references to thumbnail images, prices, titles, etc.
  2. 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*****

XML Validation

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 “&copy” 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:

  1. Ensure that “baynote.js” tag is included on all web pages. See Deploying Standard Observer tag on the site.
  2. Make an API call to Kibo RTI to get back results as explained in Recommendations API section below.
  3. Ensure Kibo RTI tracking parameters are added to the rendered recommendations as explained in Recommendations Tracking.

Recommendations API

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.

Request Parameters

The following table lists the request parameters for the Recommendations API.

ParameterDescriptionNotes
customerIdCustomer nameRequired.
codeCustomer codeRequired.
url

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.
pageTemplateA container of widgets defined in the Web Recommendations Page Templates tab.Optional but recommended if the url parameter is not used.
queryQuery 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.
userIdKibo RTI user id for the user making the call. It is the value in bn_u cookie.Optional.
attrsList 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=attribute2Optional.
productId

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.
sourceLocation 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.
visitstrailBrowsing 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.
pagetypePage type needed for routing. Used for routing if different page types in use AND routing varies by page type.Optional.
formatXML 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=jsonOptional. Default is XML.

Response

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.
ElementDescription
recResultRoot level element. Contains all the results. It is a single complete response.
responseIdUnique identifier of the response.
merchModelMerchModel checkpoint id of the MerchModel for which this response is generated.
typeIndicates if the response is from a widget or page template. Allowed values – widget or pageTemplate.
IdWidget name or the page template name associated with the response.
trackingDatatrackingData 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.
widgetResultsTop 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.
ABTestTop 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:
ElementDescription
IdUnique widget name.
algoNameAlgorithm executed to give results for the widget.
widgetIdUnique system generated internal identifier associated with the widget.
displayNameUser controlled output to be used for the display name for the widget, such as “You may also like”. Can be updated via VUE console.
placeholderNameValue 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.
slotResultsTop 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:
ElementDescription
slotSlot number the recommendation is associated with.
urlurl 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..
attrsAttributes 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
ExplanationsTop 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.
contextSimilar 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.
ElementDescription
mrechLabelInternal Kibo RTI identifier for the merchandizing version.
testNameName of the AB Test.
variantNameVersion 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).

http://@customerid@-@code@.baynote.net/recs/1/@customerid@_@code@?attrs=Title&attrs=Price&attrs=ProductId&attrs=ThumbUrl&attrs=SourceUrl&query=blue+items&url=@encoded_context_url_1@&url=@encoded_context_url_if_more_than_one@&source=@encoded_url_of_page_user_on_if_different_from_context@&userId=@value_from_bn_u_cookie@&visitstrail=@first_encoded_url_from_bn_documentVisitsTrail_cookie@&visitstrail=@second_encoded_url_from_bn_documentVisitsTrail_cookie@&visitstrail=@third_encoded_url_from_bn_documentVisitsTrail_cookie@

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.

http://acme-www.baynote.net/recs/1/acme_www?attrs=Title&attrs=Price&attrs=ProductId&attrs=ThumbUrl&attrs=SourceUrl&url=https%3A%2F%2Fwww.acme.com%2F-%2Fi%2FG5165221%2F&userId=6926108564241479216&visitstrail=http%3A%2F%2Fwww.acme.com%2Fi%2FG1226057&visitstrail=http%3A%2F%2Fwww.acme.com%2Fi%2FG5165221

Placeholders

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.

Content Tracking

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 AttributeAPI Response Element/AttributeDescription/Usage
data-baynote-slot/recResult/widgetResults/slotResults/@slotThe 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/idThe 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’]/valuesApplicable to ecommerce only: the product ID of the item being recommended.
data-baynote-variant/recResult/ABTest/variantNameOnly 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/urlThe value of the canonical url.

Add the single /recResult/trackingData value returned by the Kibo RTI API REST response as a JavaScript variable named “BNData” anywhere in the page’s HTML <body> tag.

Follow the below sample code to show how to include data on the webpage for tracking.

<html>
....
<body>
...

<a data-baynote-slot="1"  data-baynote-widget="HomePage" data-baynote-pid="12345" data-baynote-variant=”B” href="http://blah.com/products/183">Loudspeaker</a>

<a data-baynote-slot="2" data-baynote-widget="HomePage" data-baynote-pid="6789" data-baynote-variant=”B”  href="http://blah.com/products/206">Holiday Pack: Gingerbread Hack</a>

<a data-baynote-slot="3" data-baynote-widget="HomePage" data-baynote-pid="24680" data-baynote-variant=”B”   href="http://blah.com/products/146">Light It</a>

<a data-baynote-slot="4"  data-baynote-widget="HomePage" data-baynote-pid="13579" data-baynote-variant=”B”  href="http://blah.com/products/145">Wireless</a>
....
<script type="text/javascript">
var BNData = “01eJxtj7FuwzAMRP+FswaJliXZW7d2KTJ0KzLIImUEleXAUdHByL9HiI0EBQIuvHdH4LhCWNgXprcCvdKIsm0VKieVgBNBDyiV7hqD1KFBa9hrwqE1Fh05hx0FClE3g7FaWxltjORbF6S0g+1cAwIKX8pHjjP0+TclAWc/8qbX+154OqfaYGNw+HqfJz5UA64C/k5UE5v1ve7y009ck4+cAJ/Geaecx8omzmXhUK1Lmp/3949UpYvPP1uhq9gxvsbNa6z/42OdG5SgZv8=”
</script>
....
</body>
</html>

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.

Other Considerations

  • 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.