Recombee Docs
Visit recombee.comStart Free
docs20User Documentation
adminuiAdmin UI
reql32ReQL
codeAPI Clients & Integrations
suitcaseMisc

Integration Tips

Thanks to the versatility of our solution and hundreds of algorithms in our stack Recombee can be utilized in a wide variety of areas. You can use Recombee for recommending almost any type of content or product: videos, articles, fashion, real-estate, podcasts, jobs ... you name it :)

Every domain has its specifics and the following sections present some of the best practices for the correct use of our recommendation service.


Choose your domain


Content Recommendations#

Videos#

Items Catalog#

  • Each video (movie, series, asset) should be an item in Recombee
  • Typical item properties are for example:
    • title [string]
    • categories/genres [set]
    • description [string]
    • languages [set]
    • image [image] - for example a poster
    • cast [set]
    • tags [set]
    • year [int]
    • availability [boolean]
    • minimal age of viewer [int]
    • available since [timestamp]
    • date of expiration [timestamp]
    • needed subscription - for determining if the item is available for a particular user
    • type [string] - determines if the item is a movie, series, episode, etc.

Interactions#

  • Send a detail view whenever a user clicks a video thumbnail
  • Set a few important milestones in the video (e.g. 15%, 50 %, 75%) and send a view portion whenever the user watches the video until a milestone
  • It is very common to send a purchase when you consider the movie to be consumed by the user (e.g. the user watched it until 90 %)
  • If users can bookmark or rate the items, send bookmarks and ratings
  • Likes should be modeled as positive ratings (e.g. with rating 1.0)

Don't forget to provide the recommId parameter if the interaction is based on the recommendations. It will give you very precise insight into the success of the recommendations in the Admin UI.

Setting Up Recommendations#

  • Create a scenario for each place you want to show the recommendations.
  • Set filters for each of them: At least a filter for recommending only available items should be set. You can pick predefined rule Available items from the Recombee Business Rules Library to achieve this.
  • You may also want to add a filter to recommend only items of a particular type.

Typical Scenarios#

Homepage#
  • Use Recommend Items To User endpoint in that case
  • You may want to have multiple homepage scenarios (multiple boxes), each with different filters/boosters. For example:
    • Recommend videos recently added to the catalog (use Recent items filter/booster from the library)
    • Recommend videos that are about to expire
    • Recommend videos from a particular genre
    • Show globally popular videos (use recombee:popular logic)
Watch Next#
Similar Videos#
Top genres for the user#

Each user likes to watch different genres and Recombee can give you these genres for each user based on the user's watching history.

Requesting this scenario will give you the top genres for a particular user.

A frequent use case is to fully personalize the homepage, including the order of the rows with top genres on the top.

  • First, get the top genres for a user using Recommend Item Segments To User endpoint, and then for each of these genres create a row.

  • Fill these rows by sending Recommend Items To User requests for each of these genres. This is done by setting the filter parameter of the request to:

    ReQL
    'genre' == "<particular genre>"
    

These calls can be sent within a single Batch request. Setting the distinctRecomms parameter of the Batch request to true will recommend each video at most once among all the rows, even if the video belongs to multiple genres.

Videos in a category#
  • To show videos from a category, such that the user should like these videos the most, use Recommend Items To User endpoint with the video:personal Logic

  • If there is just a few categories, you can create a scenario for each of them and add Items from particular category filter rule from the Recombee Business Rules Library

  • Otherwise, allow only items from a particular category by setting the filter parameter of the Recommend Items To User API call. For example, to show only videos from the category of documentary movies, the filter may look like:

    ReQL
    "Documentary" in 'categories'
    
  • If the user scrolls the page down, you can get subsequent results by calling Recommend next items.

  • Use the Search endpoint with the video:search Logic and let your users search the videos in a personalized way

News and Articles#

Items Catalog#

  • Each article should be an item in Recombee
  • Typical item properties are for example:
    • title [string]
    • categories [set]
    • tags [set]
    • published [boolean]
    • url [string]
    • lead paragraph [string]
    • image [image]
    • expire date [timestamp]
    • is paid content [boolean]
    • author [string]

Interactions#

  • Send a detail view whenever a user opens an article.
  • If users can rate the items, send ratings. Likes should be modeled as positive ratings (e.g. with rating 1.0).
  • Don't forget to provide the recommId parameter if the interaction is based on the recommendations. It will give you very precise insight into the success of the recommendations in the Admin UI.
  • Optional enhancement: Set a few important milestones in the article (e.g. 30%, 50 %, 75%) and send a view portion whenever the user reads (scrolls) up to the portion

Typical Scenarios#

  • Create a scenario for each place you want to show the recommendations.
Homepage#
  • Use Recommend Items To User endpoint in that case
  • You may want to boost recent articles or even allow only the recent ones. Use Recent items filter/booster from the library.
Search#
  • Use the Search endpoint and let your users search the articles in a personalized way
Top categories for the user#

