Looking for the v10 manual? Visit our new user's guide!
 
Search Descriptions Version
 
 
This article applies to:

MultiStore 4-Tell Connector Installation Guide

Introduction

Thank you for purchasing AspDotNetStorefront 4-Tell Connector. With the 4-Tell Connector, you can easily connect to the 4-Tell Boost® Recommendation Engine and watch your conversions increase automatically.


Before You Begin


In order to safely complete this installation on a live website you need to be able to back up your site files and database, and have a plan and permission to restore them should you encounter a problem during the installation process. Different hosting providers and environments will have different methods of backing up and restoring databases. Please work with your hosting company to discuss the backup and restore tools that are available to you.

This installation process requires a level of technical expertise. Please read through the entire guide and make sure you understand the whole process before you begin an installation on your live site. If there are any steps of this installation process that are unclear, please contact the help desk to request assistance.
Before you begin, please ensure that:
  • Your site files and database have been backed up
  • You have an account with 4-Tell and know your ClientAlias
  • You have full FTP access to your AspDotNetStorefront site
  • Your site has Read/Write/Modify access to the {root}\Images folder

What To Expect


While you are moving files you should expect that your website will experience temporary outages, and will restart at least once. The installation process should take between half an hour and an hour, depending on how many XML packages you have to modify. If this is a concern, you should consider installing first to a test site.

Installation Process

Adding New Files


  1. Copy the 4tell.css file from the Files\Web\App_Themes\Skin_1 folder in the install package to the {root}\App_Themes\Skin_# folder on your site, where # is the number of the skin your site uses.
    • Note: Multi-Store users may need to add this file to multiple folders, if your stores use different skins.
  2. Copy the fourtellupdate.aspx and fourtellupdate.aspx.cs files from the Files\Web\admin folder in the install package to the {root}\Admin folder on your site.
  3. Copy the 4Tell.recommended.xml.config file from the Files\Web\XmlPackages folder in the install package to the {root}\XmlPackages folder on your site.
  4. Open the Vortx.4Tell.Adnsf9x.dll.config file in the Files\Web\bin folder of the install package, and edit the 2 ‘connectionString’ lines to point to your AspDotNetStorefront store’s database. You can obtain this connection information from your host.
  5. Open the Vortx4Tell.exe.config file in the Files\Web\bin folder of the install package, and edit the ‘ImagesPath’ value with the path to your site’s {root}\Images folder. This should be the full path on the physical drive to your images folder, as shown in the example in that file. You can obtain this path information from your host.
  6. In the same file, edit the’ DBConn’ value to point to your AspDotNetStorefront store’s database. You can obtain this connection information from your host.
  7. Copy Vortx.4Tell.Adnsf9x.dll, Vortx.4Tell.Adnsf9x.dll.config, Vortx4Tell.exe, and Vortx4Tell.exe.config from the Files\Web\bin folder in the install package to the {root}\bin folder on your site.

Updating Existing Files


The steps in this section touch files that already exist on your site. It is important that these steps be carried out by someone who is familiar with editing files, merging code, etc. While we explain each step that is required, if your site has been customized some steps may be slightly different for your site. Please work with your developer to determine what changes (if any) are required.

These steps require opening the “source” file (from the install package) and the “destination” file (from your site) in a text comparison tool like WinMerge, Beyond Compare, etc. In each case, you will be adding code from the source file to the destination file. The line numbers given may not match your site’s files exactly if they have been modified. Once each change is made, save the modified file back to your site.

  1. Open the source and destination kitproduct.aspx files. Copy and paste line 350 from the source file to the same section of the destination file. The bottom of your file should end up looking similar to this:
  2. Open the source and destination kitproduct.aspx.cs files. Copy the 4 lines starting on line 147 of the source file to the same area of your file. The final code should look like this:
  3. In the same file, copy lines 204-236 of the source file to the same area of your file. It should look like this:
  4. Open the \admin\controls\adminmenu.ascx.cs source and destination files. Copy and paste line 167 of the source file to the same section of your file. The final code should be similar to this:
  5. Finally, you need to modify one or more product XML Packages to display the 4-Tell output. You may edit all of the packages, or just the one(s) you actually use on your site. In our example, we will be editing product.simpleproduct.xml.config. These files are in the {root}\XmlPackages folder on your site. There are 2 sections that need to be changed.
First, copy the new query at the top of the source XML package to the same section of your file. The query should go below the existing ones, but above the <PackageTransform> line, like this:


Then, replace this line (usually located towards the end of XML packages):


With the code from that section of the new source file. In the product.simpleproduct.xml.config example, the new code starts on line 280:



Updating the Database

  1. Log in to your site’s admin console, and navigate to Configuration -> Advanced -> Run SQL
  2. Open the \Schema\4Tell_Configuration.sql file that came with your 4-Tell installation package, and copy its contents into the box on the page.
  3. Click Submit:
  4. Click ‘Reset Cache’ at the upper right of your admin console.
Congratulations! Installation is complete.

Required Configuration

