Recommendation Models

Fanplayr supports several types of product recommendation models, each suited to different pages and use cases. This page documents the available models, the user events that power them, and how to configure them.

There are three categories of model:

• AI models — Personalised predictions based on individual shopper behaviour and catalog data.
• Activity models — Real-time counts of product interactions such as views, cart adds, and purchases. These return data rather than recommendations, and are useful for surfacing social proof signals.
• Ranking models — Lists of top-ranked products across all shoppers based on aggregate metrics like views, purchases, or revenue.

AI model events

AI models require specific user event details to provide context for recommendation queries. These events are generated automatically by Fanplayr based on the pageType configured in your integration. Only the following page types produce AI model events:

• Home Page
• Product Page
• Category Page
• Search Page
• Shopping Cart Page
• Order Confirmation Page (tracked via the Order Confirmation snippet)

Home Page View

This event occurs when the user views the homepage.

Requirements

• pageType must be "home".

Product Page View

This event occurs when the user views a product detail page.

Requirements

• pageType must be "prod".
• productId must be set to a valid product in the catalog.

Category Page View

This event occurs when the user views a page containing multiple product listings, such as a category list or collection page.

Requirements

• pageType must be "cat".
• categoryId and/or categoryName must be set.

Shopping Cart Page View

This event occurs when the user views the shopping cart.

Requirements

• pageType must be "cart".

Search Page View

This event occurs when the user views a product search results page.

Requirements

• pageType must be "srch".
• At least one of the following must be met:
  • The page includes category details via categoryId and/or categoryName.
  • The page includes search query text via the searchQuery property.

Add To Cart

This event occurs when Fanplayr detects a new product being added to the cart or an increase in product quantity. The event fires on the next page view after the cart has changed, not at the moment of the cart update itself.

WARNING

The Add To Cart event is only generated after a cart change has been detected, which requires a new page view to occur after the cart has been updated. If a page view does not follow the cart update, this event will not fire.

Requirements

• The user must have added a new product to their cart or increased the quantity of an existing product.

Purchase Complete

This event occurs when the user completes the checkout process, typically on the order confirmation page.

Requirements

• An order must be tracked via Fanplayr's order tracking snippet.
• The tracked order must include an order identifier, revenue details, and at least one product.
• The "Track page view after order" campaign option must be enabled to allow segmentation and widgets to re-evaluate after an order is placed.

AI models

The following models use AI to generate personalised product recommendations based on individual shopper behaviour. They require AI model events to be firing correctly from your integration.

Recently Viewed

Returns up to 20 products recently viewed by the user in the last 30 days, with the most recently viewed items listed first.

INFO

This model returns a personalised list of previously viewed products rather than a prediction. It is useful for helping shoppers quickly return to products they have already shown interest in.

Supported pages

• All pages.

Data requirements

• The user must have viewed at least one product in the last 30 days.

Options

Option	Description
Minimum Products	The minimum number of products required for the widget to display. The widget will not show if the model returns fewer products than this value.
Maximum Products	The maximum number of products to return.

Recommended For You

Predicts the next product a user is most likely to engage with or purchase, based on their individual shopping and viewing history. Best suited to the home page or other pages where the shopper's intent is not yet known.

Supported pages

• All pages that generate an AI model event.

Similar Items

Predicts products that are similar to the product currently being viewed. Useful for keeping shoppers engaged on product detail pages by surfacing relevant alternatives.

Supported pages

• Any product page where a productId is tracked.

Frequently Bought Together

Predicts products that are frequently purchased together with the current product in the same shopping session. This model is useful when a shopper has already indicated intent to purchase a specific product and you want to recommend complementary products rather than alternatives.

Commonly used on add-to-cart pages, shopping cart pages, and order confirmation pages.

Supported pages

• Product page — see Product Page View.
• Add-to-cart page — see Add To Cart.
• Shopping cart page — see Shopping Cart Page View.
• Order confirmation page — see Purchase Complete.

Activity models

Activity models return real-time counts of product interactions rather than recommendations. They are useful for displaying social proof signals such as "30 people viewed this today."

Product Activity (Views)

Returns the number of times the current product has been recently viewed by shoppers on the site.

Supported pages

• Product pages.

Options

Option	Description
Recency Time (minutes)	The time window to query in minutes. For example, 60 returns views from the last hour. Valid values are between 5 and 1,440 (1 day).
Minimum Activity Threshold	The minimum number of recent views required to show the widget. Set to 0 to always show.
Maximum Activity Threshold	The maximum number of recent views allowed for the widget to show. If the count exceeds this value, the widget will not display. Leave blank for no maximum.

Product Activity (Carts)

Returns the number of times the current product has been recently added to the shopping cart by shoppers on the site.

Supported pages

• Product pages.

Options

Option	Description
Recency Time (minutes)	The time window to query in minutes. For example, 60 returns cart adds from the last hour. Valid values are between 5 and 1,440 (1 day).
Minimum Activity Threshold	The minimum number of recent cart adds required to show the widget. Set to 0 to always show.
Maximum Activity Threshold	The maximum number of recent cart adds allowed for the widget to show. If the count exceeds this value, the widget will not display. Leave blank for no maximum.

Product Activity (Purchases)

Returns the number of times the current product has been recently purchased by shoppers on the site.

Supported pages

• Product pages.

Options

Option	Description
Recency Time (minutes)	The time window to query in minutes. For example, 60 returns purchases from the last hour. Valid values are between 5 and 1,440 (1 day).
Minimum Activity Threshold	The minimum number of recent purchases required to show the widget. Set to 0 to always show.
Maximum Activity Threshold	The maximum number of recent purchases allowed for the widget to show. If the count exceeds this value, the widget will not display. Leave blank for no maximum.

Ranking models

Ranking models return a list of top-ranked products based on aggregate activity across all shoppers, using up to 30 days of event history. Unlike AI models, ranking models are not personalised — they reflect what is popular across your entire store.

There are four ranking models:

Model	Description
Ranked by Views	Returns the top products by number of times viewed.
Ranked by Carts	Returns the top products by number of times added to cart.
Ranked by Purchases	Returns the top products by number of times purchased.
Ranked by Revenue	Returns the top products by total revenue generated.

Filters

The following optional filters can be applied to any ranking model to narrow the results:

Filter	Description
Number of days	The number of days of history to use, starting from today. Valid values are 1–30, where 1 covers the past 24 hours, 2 the past 48 hours, and so on.
Start price	Limits results to products priced greater than or equal to this value.
End price	Limits results to products priced less than or equal to this value.
Category	Limits results to products in the specified category. Can be configured to use the current page's category automatically.