Integration Guide

1. Catalog Upload Implementation

The first step to implementing the Strands Recommender solution is to upload your product catalog. Below are three ways of physically uploading the data, but before we begin the upload you need to give us some details about your data feed for mapping purposes. These settings can be changed by simply logging in to your account and navigating to “Config” > “Catalog format”.

From the drop down list you’ll need to select first of all the type of catalog your have. Multiple formats are supported such as XML, ATOM or delimited files amongst others.

catalog_type

In the case of delimited files you’ll have to designate how the fields are separated with the Field Delimiter drop down ( usually by commas or tabs ). Also, for those with delimited catalogs you’ll have to select the what type of text qualifier you’re using with the drop down to designate text strings ( i.e. “Cool Thing” versus ‘Cool Thing’ ). Finally, for delimited catalogs you’ll have to select a list separator so that multiple values can be imported in a single field ( i.e. small|medium|large or chocolate:vanilla:strawberry ). If your delimited catalog doesn’t have lists inside fields, simply ignore this drop box.

In some other formats such as XML you will have to provide the name of the nodes that define a product so that the system can figure out how to split the file.

Let’s see some examples. Please note that the following catalogs are just intended for illustration purposes. The available fields in a real scenario could be very different.

In this example we’ll show a delimited file separated by commas:

csv

An XML feed might look like this:

catalog_xml

The next step is mapping the fields from your catalog. Our system will dynamically pick up the names of all of the fields that you provide, regardless of the naming convention used in your feed. The first time you try to upload your catalog it will most likely fail, since our system won’t know the available field names until the first attempt. After the first attempt you can set the mappings and retry.

There are 7 main fields we are interested in at this point:

catalog_fields

The first four are required (id, title, link, category). The other fields are not required, but recommended in order to make our system perform better (if you’re missing any of these, just leave the selection blank).

Additionally, we suggest that you include any attributes that you think might be relevant as additional fields. We are usually interested in data that will be useful to either define the product and its relationships to others (such as color, size, brand…) or to filter the recommendations (stock, margin). Internal details or identifiers that would not help a person understand your products, will usually not add value to our calculations and should be omitted (unless you would want to use them when rendering the recommendations, think of ISBN for instance).

You’ve completed the file mappings! Now it’s time to execute the actual file upload. You can do this over FTP, scheduling a feed downlowad or via a one time upload right from the dashboard. Whichever ways works best for you.

Browser based manual upload

In order to test your first catalog or if you want to do a one time upload at any point you can upload your catalog in the browser by simply logging in to your account and going to “Config” > “Catalog format”. You should then scroll to the bottom of that page and click on“Choose Import Method” and then “Upload”. If this is your first upload, make sure to check the box for “Complete Catalog” and then use the browse button to manually select the file from your machine.

Please note the maximum file size is 5 MB for this approach.

upload

You can monitor the status of the file upload by navigating to “Catalog” > “Upload history”. Please note that this process will fail if the field separators or name associations configured in the previous step are not accurate.

Now you’re ready for step 2 Behavioral Tracking Implementation!

Periodic Feed

If you already provide (or if you can create) a feed URL from which your product catalog can be downloaded, we can have it fetched automatically from you at the frequency you decide. Simply, navigate to “Config” > “Catalog format” and select “Feed” at the import section.

We need you to provide the URL for your feed and any required credentials to access it (user name and password if access would be required, leave blank otherwise). Make sure to check off the “Import now and at scheduled time” if you don’t want a test download to happen right then.

feed-import

Finally, use the frequency settings to the right to designate how often you’d like the catalog to be downloaded. This is entirely up to you but a daily download is usually enough for most customers.

You can monitor the status of the file upload by navigating to “Catalog” > “Upload history”. Please note that this process will fail if the field separators or name associations configured in the previous step are not accurate.

Now you’re ready for step 2 Behavioral Tracking Implementation!

FTP Upload

In order to automate the catalog synchronization and if you want to control the frequency at which the catalog uploads happen, you can do so by navigating to “Config” > “Catalog format” and selecting “FTP”. You can then start pushing files into our FTP server:

ftp://recommender.strands.com

Please note the following:

  • Your username and password default to the ones you’ve used to log into the dashboard (this can be changed from your “account” section if needed).
  • If you have a complete catalog to upload, change your directory to: /catalog/complete
  • If you have a partial catalog to upload, change your directory to: /catalog/partial
  • Pick a reasonable frequency for the uploads that meets your needs. Daily uploads work best for most accounts.
  • You can monitor the status of the file upload by navigating to “Catalog” > “Upload history”.

