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 the SiteSpect 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 the SiteSpect 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:

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