How to generate batch recommendations Requesting recommendations When a use case calls for getting personalized recommendations for multiple users in the same process, it is suggested to use the Froomle Batch Recommendations API. To get a batch of recommendations a request file is uploaded to the Froomle SFTP server. The API will take this file, and generate an output file in the same SFTP, which contains the recommendations for the users. For more information on the technical setup see the API Reference on the batch recommendations API. The request can be tailored to the requirements of each type of batch use case such as: weekly recap mails cart renewal mails notifications Typical use cases for batch recommendations are email campaigns or simple push notifications. Weekly recap mail Daily push "environment","user_id","list_name","list_size","page_type" "lorem","AbaT1sagqq1r","Relevant content this week",5,"weekly_mail" "lorem","CdgAgagewaga","Relevant content this week",5,"weekly_mail" "lorem","AbaT1sagqq1r","popular this week",5,"weekly_mail" "lorem","CdgAgagewaga","popular-content-this-week",5,"weekly_mail" "environment","user_id","list_name","list_size","page_type" "lorem","Ar1faf1351","For you today",1,"daily_push" "lorem","AfeafAAetfa3","For you today",1,"daily_push" An explanation of the different fields: environment: The environment for which you are requesting recommendations. user_id: This field form the identification of the user. A request is only valid if this values is non empty. list_name: This lets you define an identifier for a list. Based on this identifier, the Froomle AI will choose the correct configuration for generating recommendations in this list. Froomle will echo it back in its recommendation response, such that there is no confusion which recommendations belong to which list. A list name should be unique per user, device pair in a request. list_size: The number of items to recommend for the user, device pair. page_type: The identifier of the type of batch being sent out, is required to be identical for each row. You can request multiple lists for each users, where each list is a row in the request file. Internally, the Froomle batch API will fire just one request for each user (user_id, device_id pair) and as such make sure that by default, we won’t recommend the same item twice. (This behavior is configurable, contact us for more information at support@froomle.com) For use cases that require a request file with list-columns, you can consult the page Using List Columns When Requesting Batch Recommendations. Getting started Before getting started the communication with the Froomle SFTP needs to be set up. Contact the Froomle support team at support@froomle.com to ask them to setup the authentication. You will need to provide the Froomle with a list of IP addresses which want to access the SFTP, and one or more SSH2 RSA public keys so we can give you access. Once this setup is done you should be able to access the SFTP server through feeder@io.<subdomain>.froomle.com on port 2222. Note that this is different from the default port 22 for SFTP. For more info on SFTP setup see the API Reference on Data Upload. Retrieving recommendations Once the file is uploaded on the SFTP the Froomle Recommendations Platform starts processing. Once the computation is ready the output file is uploaded back on the SFTP, in the responses folder. below you find an example of the response to the requests above. Weekly recap mail Daily push ”user_id”,”user_group”,”campaign_id”,”request_id”,”list_name”,”item_id”,"item_info”,”rank” "AbaT1sagqq1r","froomle","11211211","12411511511","Relevant content this week","item_id_1",1 "AbaT1sagqq1r","froomle","11211211","12411511511","Relevant content this week","item_id_2",2 ... "AbaT1sagqq1r","froomle","11211211","12411511511","popular this week","item_id_7",1 "AbaT1sagqq1r","froomle","11211211","12411511511","popular this week","item_id_9",2 ... "CdgAgagewaga",,"froomle","11211211","52411511541","Relevant content this week","item_id_1",1 "CdgAgagewaga",,"froomle","11211211","52411511541","Relevant content this week","item_id_10",2 ... ”user_id”,”user_group”,”campaign_id”,”request_id”,”list_name”,”item_id”,”rank” "Ar1faf1351","froomle","115111","15115115","For you today","item_id_1",1 "AfeafAAetfa3","froomle","115111","15111515","For you today","item_id_15",1 user_id, list_name are echoed back from the request. user_group: This equals froomle if the user is in a user group that receives Froomle recommendations. request_id: This is a string that should be sent when an event occurs that is related to this recommendation request, such as batch_click_on_recommendation or batch_impression. Thus, it is important to have this value readily available. campaign_id: the identifier of the generated batch of recommendations. Needs to be sent in the events related to any of the recommendations in this batch. Thus it is important to have this value readily available. item_id: The identifier of the recommended item. In this example no additional metadata is communicated in the response. It is possible to ask the Froomle support team to configure this.