Recombee Docs
Visit recombee.comStart Free
docs20User Documentation
adminuiAdmin UI
reql32ReQL
codeAPI Clients & Integrations
cookhatScenario Recipes
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]
    • is subscription needed [boolean] - 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

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.
Main News Box / Feed On Homepage
Other Boxes On Homepage

You may opt for various homepage Recommend Items To User Scenarios, such as:

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

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