Content Recommendations - Getting Started

Content recommendations with our implementation model requires a few simple tasks

Table of Content

Questionnaire

Content Identifiers and Categories for Recommendations

Setting up a basic Data Layer

Setting up your Content Feed

API Only Integration

Getting Started

Changing or implementing content 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 content pages? For example, when coming from email/ad campaigns, or from search, mobile vs desktop.

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

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

• How do we place orders/sign ups 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 quick view functionality?

Content Identifiers and Categories for Recommendations

Content identifiers and categories are leveraged in the content feed and data layer. 

Content ID

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

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

• 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 / Sign up page

• Content detail pages

• Quick View (if available)

• Shopping Cart

• Category pages

• Search Results

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

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

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

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

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

<!-- Order Confirmation / Sign Up Page -->
<script type="text/javascript">
var ssRecsInfo =
{
   'page': {
       'type': 'confirmation',
       'orderTotal': 246.53,
       'contents': [
       {
           'contentId': '889987',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots']
           },
           {
           'contentId': '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':{
     'contents': [
       {
           'contentId': '889987',
           'category': ['sporting goods', 'winter sports', 'snowboarding', 'snowboard boots']
           },
           {
           'contentId': '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 Content 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 content 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

• UTF-8 encoded without BOM

• Delimiter: tab (recommended) or custom

Required Fields

The recommendation engine requires the following fields:

• Unique Content Identifier
  • Name this field anything you like.
  • This field needs to match content identifiers displayed on the website, including content and order confirmation/sign up 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 "true" or "false".
• Display Properties (up for discussion):
  • Name (e.g. article, report etc)
  • Image URL
  • Content URL
  • Ratings/reviews
  • Price/Sales Price
  • ...
• Filter Properties (up for discussion)
  • Categories
  • Region
  • Currency
  • Language
  • Publish Date
  • ...

API Only Integration

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

1. Sync your content 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 contents 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,
        "clientId": 5,
        "link": "https://www.site.com/store/content/microfiber-sheet-set/4324321",
        "price": "59.99",
        "content_type": "Sheet Sets",
        "name": "400-Thread-Count Solid Sateen Sheet Set",
        "available": "true"
    },
    {
        "id": 176725,
        
        "clientId": 5,
        "link": "https://www.site.com/store/content/comfort-wrinkle-resistant-stripe-sheet-sheet/543534",
        "price": "39.99",
        "content_type": "Sheet Sets",
        "name": "Wrinkle Resistant Stripe Sheet Sheet",
        "available": "true"
    },
    ...
]