You can present the categories of the articles in the way, that the categories which are read most often by the particular user appear on the top.

Requesting this scenario will give you the top categories for a particular user.

Music and Podcasts#

Items Catalog#

  • Each song should be an item in Recombee
  • Typical item properties are for example:
    • title [string]
    • artist [string]
    • genre [string]
    • featured artists [set]
    • labels [set]
    • album title [string]
    • album cover [image]
    • country [string]
    • release date [timestamp]
    • is explicit [boolean]
    • duration [int]

Interactions#

  • Set a few important milestones in the song (e.g. 15%, 50 %, 75%, 100%) and send a view portion whenever the user listens to the song until a milestone
  • Send us ratings with the rating set to 1.0 for liked songs
  • Send us ratings with the rating set to -1.0 for disliked songs

Setting Up Recommendations#

  • Create a scenario for each place you want to show the recommendations.

  • Set filters to the scenarios: At least a filter for recommending only available items should be set.

    If the availability is based on the release date, the filter can look like this:

    ReQL
    'release_date' < now()
    

    In many cases, you also need to show only appropriate content to minors. If you set a user property is_minor to true for the minors, then the filter can look like this:

    ReQL
    if context_user["is_minor"] then
    	not 'is_explicit'
    else
    	true
    

Such filter rules can be added to the Global Settings, so they are applied to all your scenarios.

Typical Scenarios#

  • Create a scenario for each place you want to show the recommendations.
Songs / Podcasts for You#

To obtain a personalized list of the top songs or podcasts for a user call the Recommend Items To User endpoint with the recombee:personal Logic.

New Releases#

To obtain a personalized list of the recently added songs or podcasts that shall be interesting for the user, call the Recommend Items To User endpoint with the recombee:personal Logic and add the Recent items predefined Filter rule.

To obtain songs or podcasts that are currently globally popular, use Recommend Items To User endpoint with the recombee:popular Logic.

  • You can choose what time period will be taken into consideration when evaluating the most popular songs using the timePeriod parameter of the Logic (value is in seconds)

  • The currently popular content can often vary in different countries. If you upload the user's country as the user property, you can get the content popular among users from the same country by setting userSegmentFilter parameter of the Logic to:

    ReQL
    'country' == context_user["country"]
    

In order to obtain songs that are related to a particular song, call the Recommend Items To User endpoint with the recombee:similar Logic.

You can use these songs e.g. for the autoplay, so it keeps the mood of the song the user is currently listening to.

Top Artists / Podcasters for You#

Based on the listened songs, Recombee can recommend interesting artists for the user.

Requesting this scenario will give you the artists that shall be the most interesting for a particular user.

You can show the related artists on an artist's detail page.

Requesting this scenario with segmentId set to a particular artist will give you the artists related to that artist.

Top Albums for You#

Based on the listened songs, Recombee can recommend albums that shall be interesting for the user.

Request this scenario to get the top albums for the user.

Product Recommendations#

Items Catalog#

  • Each product that you want to recommend should be an item in Recombee.
  • Typical item properties are for example:
    • title [string]
    • image link [image]
    • available [boolean]
    • categories [set]
    • price [double]
    • url [string]
    • brand / vendor [string]
    • on sale [boolean]

Then there are various segment-specific properties, for example in fashion:

  • gender [string]
  • material [string]
  • color [string]
  • available sizes [set]
tip20
Tip

You can set a catalog feed (e.g. Google Merchant Feed) in the Admin UI for products catalog synchronization

Handling Variants#

  • If your products come in multiple variants (sizes, colors), the preferred representation in most cases is to have the master product as an item in Recombee and send interactions to it from pages of all its variants.

  • If you want to ensure compatibility of available product sizes and user's preferred sizes, model both as item/user properties and use filter like this one:

    ReQL
    context_user["sizes"] == null OR size('available_sizes' & context_user["sizes"]) > 0
    
  • In the case of having each variant as an item in Recombee, the recommendations will also work, but it may take longer to train the models properly at lower traffic sites as the number of interactions is divided between all the variants.

Interactions#

  • Send a detail view whenever a user views a detail page of a product
  • Send a cart addition whenever a user adds a product into the cart
  • Send a purchase whenever a user buys a product.
    • There will be an Add Purchase request per each product in the ordered cart. Optionally, these requests can be sent inside a single Batch request.
    • Set the price parameter to see revenue based on recommendations in the Admin UI.
  • If users can bookmark or rate the items, send bookmarks and ratings
  • It is suggested to provide the recommId parameter if the interaction is based on the recommendations.

It will give you very precise insight into the success of the recommendations in the Admin UI.

Setting Up Recommendations#

  • Create a scenario for each place you want to show the recommendations.
  • Set filters for each of them: At least a filter for recommending only available products should be set. You can pick predefined rule Available items from the Recombee Business Rules Library to achieve this.

Typical Scenarios#

