Filters in Modules In various Froomle modules, including Editor’s Picks and Topical Recommendations, filters play a crucial role in refining and personalizing content recommendations. This section provides an overview of how to implement and utilize filters effectively. Why Filters? Filters allow you to limit the recommendations to a specific subset of articles. Examples In a module of the type Editor’s Pick, the articles recommended are limited to those picked by editors. In a module of the type Topical Recommendans, the articles recommended are limited to those that belong to a set of selected topics. A typical example is to only recommend sports articles on a sports page. In a module of the type Similar Articles, you sometimes want to limit the recommended articles to the category of the active article page. Defining Filters A filter consists of three components: a key, a value, and a match_type In an example of a Topical Recommendations Module on the topic sports, the key could be categories, the value would be sports and the match_type would be contains Allowed keys Of the fields that you use to describe your articles when syncing your article catalogue with Froomle, the following can be used as key for filtering: all fields for which the value is of the type scalar` (typically int, float or string), all fields for which the value is of the type array of the same scalar, all fields in item_attributes for which the value is of the type scalar, all fields in item_attributes for which the value is of the type array of the same scalar. Typically, the fields categories or tags are used. Allowed values Both static and dynamic values are allowed: static: You specify the value at module creation time and they do not change. The Editor’s Pick module is a good example of such case. dynamic: The recommendation request contains the value. This is for example applied when a module of the type Similar Articles can only recommend articles from the same category as the article that is active on the article page. Furthermore, values can be: negated with not combined with and or or Avoiding the Abuse of Dynamic Filters Dynamic filter values are designed for use cases where a single module can be impressed in many different contexts. For example: On article pages, the context is the main article on the page, and there are many different articles. When you want to pass information about categories explicitly selected by the user. When used in other types of use cases, the use of dynamic filter values can be inappropriate and the available alternatives should be used instead. Inappropriate use of dynamic filter values leads to higher latencies and makes it more difficult to detect unintended behavior. The available alternatives are: When filter values don’t change (a lot), use static values. When you want the flexibility to change your filter values over time, use a dedicated label: Create a dedicated label like include_in_froomle_module_x or exclude_from_froomle_module_y (this label is typically a category or a tag), Attach the label to all relevant articles. You can do this manually at article creation time, or automatically, based on some basic tagging rules you implement on your side. For example: if article.category in ('sport','celebrity'): article.add_tag('exclude_from_froomle_module_y') On the Froomle side, define a static filter on the dedicated label. Update the tagging rules for adding the label whenever you want, without the need to involve Froomle. Allowed match_types The following match_types are allowed: match: equal to contains: substring starts_with: string prefix check gt: greater than gte: greater than or equal to lt: less than lte: less than or equal to range: numeric value within range [min, max] Limit (optional) Optionally, the filter does not need to apply to the full module, but you can instead specify a limit that specifies the minimum or maximum amount of recommendations to which the filter must/can apply. Combining Filters AND Multiple filters can be combined, with the understanding that every filter further limits the set of allowed recommendations because they are combined as filter-1 AND filter-2 AND …. OR Although it is less straight forward, it is also possible to combine filters with an OR operator. This is achieved by engineering the structure of your metadata, and it is best explained through an example. If you want recommendations to belong to the category MLS OR have the tag Messi attached to them, you can: When synchronizing item metadata, add the new field "item_attributes" : { "categories_and_tags" : ["tag-x", "cat-y"] } Define a filter with key = categories_and_tags value = or : ["MLS", "Messi"] Violating Filters You can choose to which extent a filter can be violated: never violated: If there are not sufficient articles that satisfy the filter, the amount of recommendations returned is lower than the amount of recommendations requested. violate only to return sufficient recommendations: If there are not sufficient articles that satisfy the filter, also articles that do not satisfy the filter are returned. Every article that does satisfy the filter is ranked higher than every article that does not satisfy the filter. preference: Articles that satisfy the filter are preferred and therefore boosted. Articles that do not satisfy the filter can be ranked higher than articles that do satisfy the filter. Applicability of filters It does not matter whether you use our Recommendations API (for websites and apps) or Batch Recommendation Service (for emails or push notifications). Filters can be applied on both. Implementing Filters Implementing filters requires you to take the following steps: Communicate the desired key, value, match_type to your account manager Ensure that the article catalogue you sync with Froomle contains the key as a field. Align with your account manager on the list_name of the module on which to apply the filter. If it concerns a new module, your Account Manager will create the proper list_name and communicate it to you. If it concerns changes to an existing module, you need to inform your Account Manager about the list_name. This allows Froomle to correctly process any incoming recommendations request for this list_name, ensuring accurate filtering of recommendations. This means that the configuration of the module happens mostly in the back-end, and that this information does not need to be appended to every request for recommendations. Default filters To generate recommendations, Froomle combines custom filters with it’s default filters. Unless otherwise specified, Froomle will recommend items that are: Up to 72 hours old for websites, apps, and daily emails; and Up to 7 days old for weekly emails. Not yet read by the reader. Best Practices for Using Filters Use filters judiciously to avoid overly narrowing the recommendation pool and leaving no good recommendation options to the Froomle AI.