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)

Implementation with JavaScript

There are three steps to implementing RTI with JavaScript:

  1. Observe site
  2. Provide Product Catalog Feed
  3. 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. The 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
  • 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.

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: Deploy Kibo RTI Recommendations

Recommendation Deployment via JavaScript Injection

This is the simplest and quickest method for deploying Kibo RTI Recommendations. This method allows for direct communication between the visitors’ browsers and the Kibo RTI Recommendation engine.

Refer to https://kibo.force.com/customersupport/s/article/javascript-deployment-method?language=en_US

To deploy Recommendations using the JavaScript method, do the following:

  1. Ensure that either the “baynote.js” or “baynote-lib.js” tag is included on all web pages.
  2. Insert a < div > tag onto the pages where recommendations will be displayed.

An optional CSS file can be uploaded to the site. If desired, Kibo RTI can provide a CSS to control the look-and-feel of the recommendations. In this case, the Kibo RTI Engagement Manager can make this available and the CSS file must be uploaded to the website. Alternatively, update the existing CSS file. Either way, ensure that the CSS include tags are inserted into the page template where recommendations will be displayed. Most customers insert them into the page header area. The following are sample CSS include tags.

<head>
<\!-\- BEGIN KIBO RTI INCLUDE \-->
<link rel="stylesheet" href="/css/kibo-rti-guide.css" type="text/css">
<\!-\- END KIBO RTI INCLUDE \-->
</head>

Also refer to https://kibo.force.com/customersupport/s/article/how-to-insert-the-div-tag?language=en_US

To enable Kibo RTI to place specific recommendations in specific areas of specific pages, do the following:

  1. Insert a <div> tag onto those pages and in the location (for example, the right-hand panel) where the recommendations will be displayed. Each tag must contain a specific element ID that corresponds to the HTML element ID specified in the Kibo RTI Recommendations Designer template. In the normal process of page rendering in the browser, these tags will contact Kibo RTI (AJAX-style) and then dynamically render themselves into the page in the designated location. The type and parameters for the recommendations are specified on the tag and the style in which they are displayed controlled by standard CSS.
  2. Log into Kibo RTI Recommendations Designer and define the div IDs for the corresponding recommendation templates. A recommendation template defines a set of pages or content where recommendations will be displayed (for example product pages, a home page, category pages, etc.).  Identify the div IDs by populating the “placeholder” values for the various widgets that will populate the site.  The Kibo RTI implementation team will assist in doing this for the initial roll-out.
  3. (Optional) Create a class in the CSS file using the div ID name so that the browser knows how to display the recommendation. If there are multiple styles for the recommendations, be sure to specify the correct class name here that corresponds to the class that is used in the CSS file. This step is optional because there are other methods for handling this in the CSS.

Example: A website sells designer clothes. Recommendations need to be configured for product pages displayed on the Armani Feather Earrings product page. Define the tag element ID on this product page as “bn_product_rec” and use the Recommendation Designer to ensure that this same ID is configured for the product recommendation template. The tag on the product page would look similar to the following:

<div id="bn_product_rec" />

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.

Kibo RTI will include the Kibo RTI user ID in the requests for recommendations. This parameter can be found in the bn_u cookie and is useful for AB testing and supporting some recommendation types.

Other Considerations – Kibo RTI will consider these when setting up initial personalization mode display:

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