This section covers the configuration options that are required before the 4-Tell plugin will work at all. See the Optional Configuration section below for other changes you can make.

  1. Navigate to Products ->4Tell Update in the admin console.
  2. Set the ‘Related Products Source’ value to 4Tell.
  3. Enter the Client Alias you got from 4-Tell in the ‘Client Alias’ box.
  4. Put the email address you would like to receive notifications at in the event of 4-Tell problems in the ‘Point of Contact Email Address’ field.
  5. Put the name you would like notification emails for 4-Tell problems to be addressed to in the ‘Point of Contact Name’ field.
  6. Click the ‘Save Config Changes’ button.
  7. Click ‘Reset Cache’ at the upper right of your admin console.

Displaying products from a category on the homepage

    Submitting Data to 4-Tell

    Before 4-Tell can make recommendations for your customers, it needs to have your product and sales data. To submit that data, navigate to Products -> 4Tell Update in the admin console and click on the ‘Submit to 4-Tell’ button at the top of the page. The plugin will collect your product and sales data and upload that to the 4-Tell service. The results of each run will be displayed as an entry in the System Log.

    Note that sites with multiple stores will all be submitted each time this button is clicked, though each may submit separate data depending on your site’s setup. See the MultiStore section below for more information.

    New data must be submitted to 4-Tell manually by returning to this page periodically and clicking the ‘Submit to 4-Tell’ button. How often that needs to be done will depend on your site. Sites with a high volume of sales or that frequently change products will want to submit often, to keep the recommendations as relevant as possible.

    Once the Installation, Required Configuration, and Submitting Data to 4-Tell steps have been completed, your plugin should be up and running! Browse to a page using one of the XML packages you modified above and you should see your new recommended products displayed:

    Optional Configuration

    The following settings are available on the Products -> 4Tell Update page in the admin console. While the plugin will work with these all left on the defaults, some of them may need to be changed to tune 4-Tell’s recommendations for your site.

    MultiStore

    Each time the ‘Submit to 4-Tell’ button is clicked on the Products -> 4Tell Update page, all of the required product, entity, and sales data is pulled from the store’s database and sent to 4-Tell. Each time is a full submission, not an update. Old data is wiped and replaced with what came up in the latest upload.

    For sites with multiple stores, each time the button is clicked the data for each store is uploaded separately, one after the other. The information that goes up depends on several settings:

    • 4Tell.FilterDataByStore AppConfig – If this is set to true, then each upload will only send up sales data for the store currently being uploaded. This is important if your stores have different customer demographics or shopping patterns and you would like to keep their data separate.
    • AllowProductFiltering GlobalConfig – If true, only products mapped to the store currently being uploaded will be sent to 4-Tell. This will ensure that 4-Tell doesn’t try to recommend products that the current store doesn’t sell.
    • AllowEntityFiltering GlobalConfig – If true, only entities mapped to the store currently being uploaded will be sent to 4-Tell. This ensures that product relationships that don’t exist on the current store (ie Product->Category mappings) don’t factor into 4-Tell recommendations.

    Important: If any of the settings above are true, you must have separate client aliases specified in the ClientAlias AppConfig for each store. This will require multiple 4-Tell accounts. If this is not done, then only the data from the last store uploaded will exist on your 4-Tell account, and product recommendations may not work on other stores.

    Result Types

    4-Tell supports several different types of recommendations. Some of the recommendations take into account personalized data from the current customer (if they are logged in). A brief description of each type is below. The type of recommendation requested is controlled by the 4Tell.ResultType AppConfig. The default is Personalized Cross-Sell.

    • Cross-Sell (ID=0): These recommendations highlight relevant complementary products. They are based on the aggregate sales history of the item currently under consideration by the shopper, whether a known or anonymous visitor. For example, recommendations for a shirt might include pants, jacket and a hat.
    • Personalized Cross-Sell (ID=0): If the shopper is known the cross-sell recommendations are influenced by the shopper. This means that two different shoppers receive different recommendations based upon their previous purchase history; however, recommendations in both cases are bought with the viewed or purchased product. Because these recommendations are related to the product(s) and personalized for the shopper, they are very powerful!
    • Similar (ID=3): These recommendations show comparable (i.e. alternative) products based on common attributes and allow you to present more of your product catalog to the shopper. This is helpful for browsers who have landed on a product page, but find it’s not really what they were looking for. To go back to the shirt example, similar recommendations would include other shirts.
    • Personalized Up-Sell (ID=1): These recommendations show items that the shopper will likely buy. They are driven by the shopper’s individual buying habits and not by any specific product. For this reason, they are best used when the consumer first arrives at your site (i.e., a customized landing page) or in non-product specific email (i.e., monthly newsletter). They are one-to-one, meaning they are unique for each shopper.
    • Blended (ID=2): Just like personalized cross-sell, these recommendations are a combination of both cross-sell and personalized recommendations, so they are available when there are one or more products and a known shopper. The difference is that these recommendations give equal weight to all of the shopper’s purchases and are not as focused on items from the current session. The system will display the most relevant recommendations based on our sophisticated algorithm, taking all known information into account. These recommendations are best used when a shopper has completed a shopping experience, such as order confirmation or user admin pages (if there are items in the cart).
    • Top Sellers (ID=4): These are overall top sellers, or top sellers in a specific category. If a product ID is provided, category top sellers are returned in the main category of that product. Otherwise, overall top sellers are provided.

    Support

    If you have further questions or comments, please feel free to contact our help desk.

    Or contact 4-Tell directly at (971) 217-8355