Product Recommendations - Getting Started

Product recommendations with our implementation model requires a few simple tasks

Table of Content

Questionnaire

Parent Products and Variants

Product Identifiers and Categories for Recommendations

Setting up a basic Data Layer

Setting up your Product Feed

Loading Historical Data

API Only Integration

Getting Started

Changing or implementing product recommendation solutions shouldn’t be hard. Our implementation model ensures you’ll have a few simple tasks, while we do the rest.

Questionnaire

Please take a minute to answer these questions as they relate to the recommendations setup. These will help ensure a smooth implementation process:

  • Are there different versions of product pages? For example, when coming from email/ad campaigns, or from search, mobile vs desktop.

  • Are there any free or add-on products that get added on cart or elsewhere? How are those identified?

  • Do you have multiple order confirmation pages, to support different payment options (e.g. Paypal, Credit Card, …)? 

  • How do we place orders for QA/Validation purposes for the different payment methods?

  • Do you have any plans for website replatforming in the coming months (e.g. SPA, PWA, ....)

  • Are there multiple subdomains or primary domains?

  • Is your site using autocomplete for site search?

  • Is your site leveraging product quick view functionality?

Parent Products and Variants

SiteSpect suggests producing recommendations at the parent level. This approach typically yields higher quality recommendations, by aggregating user behaviors around parent products, instead of diluting that same data across multiple variants. 

As such, each row in your product feed should represent parent products, and information exposed in your data layer should be aligned with parent products as well.

Product Identifier used for Recommendations

Product identifiers are leveraged in the product feed and data layer.

Product ID

  • Should be the same in both your product feed and data layer

  • Make sure that product identifiers are aligned with parents or variants as described above

Setting up a basic Data Layer

This simple data layer identifies key pages and data points needed to produce quality recommendations. Key pages where the data layer is needed are:

  • Purchase confirmation page

  • Product detail pages

  • Quick View (if available)

  • Shopping Cart

  • Category pages

  • Search Results

NOTE:  If your site makes use of product Quick View functionality, make sure that the ‘category’ value is the same on both category and product detail pages.

Here is an example of what the data layer looks like for these key pages:

<!-- Product Detail Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'product',
       'products': [
           {
           'productId': '889987', //should match product feed
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots'] //product's list of categories
           }
       ]
   }
};
</script>

<!-- Product Listing Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'category',
       'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots'] //should match pdp categories
   }
};
</script>

<!-- Cart Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'cart',
       'products': [
           {
           'productId': '889987',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots']
           },
           {
           'productId': '310293',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboards']
           }
       ]
   }
};
</script>

<!-- Order Confirmation Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'confirmation',
       'orderTotal': 246.53,
       'products': [
       {
           'productId': '889987',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots']
           },
           {
           'productId': '310293',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboards']
           }
       ]
   }
};
</script>

<!-- Search Results Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'search',
       'searchString': 'snowboarding gear'
   }
}
</script>

<!-- Any additional page where we would need to show items complementary to the cart (i.e. homepage) -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'home',
   },
   'cart':{
     'products': [
       {
           'productId': '889987',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots']
           },
           {
           'productId': '310293',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboards']
           }
       ]
   }
};
</script>

Setting up a Data Layer for a Single Page Application (SPA)

NOTE: We recommend leveraging existing web analytics and tag manager logic to construct the SiteSpect recommendations data layer.

On a virtual page view, update the data layer according to the examples above, and fire this event:

window.SS && SS.Require(function(){
    SS.Recs && SS.Recs.sendRecsEvent({action: "page-view"});
});

Expose a Unique Customer ID

You can pass your own customer id to stitch user behaviors across different devices:

var ssRecsInfo =
{
   'page': {...},
   'user' : {
       'id' : '12345'
   }
};

Setting up your Product Feed

NOTE: If you already produce a Google Merchant feed or similar, we recommend providing a sample to the SiteSpect team as a first step.

Our specs are loosely based on the Google Merchant Feed. If you already produce such a feed, or a similar feed for other purposes, we recommend starting with what you currently have.

A product feed needs to be exposed and refreshed periodically as part of the onboarding process. SiteSpect ingests this feed and refreshes it daily (can be customized if needed).

The feed is used to display recommendations (name, image, link, price, etc) as well as for filtering and boosting purposes.

 

What products should be included in the feed?

The feed should include all products that are exposed on the website, including out-of-stock, pre-order, and other availability statuses.

 

Availability

You must upload the feed to a publicly available URL location, and update it at a specified frequency. Please communicate the URL location to the SiteSpect team.

 

Format

SiteSpect works with the following format:

  • Text-based tabular data (eg: tsv, csv, etc.)

  • UTF-8 encoded without BOM

  • Delimiter: tab (recommended) or custom

 

Parent vs Child/Variant Items

SiteSpect suggests producing recommendations at the parent level. As such, each row in your product feed should be at the parent level.

 

Required Fields

