.. role:: reql(code)
:language: python
.. _integration_tips:
Integration Tips
################
.. rst-class:: lead
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 :)
.. figure:: _static/headings/integration-tips.png
:class: no-shadow rounded
:align: center
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**
.. raw:: html
------------
.. _integration_tips_content:
Content Recommendations
=======================
.. raw:: html
.. _integration_tips_content_videos:
Videos
------
.. figure:: _static/integration_tips/videos.png
:align: right
Items Catalog
^^^^^^^^^^^^^
- Each video (movie, series, asset) should be an *item* in Recombee
- Typical :ref:`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.
- Optional: If the users can interact (like, rate, etc.) not only with the videos but for example also with directors, actors, etc., then these can be items too. They can have different properties (e.g. nationality) than the videos, and these properties will be left unfilled for items that represent videos: the recommender system is ok with that.
Interactions
^^^^^^^^^^^^
- Send a :ref:`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 :ref:`view portion` whenever the user watches the video until a milestone
- It is very common to send a :ref:`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 :ref:`bookmarks` and :ref:`ratings`
- Likes should be modeled as positive :ref:`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 :ref:`give you very precise insight` into the success of the recommendations in the Admin UI.
Setting Up Recommendations
^^^^^^^^^^^^^^^^^^^^^^^^^^
- Create a :ref:`scenario ` for each place you want to show the recommendations.
- Set :ref:`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 :ref:`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 :ref:`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 :ref:`library `)
- Recommend videos that are about to expire
- Recommend videos from a particular genre
- Show globally popular videos (use recombee:popular logic)
Watch Next
""""""""""
- Use :ref:`Recommend Items To Item ` endpoint to get the relevant videos
Similar Videos
""""""""""""""
- Use :ref:`Recommend Items To Item ` endpoint
Videos in a category
""""""""""""""""""""
- To show videos from a category, such that the user should like these videos the most, use :ref:`Recommend Items To User ` endpoint
- 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 :ref:`Recombee Business Rules Library `
- Otherwise, allow only items from a particular category by setting the ``filter`` parameter of the :ref:`Recommend Items To User ` API call. For example, to show only videos from the category of documentary movies, the filter may look like:
::
"Documentary" in 'categories'
- If the user scrolls the page down, you can get subsequent results by calling :ref:`Recommend next items `.
Search
""""""
- Use the :ref:`Search ` endpoint and let your users search the videos in a personalized way
.. _integration_tips_content_articles:
News and Articles
-----------------
.. figure:: _static/integration_tips/news_articles.png
:align: right
Items Catalog
^^^^^^^^^^^^^
- Each article should be an *item* in Recombee
- Typical :ref:`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 :ref:`detail view` whenever a user opens an article.
- If users can rate the items, send :ref:`ratings`. Likes should be modeled as positive :ref:`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 :ref:`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 :ref:`view portion` whenever the user reads (scrolls) up to the portion
Typical Scenarios
^^^^^^^^^^^^^^^^^
- Create a :ref:`scenario ` for each place you want to show the recommendations.
Homepage
""""""""
- Use :ref:`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 :ref:`library `.
Read Next
"""""""""
- Use :ref:`Recommend Items To Item ` endpoint to get the relevant articles.
Search
""""""
- Use the :ref:`Search ` endpoint and let your users search the articles in a personalized way
.. _integration_tips_product:
Product Recommendations
=======================
.. figure:: _static/integration_tips/product.png
:align: right
Items Catalog
-------------
- Each product that you want to recommend should be an *item* in Recombee.
- Typical :ref:`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``]
.. tip::
You can set a :ref:`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:
::
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 :ref:`detail view` whenever a user views a detail page of a product
- Send a :ref:`cart addition` whenever a user adds a product into the cart
- Send a :ref:`purchase` whenever a user buys a product.
- There will be an :ref:`Add Purchase request` per each product in the ordered cart. Optionally, these requests can be sent inside a single :ref:`Batch request`.
- Set the ``price`` parameter to see revenue based on recommendations in the :ref:`Admin UI `.
- If users can bookmark or rate the items, send :ref:`bookmarks` and :ref:`ratings`
- It is suggested to provide the `recommId` parameter if the interaction is based on the recommendations.
It will :ref:`give you very precise insight` into the success of the recommendations in the Admin UI.
Setting Up Recommendations
--------------------------
- Create a :ref:`scenario ` for each place you want to show the recommendations.
- Set :ref:`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 :ref:`Recombee Business Rules Library ` to achieve this.
Typical Scenarios
-----------------
Homepage
^^^^^^^^
- Use :ref:`Recommend Items To User ` endpoint in that case
- Set `ecommerce:homepage` :ref:`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` :ref:`Logic` to achieve that
Product Detail
^^^^^^^^^^^^^^
- Use :ref:`Recommend Items To Item ` endpoint in that case
- If you want to present the user viable alternatives, use `ecommerce:similar-products` :ref:`Logic`
- You may want to apply predefined *Upsell* rule from the :ref:`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` :ref:`Logic`
Cart
^^^^
- Use :ref:`Recommend Items To User ` and pick `ecommerce:cross-sell` :ref:`Logic` to show accessories to products in user's cart
Category
^^^^^^^^
- Use :ref:`Recommend Items To User ` and set its ``filter`` parameter to recommend only products from a particular category. For example, if you use :ref:`Google Merchant Feed` for catalog synchronization, you may use the following filter to recommend only mobile phones:
::
"Mobile Phones" in 'google_product_category'
- If the user scrolls the page down, you can get subsequent results by calling :ref:`Recommend next items `.
Search
^^^^^^
- Use the :ref:`Search ` endpoint and let your users search the products in a personalized way
Email
^^^^^
- Use :ref:`Recommend Items To User ` and `recombee:emailing` :ref:`Logic` for personalized offers in an email campaign
.. _integration_tips_real_estate:
Real Estate Recommendations
===========================
.. figure:: _static/integration_tips/real_estate.png
:align: right
Items Catalog
-------------
- Each property (building, apartment, ...) that you want to recommend should be an *item* in Recombee.
- Typical :ref:`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 :ref:`detail view` whenever a user views a detail page of a property
- Send a :ref:`bookmark` whenever a user bookmarks a property
- Send a :ref:`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 :ref:`give you very precise insight` into the success of the recommendations in the Admin UI.
Setting Up Recommendations
--------------------------
- Create a :ref:`scenario ` for each place you want to show the recommendations.
- Set :ref:`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 :ref:`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 :ref:`Recommend Items To User ` endpoint with `recombee:homepage` :ref:`Logic` in that case
- The area inserted by the user should be sent in the ``filter`` parameter of the :ref:`Recommend Items To User request ` in order to allow only properties from the particular area. It can look like:
::
'state'=="TX" and 'city'=="Austin"
- Alternatively, you can store the user's area to Recombee as :ref:`user properties`, and use filter like:
::
'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 :ref:`Recommend Items To User ` endpoint with `recombee:personal` :ref:`Logic`
- Set the request's ``filter`` parameter to allow only properties in the map radius. You can use :ref:`earth_distance ` ReQL function to achive this.
::
earth_distance('latitude', 'longitude', , < centre of the map longitude> ) <