🚧
In order to allow personalization to function, IntelliSuggest Tracking must be setup prior to implementing Personalized Recommendations or Personalized Search & Merchandising.
This feature does require a plan upgrade, please reach out to your Searchspring Point of Contact for more information.

Personalized Recommendations API

This endpoint is used to source personalized products through different configured profiles to show to the shopper. The products returned from this endpoint will be rendered within a carousel that the shopper can cycle through to view all of the products returned or they can be rendered within a static section to view products.

Documentation:

Personalized Recommendations API

Personalized Recommendations Beacon Tracking

Beacon tracking for Personalized Recommendations is only required to be installed if the account is signed up for Personalized Recommendations. Beacon events should be sent to the Searchspring Beacon API for all required recommendations event types. Each event is going to tell our system when and how a customer interacted with the rendered recommended products sourced from the Personalized Recommendations API endpoint.

In order for our system to understand a profile event is associated with a product event there are three criteria that must be consistent.

All events that have an association in any form have to be batched (sent together) within the same API call to the Beacon API
All contextual data for each event within the context and event.context objects must be identical
The profile events id must be passed as the associated product events pid value

This data is required for our personalization engine to personalize recommended products returned in the Personalized Recommendations API endpoint for shoppers as well as track how shoppers interact with the rendered recommended products. This will play a key role in populating the majority of the data seen in the Product Recommendations report. Note IntelliSuggest Tracking will also need to be integrated to allow this report to gather all necessary data and be accurate.

Documentation:

The example scenarios below will cover from end to end how a shopper would interact with rendered personalized recommendations sections where data is requested and returned from our Personalied Recommendations API endpoint. This will not cover every possible scenario, but this is a good base line to understand how a shopper can interact with the rendered recommendations and what data needs to be sent when the interaction occurs.

Note where YOUR_SITE_ID is referenced, this will be the siteId of the Searchspring account where data is being sent to.

Render

When a request is made to the Personalized Recommendations API endpoint, data is returned and is used to build a recommendations section on the page, our system needs to know what recommendations profile had data requested from and what results were returned from the profile in the API response. This data will be sent as a batch of render events to our system.

As an example, let's say we request data from the profile with a tag of home-recs and a placement of home-page and three results are returned, a short sleeved shirt, a long sleeved shirt, and a tank top. Our system would need to know this information. Below is an example of what the data passed for this render event would look like.

Note product data placed for each of the profile.product.render events in the event.product object is the id string and mappings.core object returned for a result from the Personalized Recommendations API endpoint.

[
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "profile" : {
        "tag" : "home-recs",
        "placement" : "home-page",
        "seed" : [""]
      }
    },
    "id" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.render"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "123456789",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/123456789/image",
            "msrp" : 24.99,
            "name" : "Short Sleeve Shirt",
            "price" : 14.99,
            "sku" : "S_SLV_SHRT_XS",
            "thumbnailImageUrl" : "https://example.com/images/123456789/thumbnailImage",
            "uid" : "123456789",
            "url" : "https://example.com/products/123456789"
          }
        }
      }
    }, 
    "id" : "a97d55c5-77d2-4b0f-939d-5d4b0de15f63",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.render"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "987654321",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/987654321/image",
            "msrp" : 29.99,
            "name" : "Long Sleeve shirt",
            "price" : 19.99,
            "sku" : "LNG_SLV_SHRT_XS",
            "thumbnailImageUrl" : "https://example.com/images/987654321/thumbnailImage",
            "uid" : "987654321",
            "url" : "https://example.com/products/987654321"
          }
        }
      }
    }, 
    "id" : "20902d3f-3aa0-436e-8920-af4f1fcd7ee1 ",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.render"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "543216789",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/543216789/image",
            "msrp" : 19.99,
            "name" : "Tank Top",
            "price" : 13.99,
            "sku" : "TNK_TOP_XS",
            "thumbnailImageUrl" : "https://example.com/images/543216789/thumbnailImage",
            "uid" : "543216789",
            "url" : "https://example.com/products/543216789"
          }
        }
      }
    }, 
    "id" : "20902d3f-3aa0-436e-8920-af4f1fcd7ee1 ",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.render"
  }
]

Impression

When the rendered recommendations section on the page is scrolled into view by the shopper, our system needs to know what recommendations profile and what results are in view of the shopper. This data will be sent as a batch of impression events to our system. Typically the JavaScript (JS) scroll event listener is used to register when the section has been scrolled into view.

Using the previous example profile and results data, let's say the recommendations section is rendered as a carousel where only the first two rendered results are in view to the shopper, the short sleeved shirt and the long sleeved shirt. Our system would need to know this information. Below is an example of what the data passed for this impression event would look like.

Note that because only two of the rendered results are in view to the shopper the profile.impression event and two profile.product.impression events are sent in the batch.