The recommendation engine requires the following fields:

  • Unique Product Identifier
    • Required.
    • This field needs to match the product identifier (SKU or product id) exposed in the data layer throughout the site, including PDPs and order confirmation page.
  • Availability
    • Required.
    • Values need to be consistent across products.
  • Display Properties (up for discussion):
    • These properties are used to build recommendation templates.
    • Example of fields:
      • Name
      • Image URL
      • Product URL
      • Ratings/reviews
      • Price
      • Sales Price
  • Filtering Properties (up for discussion)
    • These properties are used to filter recommendations in the UI.
    • Try to align with your website categorization, navigation, and search filtering.
    • A general best practice is to split properties into single dimensions with few values. For example, it's always preferable to have product_type and usage as two separate properties, rather than combined under one.
    • For each property, values need to be consistent across products (e.g. two products in the same category should have the same exact category name).
    • For primary categories and dimensions, focus on single values for optimal filtering. For example:
      • product_type: shoes
    • For properties that are treated like tags, a list of values is preferred. For example:
      • product_style = ["Dress","Men's Clearance","Loafers"]
    • If your product feed exposes hierarchical properties, talk to your support team.
    • Examples of filter properties:
      • Primary Category
      • Product Type
      • Usage Type
      • Brand
      • Color
      • Size

      Loading Historical Data

      To accelerate the creation of a mature recommendations model, SiteSpect can ingest historical transaction data.

      We recommended providing at least 90 days worth of historical transaction data. If seasonality strongly impacts the variety of products available in your catalog, consider including up to 12 months of historical transaction data.

       

      Format

      • Text-based tabular data (eg: tsv, csv, etc.)

      • UTF-8 encoded without BOM

      • Delimiter: tab (recommended) or custom

       

      Required Fields

      • Unique Product Identifier

      • Order or transaction Identifier

        • Should be unique to the transaction, and shared by all items in a transaction

      • Datetime of transaction

        • Epoch timestamp, iso8601, or other standardized date format

      • Customer Identifier

        • Unique to the same user across multiple transactions

       

      Example

      A sample file can be provided upon request. See excerpt below:

      order_id

      order_date

      product_sku

      customer_id

      1459357

      2020-10-06 02:23:41.626 +0000

      889987

      601054

      1459357

      2020-10-06 01:28:38.186 +0000

      310293

      601054

      1459447

      2020-10-06 02:03:06.760 +0000

      254286

      601123

      1459962

      2020-10-06 04:41:01.084 +0000

      544465

      601025

      1459994

      2020-10-06 04:27:11.998 +0000

      579289

      601020

      1460013

      2020-10-06 04:27:11.997 +0000

      707648

      601142

      1460021

      2020-10-06 04:38:13.635 +0000

      351857

      601037

      1460025

      2020-10-06 03:44:29.461 +0000

      425677

      601036

      1460032

      2020-10-06 08:55:01.913 +0000

      831919

      601043

      1460032

      2020-10-06 04:38:13.772 +0000

      321012

      601043

       

      API Only Integration

      Product Recommendations are also available using an API-only approach. To take advantage of this approach, follow these steps:

      1. Sync your product feed (same as above).

      2. Send events using the API.

      3. Retrieve recommendations using the API.

      Sending Events Using the API

      Events API Endpoint

      In addition, you will need to track user behavior by integrating specific event calls into your application.

       

      Endpoint for sending events:

      https://recs.sitespect.net/v1/[side-id]/recs/

       

      Example payload for events:

      {
          "events": [
              {
                  "name": "detail-view",
                  "entityIds": [
                      "173608"
                  ]
              },
              {
                  "name": "detail-category-pref",
                  "entityIds": [
                      "Clothes",
                      "Jeans"
                  ]
              }
          ],
          "userId": "G6839736557633606790"
      }

      Successful response for events:

      {
         "events_recorded": true
      }

       

      Events Table

       

      User Action

      name

      entityIds

      multiple: an array of values

      Buy

      buy

      product-id (multiple)

      buy-category-pref

      category name (multiple)

      Product detail view
      Product quick view

      detail-view

      product-id

      detail-category-pref

      category name

      Category page view

      category-view

      category name

      Search results page view

      search-string

      Raw searched expression

      Like
      Share
      Rate
      (optional; only capture positive ratings)

      like-detail-view

      product-id

      like-category-pref

      category name

      Retrieving Recommendations Using the API

      You can include Recommendations in your app with a simple API call. The response from the Recommendation API provides a JSON object that exposes recommended products with their associated attributes (e.g. price, name, link, image link, ...).

       

      In addition, you can specify specific business rules to include/exclude/boost/deboost Recommendations based on many attributes.

       

      API endpoint for retrieving recommendations:

      https://recs.sitespect.net/v1/[site-id]/recs/

       

      People Also Like

      Example API request payload for “People Also Like”, including a boost filter on parent category:

      {
          "item": "228930",
          "rules": [
              {
                  "name": "parentCategory",
                  "bias": 11,
                  "values": [
                      "Bedding",
                      "Sheets & Pillowcases"
                  ]
              }
          ],
          "num": 20,
          "algorithm": "people-also-like"
      }

      Complementary

      Example API request payload for “Complementary”:

      {
          "itemSet": [
              "D107",
              "B890"
          ],
          "rules": [],
          "num": 20,
          "algorithm": "complementary"
      }
      

      Personalized

      Example API request payload for “Personalized”:

      {
          "user": "G6769572760122298386",
          "rules": [],
          "num": 20,
          "algorithm": "personalized"
      }

      Popular

      Example API request payload for “Popular”:

      {
          "rules": [],
          "num": 20,
          "algorithm": "popular"
      }
      

      Recently Viewed

      Example API request payload for “Recently Viewed”:

      {
          "user": "G6769572760122298386",
          "num": 20,
          "algorithm": "recently-viewed"
      }

      Example of Recommendations Response

      [
          {
              "id": 176726,
              "sku": "4324321",
              "clientId": 5,
              "link": "https://www.site.com/store/product/microfiber-sheet-set/4324321",
              "price": "59.99",
              "product_type": "Sheet Sets",
              "name": "400-Thread-Count Solid Sateen Sheet Set",
              "available": "true"
          },
          {
              "id": 176725,
              "sku": "3543534",
              "clientId": 5,
              "link": "https://www.site.com/store/product/comfort-wrinkle-resistant-stripe-sheet-sheet/543534",
              "price": "39.99",
              "product_type": "Sheet Sets",
              "name": "Wrinkle Resistant Stripe Sheet Sheet",
              "available": "true"
          },
          ...
      ]