Homepage#

  • Use Recommend Items To User endpoint in that case
  • Set ecommerce:homepage Logic to get picked products for the user
  • In case the user is new and has no interactions yet, the recommender will provide bestseller/trending products
  • You may want to add also another box with the best selling items - use ecommerce:bestseller Logic to achieve that

Product Detail#

  • Use Recommend Items To Item endpoint in that case
  • If you want to present the user viable alternatives, use ecommerce:similar-products Logic
  • You may want to apply predefined Upsell rule from the Recombee Business Rules Library to prefer items that are a bit more expensive than the one that is currently viewed by the user. This often leads to higher average order value.
  • If you want to show the user the accessories, use ecommerce:cross-sell Logic

Cart#

Category#

  • Use Recommend Items To User and set its filter parameter to recommend only products from a particular category. For example, if you use Google Merchant Feed for catalog synchronization, you may use the following filter to recommend only mobile phones:

    ReQL
    "Mobile Phones" in 'google_product_category'
    
  • If the user scrolls the page down, you can get subsequent results by calling Recommend next items.

Search#

  • Use the Search endpoint and let your users search the products in a personalized way

Email#

Top brands for the user#

You can get the top brands for the user (according to the user's interaction history, or the globally popular brands in case of a new user) by requesting the Recommend Item Segments To User recommendations.

One tip on how to use the top brands is to add automated rows with products by these brands to the homepage.

  • First, get the top brands for a user using Recommend Item Segments To User endpoint, and then for each of these brands create a row.

  • Fill these rows by sending Recommend Items To User requests for each of the brands. This is done by setting the filter parameter to:

    ReQL
    'brand' == "<particular brand>"
    

These calls can be sent within a single Batch request.

The same approach can be used also for getting the top categories for the user.

Real Estate Recommendations#

Items Catalog#

  • Each property (building, apartment, ...) that you want to recommend should be an item in Recombee.
  • Typical item properties are for example:
    • title [string]
    • image link [image]
    • available [boolean]
    • url [string]
    • state [string]
    • city [string]
    • neighborhood [string]
    • zip code [string]
    • latitude [double]
    • longitude [double]
    • price [double]
    • description [string]
    • square feet [int]
    • number of bedrooms [int]
    • number of bathrooms [int]
    • parking spaces [int]
    • pets allowed [boolean]
    • year built [int]
    • type [string] - apartment / family house / condo / ...
    • amenities [set] - e.g. air condition, balcony, fire place, swimming pool ...

Interactions#

  • Send a detail view whenever a user views a detail page of a property
  • Send a bookmark whenever a user bookmarks a property
  • Send a purchase when a user expresses a strong interest in the particular property - e.g. makes an offer or books a tour.
  • Don't forget to provide the recommId parameter if the interaction is based on the recommendations. It will give you very precise insight into the success of the recommendations in the Admin UI.

Setting Up Recommendations#

  • Create a scenario for each place you want to show the recommendations.
  • Set filters for each of them: At least a filter for recommending only available properties should be set. You can pick predefined rule Available items from the Recombee Business Rules Library to achieve this.

Typical Scenarios#

Properties in user-specified area#

  • After a user inserts the area where the user is looking for a property the best deals for the user in the area will be delivered by Recombee

  • Use Recommend Items To User endpoint with recombee:homepage Logic in that case

  • The area inserted by the user should be sent in the filter parameter of the Recommend Items To User request in order to allow only properties from the particular area. It can look like:

    ReQL
    'state'=="TX" and 'city'=="Austin"
    
  • Alternatively, you can store the user's area to Recombee as user properties, and use filter like:

    ReQL
    'state'==context_user["state"] and 'city'==context_user["city"]
    

Properties in a geolocation#

  • If the user browses a map, you can show (or highlight) the most fitting properties for the user (according to the user's past interactions).

  • Use Recommend Items To User endpoint with recombee:personal Logic

  • Set the request's filter parameter to allow only properties in the map radius. You can use earth_distance ReQL function to achive this.

    ReQL
    earth_distance('latitude', 'longitude', <centre of the map latitude>, < centre of the map longitude> ) < <map radius in metres>
    

Similar properties#

Homepage for registered users#

  • Use Recommend Items To User endpoint with recombee:homepage Logic
  • If the user has already interactions, properties in the user's location should be picked by Recombee. You can (especially for new users) ensure it by filters or boosters.

Email#

  • Use Recommend Items To User endpoint with recombee:emailing Logic

  • If the user has already interactions, properties in the user's location should be picked by Recombee. You can ensure it by setting filters or boosters.

  • If the user set some custom conditions, e.g. minimal number of bedrooms or maximal price, you can also express these as a filter:

    ReQL
    'num_bedrooms' >= 2 and 'price' < 10000
    

Search#

  • Use the Search endpoint and let your users search the properties in a personalized way
  • You can also apply filters or boosters - e.g. search only within an area using earth_distance ReQL function.

Paginated Recommendations#

If you want to get subsequent recommendations for the next page of results, call Recommend next items endpoint.

© Copyright 2024, Recombee s.r.o
docs.recombee.com