Example API Integration News Froomle specializes in providing personalized and relevant recommendations for your readers. The following is an overview of the required steps to set up a website integration tailored to your news use case, using direct integration with our API’s. For a complete overview of our integration options, refer to our integration landing page. There are four major steps described on this page: Understand the Froomle basic concepts by reading our platform overview Synchronize item metadata Synchronize tracking events Requesting & show recommendations Items Integration Froomle needs information on your item catalog (articles/videos/blog posts / …), including metadata, for several reasons: to know which items to recommend. to share this metadata back to you in our recommendation response. This could save you some time fetching this information from your own back-end. to allow for filters/constraints on the recommended items, e.g. we can limit the age of articles to recommend to train our algorithms to give your users the best recommendations At the start of the integration process, we expect to receive at least the current catalog. If possible, also older items can be sent to us (e.g. up to a few months old). After this first data upload, we expect to receive updates on new or updated items quickly. For fast-changing content like articles or media, updates should be (near-)real-time in order to provide the most relevant recommendations at all times. It is very important that we receive ALL of your items which are still actively being visited (old items which are no longer viewed, can be left out), items which are missing from our database will negatively impact our recommendation quality. We summarize the most important actions for managing your metadata using the Items API, for more information see API Reference. You can manage your metadata using our API, with the following methods: PUT: to add a new item or update an existing item. DISABLE: to ensure that an item will no longer be recommended. The item will remain in our database and can be still used in our models. DELETE: to delete items from our database. Only use this option if the items are actually deleted from the website. GET: retrieve the metadata from an existing item. Useful to check if all data is persisted like expected in our database. In case you would like to integrate us in another way, please consult the full Integration Handbook. News item metadata template Below you can find an example for posting a new article on our API. For specifications & more details, we refer you to our Item metadata template. Example Specification { "environment": "{environment}", "item_id": "client_item_id_001", "item_type": "article", "title": "Froomle title", "description": "Lorem ipsum ... Article/product full text", "uri": "https://www.froomle.com/client_item_id_001", "categories": [ "/Sports/Football", "/News/National" ], "tags": [ "Red Devils", "Martinez", "Heizel", "Qatar2022" ], "images": [ "https://www.froomle.com/content/client_item_id_001.jpg" ], "publication_datetime": "2021-07-29T13:02:03+02:00", } [{table-format}] Field Description environment* string Required. The environment to which the item belongs. item_id* string Required. Available for filtering. The unique identifier of the item. item_type* string Required. Available for filtering. Items is the collection of all different entities on your platform. Item type allows you to further specify which type of entity this item represents. E.g. article, video, profile, category, … In the recommendation request a filter can be specified to only return items of a certain type. language string Recommended. Available for filtering. The metadata’s main language, if an item’s metadata is delivered in multiple languages specify the most dominant language here. The provided value should be a ISO 639-1 standard language code like en, fr, nl, en-us, nl-be, … In the recommendation request a filter can be specified to only return items of a certain language. title string Recommended. The title of the item. If your item is available in multiple languages use the title_map field instead. Metadata like this allows Froomle to further optimize the recommendations and provide demo functionality in our portal. title_map map<string, string> Optional. A mapping of language_code → title. Use this field when your title has multiple translations. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, … description string Recommended. The description of the item. If your item contains translations use the description_map field instead. Metadata like this allows Froomle to further optimize the recommendations. description_map map<string, string> Optional. A mapping of language_code → description. Use this field when your description has multiple translations. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, … uri string Recommended. The uri of the item. If your item has a resource identifier unique to each language use the uri_map field instead. Recommended to provide demo functionality in our portal. uri_map map<string, string> Recommended. A mapping of language_code → uri. Use this field when your item has resource identifiers unique to each language. Keys in this map should be ISO 639-1 standard language codes like en, fr, nl, en-us, nl-be, … categories list<list<string>> Recommended. Available for filtering. As items often belong to a hierarchical category structure you can specify each path within the structure that can be used to reach the current item. Categories within a path should be listed from most general to most specific. In the recommendation request a filter can be specified to only return items from the given categories. Recommended to provide demo functionality in our portal. tags list<string> Recommended. Available for filtering. Tags are often associated with items to provide extra context. While this field is optional it should be clear that tags carry valuable information for personalization algorithms. In the recommendation request a filter can be specified to only return items that carry a certain tag. Recommended to provide demo functionality in our portal. images list<string> Recommended. If your item contains one or more images you can optionally provide their URLs using this field. Recommended to provide demo functionality in our portal. parent string Optional. When your items are structured in a hierarchy you can supply the parent identifier using this field. ancestry_level string Optional. When your items are structured in a hierarchy you can specify the level of the provided item in the hierarchy. Valid values are (from highest to lowest in the hierarchy): group, item and model. item_attributes map<string, string> Optional. A mapping of any item attributes to values. We can return these attributes in our recommendation response and use them for analysis purposes. publication_datetime* string Required. ISO-8601 formatted timestamp string of the publication datetime of the news item. end_datetime string Optional. ISO-8601 formatted timestamp string of the end of publication datetime of the news item. access_type string Optional. When access to an article is restricted for certain users, use this field to specify the restriction. Valid values are: FREE, METERED and PAID. Events integration Froomle’s algorithms use your users' interactions with your website to make recommendations and to measure our performance. We refer to your users' interactions as Events. Froomle supports a broad collection of event types to capture specific user behavior. To provide the best recommendations possible, it is recommended to record user events for all event types. The following table describes the priority of the different user event types. Priority User Events User Events Must for go-live Module Optimization detail_pageview Module Optimization, Analysis and Reporting click_on_recommendation Analysis and Reporting page_visit Should have Module Optimization, Analysis and Reporting impression Could have Analysis, Reporting and Module Optimization start_subscription Analysis, Reporting and Module Optimization item_interaction Sharing events with Froomle Events can be integrated using multiple connectors. All integration options can be consulted on the integration handbook. In this example we will show how to share events using the Events API. For front-end integration of our events API, refer to our example about JavaScript frontend integration. If you intend to integrate us through your back-end, simply call our Events API when a user triggers one of the events mentioned above. Find below a cURL example for sending some events: $ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/events' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer X' \ --data-raw '{ "events": [ { //send whenever a user visits an item detail page (regardless of a Froomle module being shown) "event_type": "detail_pageview", "page_type": "article_detail", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", "action_item" : "the_action_item_id", "action_item_type": "article", "channel" : "www-desktop" }, { //send whenever a user gets a recommendation in view "event_type": "impression", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", //data from the recommendation "list_name" : "The list name", "action_item" : "the_action_item_id-123", "action_item_type" : "article", "request_id": "6461", "channel": "mobile-app", "user_group": "froomle" }, { //send whenever a user clicks on a recommendation (Froomle or baseline) "event_type": "click_on_recommendation", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", //data from the recommendation "list_name" : "The list name", "action_item" : "the_action_item_id-123", "action_item_type" : "article", "request_id": "6461", "channel": "mobile-app", "user_group": "froomle" }, { //send whenever a user visits a page other than an item detail page (regardless of a Froomle module being shown) "event_type": "page_visit", "page_type": "home", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", "channel" : "www-desktop" }, { //send when a user purchases an item "event_type": "purchase", "device_id" : "the_device_id-123", "user_id" : "the_user_id-123", "action_item": "the_action_item_id-123", "action_item_type": "product", "amount": 10, "original_price": 29.99, "purchased_price": 9.99, "channel": "www-mobile" } ] }' Recommendation Integration Froomle generates a set of recommendations for each recommendation request you send us. In the request you will have to specify the module for which you request recommendations, the user and any specific context we need to know. This includes, but is not limited to: the item currently watched by the user the category from which you expect recommendations articles to be excluded from the recommendations to avoid duplicates. You can see an example lower in the page. General business rules and constraints relevant to the recommendations need to be discussed during the onboarding. By default, items will not be recommended to a user which has viewed the item already. For a full overview of the API specification see: Reference - Recommendations API. Recommendation Response: Froomle can communicate any information you share with us, back to you. This could save you some time fetching the information from your own back-end. Just let us know what you’d like to see in your recommendation response. Each recommendation in the set has a rank indicating the position to show it. Below we provide recommendation integration examples for some of our most used modules: Continue Reading Recommended for you A module showing the articles that the user is most likely to click on given the current article being read (article_detail page). Standard structure for a recommendation request { "device_id": "cookie-id-123", "user_id": "login-id-1234", "channel": "www-desktop", "page_type": "article_detail", "context_item": "current-article-id", // id of the article currently being read "context_item_type": "article", "lists": [ { "list_name": "continue_reading", "module_id": "continue_reading", "list_size": 3, // to be adapted to required number "tags": ["tag1","tag2"], // optional field, can be used to filter on certain tags "categories": ["category1","category2"] //optional field, can be used to filter on certain categories } ], "histories": { // optional: for example, to exclude articles shown elsewhere on the page where the recommendations are placed "exclude": [ { "id": "article_id_1", "item_type": "article", "reconsumable": false }, { "id": "article_id_2", "item_type": "article", "reconsumable": false }, { "id": "article_id_3", "item_type": "article", "reconsumable": false } ] } } Standard structure for a recommendation response { "device_id": "the-cookie-id-123", //same info you send us "user_id": "the-user-id-123-like-cookie", //same info you send us "lists": [ { "items": [ { "information_field": "some_metadata", //agreed fields "item_id": "item_id_1", //recommended item 1 "rank": 1 }, { "information_field": "some_metadata", "item_id": "item_id_2", "rank": 2 }, ... ], "limit": 3, //same info you send us "list_name": "Some list name", //same info you send us } ], "request_id": "2141141", //the request identifier - this is important as we expect you to send this back in your click & impression events "user_group": "froomle" //by default it’s fixed to froomle unless there are different user groups defined } A module containing the most relevant articles for a user based on what we know about him/her. Standard structure for a recommendation request { "device_id": "cookie-id-123", "user_id": "login-id-1234", "channel": "www-desktop", "page_type": "home", "lists": [ { "list_name": "recommended_for_you", "module_id": "recommended_for_you", "list_size": 3, // to be adapted to required number "tags": ["tag1","tag2"], // optional field, can be used to filter on certain tags "categories": ["category1","category2"] //optional field, can be used to filter on certain categories } ], , "histories": { // optional: for example, to exclude articles shown elsewhere on the page where the recommendations are placed "exclude": [ { "id": "article_id_1", "item_type": "article", "reconsumable": false }, { "id": "article_id_2", "item_type": "article", "reconsumable": false }, { "id": "article_id_3", "item_type": "article", "reconsumable": false } ] } } Standard structure for a recommendation response { "device_id": "the-cookie-id-123", //same info you send us "user_id": "the-user-id-123-like-cookie", //same info you send us "lists": [ { "items": [ { "information_field": "some_metadata", //agreed fields "item_id": "item_id_1", //recommended item 1 "rank": 1 }, { "information_field": "some_metadata", "item_id": "item_id_2", "rank": 2 }, ... ], "limit": 3, //same info you send us "list_name": "Some list name", //same info you send us } ], "request_id": "2141141", //the request identifier - this is important as we expect you to send this back in your click & impression events "user_group": "froomle" //by default it’s fixed to froomle unless there are different user groups defined }