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 Identifiers and Categories for Recommendations

Product identifiers and categories 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

Categories

• Align with major website categories or filtering options. If your website has a detailed breadcrumb that represents category hierarchy consistently, you can align the categories with it.

• If your site offers quick view functionality, make sure category values are the same on PLPs and PDPs.

• Should be exposed as an array of values

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'
   }
};

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

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
  • Name this field anything you like.
  • This field needs to match product identifiers (SKUs or else) displayed on the website, including PDPs and order confirmation page.
• Category
  • Name this field anything you like.
  • Try to align with your website categorization.
  • Hierarchy preferred.
  • List of values supported.
• Availability
  • Expected values are "in stock" or "out of stock".
• Display Properties (up for discussion):
  • Name
  • Image URL
  • Product URL
  • Ratings/reviews
  • Price
  • Sales Price
  • ...
• Filter Properties (up for discussion)
  • Category
  • 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:

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

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"
    },
    ...
]