Now you’re ready for step 2 Behavioral Tracking Implementation!

2. Behavioral Tracking Implementation

Integrating our behavioral tracking codes is essential to start getting the most out of our personalization engine. The codes enable us to start aggregating relevant actions as user profiles that help us both better understand your store (by extracting its collective wisdom) and personalize its shopping experience.

The behavioral tracking implementation process is as simple as updating a few of your of your site’s pages to include pre-formatted calls to our system. The approach is quite similar to that of other tracking tools such as Google Analytics and the documentation for the process can be found in ourjavascript tracking reference page.

Our dashboard offers as well a tracking code wizard that will help you create the different code snippets. Each tracking code is intended to be used in a specific page type within your site (such as product pages or the order confirmation one).

In order to access the wizard log into the dashboard, navigate to “Config” > “User tracking” and select the type of event you wish to track. You can then copy and paste the generated codes into the appropriate pages with a few minor edits. All you have to do is update the input fields with the corresponding dynamic parameters in a format supported by your site (product id placeholders for the product pages or the order id for tracking orders for instance).

track-wizard

If one of the behavior types is not relevant to your site, just skip it. Please remember to include the javascript code within the <body> tag and ideally right before the closing </body> one and to validate that our javascript library code part is included only once per page (this can happen easily if multiple events or recommendations are included). Also note that there is an event for tracking recommended product clicks that is automatically triggered for you when using the copy and paste recommendation widgets and that does not need to be integrated in most cases.

You can now move on to Step 3 Integrating Recommendations.

3. Adding Recommendations to your site

Once you have uploaded your catalog and the behavioral tracking is installed you can start offering personalized content to your users.

But before getting into the details, there’s one further catalog-related configuration step that you should execute now. Out of the available non-mandatory catalog properties, we’ll need you to select a few as the self designated more relevant ones. First navigate to “Config” > “Catalog post-processing” and you will see a screen like this (your available properties will probably differ though):

basic_attributes

Simply select the properties that are going to be the most reliably relevant and move them to the right side of the panel. Then click save. You can preview how this will make your catalog look, by navigating to the “Catalog” tab.

You can now start adding personalized content to your site by installing as many recommendation widgets as you see fit across your different site sections: home page, product detail pages, order confirmation page …

The Strands development team has put together a great wizard for completing your recommendation widgets. Log in to you account, select “Recommendations” and you will see a list of pre-designed recommendation templates based on best practices. Just pick one of the top tabs (Home, Category, Product Detail… depending on what part of your site you’d like to create a recommendation panel for) and start making adjustments as needed.

widgets

You should first of all adjust the look and feel of the widgets to match your site design by clicking on the widget’s “Adjust Look and Feel” control. You’ll see a page like the following:

wizard

This page lets you style the recommendation widget with an intuitive wizard. The sample widget at the bottom updates automatically, so you can experiment with the look and feel until you are happy with the results. Go ahead and select the number of recommendations you’d like to show or change the color scheme or the orientation from horizontal to vertical or matrix layout.

Once you have a look you like, save it and go back to the list of widgets by clicking “Back to the list”. Please remember that if the wizard would not be enough to meet your needs there are different extension mechanisms that allow for any custom rendering that might be required. Instructions on how to do that can be found at the bottom of the wizard page. You can also import the looks from any given widget by clicking on the “Import” control in the top right corner.

You might want to review next the type of recommendations to be served by adjusting the “Logic” screen for any given widget. The default widgets included that come preconfigured with your account are based on best practices and can normally work out of the box but feel free to play around with the different settings and add any sort of business rules that would make sense for your catalog (you can find inline documentation for each setting but feel free to contact our support team if you would need any help with that). You can always preview the results in the panel on the right column.

You are finally ready to integrate the widgets on your site. Go back to the “Recommendations” section, click on the “Integrate” control and you will be prompted with an integration wizard that will help you add the integration codes to your site. All you need to do is to follow the instructions in a similar fashion to what you did for the behavioral tracking installation and end up copying and pasting the integration codes from the pop up window to your site.

Congrats! You’re finished! If you have any questions or concerns, please contact support-sbs@strands.com .