[
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "profile" : {
        "tag" : "home-recs",
        "placement" : "home-page",
        "seed" : [""]
      }
    },
    "id" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.impression"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "123456789",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/123456789/image",
            "msrp" : 24.99,
            "name" : "Short Sleeve Shirt",
            "price" : 14.99,
            "sku" : "S_SLV_SHRT_XS",
            "thumbnailImageUrl" : "https://example.com/images/123456789/thumbnailImage",
            "uid" : "123456789",
            "url" : "https://example.com/products/123456789"
          }
        }
      }
    }, 
    "id" : "a97d55c5-77d2-4b0f-939d-5d4b0de15f63",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.impression"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "987654321",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/987654321/image",
            "msrp" : 29.99,
            "name" : "Long Sleeve shirt",
            "price" : 19.99,
            "sku" : "LNG_SLV_SHRT_XS",
            "thumbnailImageUrl" : "https://example.com/images/987654321/thumbnailImage",
            "uid" : "987654321",
            "url" : "https://example.com/products/987654321"
          }
        }
      }
    }, 
    "id" : "20902d3f-3aa0-436e-8920-af4f1fcd7ee1 ",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.impression"
  }
]

Click/Impression

When the rendered recommendations section on the page has already been scrolled into view by the shopper and the shopper clicks on the rendered recommendations carousel to bring more recommended products into view, our system needs to know what recommendations profile was interacted with and what new results are brought into the view of the shopper. This data will be sent as a batch of click and impression events to our system.

Using the previous example profile and results, let's say the shopper clicks a right arrow button that handles bringing the third and final tank top result into their view and displays the long sleeve shirt followed by the new tank top result. Our system would need to know this information. Below is an example of what the data passed would look like.

Note that because the shopper clicked the rendered profile a profile.click event is sent. Also note only a single profile.product.impression event is sent in the batch, this is because our system should only receive data for a result that has not already received a profile.product.impression event. In this case we have already sent a profile.product.impression event for the long sleeve shirt in the previous example, so we only send an event for the result that has been brought into view to the shopper where we have not sent an impression event, the tank top result.

If your team has implemented an auto scroll feature for a recommendations carousel, when it autoscrolls a profile.impression event would be sent instead of the profile.click event followed by events for the new products that have been brought into view of the shopper.

[
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "profile" : {
        "tag" : "home-recs",
        "placement" : "home-page",
        "seed" : [""]
      }
    },
    "id" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.click"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "543216789",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/543216789/image",
            "msrp" : 19.99,
            "name" : "Tank Top",
            "price" : 13.99,
            "sku" : "TNK_TOP_XS",
            "thumbnailImageUrl" : "https://example.com/images/543216789/thumbnailImage",
            "uid" : "543216789",
            "url" : "https://example.com/products/543216789"
          }
        }
      }
    }, 
    "id" : "20902d3f-3aa0-436e-8920-af4f1fcd7ee1 ",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.impression"
  }
]

Click

When the shopper clicks on a rendered result and is navigated to the product page for the clicked result, our system needs to know what recommendations profile and what result the shopper clicked. This data will be sent as a batch of click events to our system.

Using the previous example profile and results, let's say the shopper clicks the tank top and will be navigated to the tank top product page. Our system would need to know this information. Below is an example of what the data passed for this click event would look like.

[
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "profile" : {
        "tag" : "home-recs",
        "placement" : "home-page",
        "seed" : [""]
      }
    },
    "id" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.click"
  },
  {
    "category" : "searchspring.recommendations.user-interactions",
    "context" : {
      "pageLoadId" : "e560933a-b0fe-408d-8df5-807270e79fb8",
      "userId" : "e2cfa1b3-96bc-4857-b9ad-22f07af52403",
      "sessionId" : "5b5baff8-0f18-4b56-8f4b-9a6ce13435a2",
      "website" : {
        "trackingCode" : "YOUR_SITE_ID"
      }
    },
    "event": {
      "context" : {
        "type" : "product-recommendation",
        "tag" : "home-recs",
        "placement" : "home-page"
      },
      "product" : {
        "id" : "543216789",
        "mappings" : {
          "core" : {
            "imageUrl" : "https://example.com/images/543216789/image",
            "msrp" : 19.99,
            "name" : "Tank Top",
            "price" : 13.99,
            "sku" : "TNK_TOP_XS",
            "thumbnailImageUrl" : "https://example.com/images/543216789/thumbnailImage",
            "uid" : "543216789",
            "url" : "https://example.com/products/543216789"
          }
        }
      }
    }, 
    "id" : "20902d3f-3aa0-436e-8920-af4f1fcd7ee1 ",
    "pid" : "f77ce2b0-814f-44af-9caa-89fd75400991",
    "type" : "profile.product.click"
  }
]