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.
- title [
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
]
- title [
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
- Use the Recommend Items To User endpoint in this case
- Set the news:daily-news Logic
Other Boxes On Homepage
You may opt for various homepage Recommend Items To User Scenarios, such as:
- A highly personalized box using news:personal Logic
- A trending news box using news:trending Logic
- A latest news box using news:recent Logic
Read Next
- Use the Recommend Items To Item endpoint to get the relevant articles.
- Set the news:read-next Logic
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.
- First, create an Item Segmentation on the item property that contains the category of the articles
- Then go to the Scenarios section and create a scenario of the Recommend Item Segments To User type based on the created categories Segmentation
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
]
- title [
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:ReQLif 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.
Trending Songs / Podcasts
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"]
Related Songs or Podcasts
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.
- First, create an Item Segmentation on the item property that contains the primary artist
- Then go to the Scenarios section and create a scenario of the Recommend Item Segments To User type based on the created artists Segmentation
Requesting this scenario will give you the artists that shall be the most interesting for a particular user.
Related Artists / Podcasters
You can show the related artists on an artist's detail page.
- If you don't have an Item Segmentation based on the primary artist yet, create one
- Then go to the Scenarios section and create a scenario of the Item Segments To Item Segment with both Context and Result Segmentations set to the artists Segmentation
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.
- First, create an Item Segmentation on the item property that contains the album title or ID
- Then go to the Scenarios section and create a scenario of the Recommend Item Segments To User type based on the created albums Segmentation
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
]
- title [
Then there are various segment-specific properties, for example in fashion:
- gender [
string
]- material [
string
]- color [
string
]- available sizes [
set
]
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:
ReQLcontext_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 ...
- title [
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.ReQLearth_distance('latitude', 'longitude', <centre of the map latitude>, < centre of the map longitude> ) < <map radius in metres>
Similar properties
- Use Recommend Items To Item with recombee:similar 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.
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
orboosters
.
-
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
orboosters
. -
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
orboosters
- 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.