How to generate batch recommendations

Requesting recommendations

When a use case calls for getting personalised 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","device_id","list_name","list_size","page_type","configuration_id"
"lorem","AbaT1sagqq1r",,"Relevant content this week",5,"weekly_mail","OneWeekContent"
"lorem","CdgAgagewaga",,"Relevant content this week",5,"weekly_mail","OneWeekContent"
"lorem","AbaT1sagqq1r",,"popular this week",5,"weekly_mail","OneWeekContent"
"lorem","CdgAgagewaga",,"popular-content-this-week",5,"weekly_mail","OneWeekContent"
"environment","user_id","device_id","list_name","list_size","page_type","configuration_id"
"lorem",,"Ar1faf1351","For you today",1,"daily_push","NewRelevantContent"
"lorem",,"AfeafAAetfa3","For you today",1,"daily_push","NewRelevantContent"

An explanation of the different fields:

  • environment: The environment for which you are requesting recommendations.

  • user_id, device_id: These two fields form the identification of the user. A request is only valid if at least one of the 2 values is non empty. If both are present, the batch recommendations API will use both. The user id is used for logged in users, the device id is typically a cookie or some other device identifier.

  • list_name: This lets you define an identifier for a list. It should match the title of the list the recommendations are shown in. We don’t interpret this name, but we will echo it back in our 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.

  • configuration_id: This defines which previously defined set of constraints to apply to the recommendations. These sets of constraints can be managed through the configurations API. Though Froomle can manage these for you, we encourage you to define your own, as this provides an easy way of customising the results to your liking.

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 your Solutions Architect for more information at support@froomle.com)

Getting started

Before getting started the communication with the Froomle SFTP needs to be set up. Contact your Froomle Solution Architect at support@froomle.com to ask them to setup the authentication. You will need to provide the Froomle with a list of IP adresses 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.<customer_token>.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”,”device_id”,”user_group”,”version”,”campaign_id”,”request_id”,”list_name”,”item_id”,"item_info”,”rank”
"AbaT1sagqq1r",,"froomle","froomle_1","11211211","12411511511","Relevant content this week","item_id_1",1
"AbaT1sagqq1r",,"froomle","froomle_1","11211211","12411511511","Relevant content this week","item_id_2",2
...
"AbaT1sagqq1r",,"froomle","froomle_1","11211211","12411511511","popular this week","item_id_7",1
"AbaT1sagqq1r",,"froomle","froomle_1","11211211","12411511511","popular this week","item_id_9",2
...
"CdgAgagewaga",,"froomle","froomle_2","11211211","52411511541","Relevant content this week","item_id_1",1
"CdgAgagewaga",,"froomle","froomle_2","11211211","52411511541","Relevant content this week","item_id_10",2
...
”user_id”,”device_id”,”user_group”,”version”,”campaign_id”,”request_id”,”list_name”,”item_id”,”rank”
,"Ar1faf1351","froomle","froomle_1","115111","15115115","For you today","item_id_1",1
,"AfeafAAetfa3","froomle","froomle_2","115111","15111515","For you today","item_id_15",1
  • device_id, 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.

  • version: This specifies in which A/B group the user is currently enrolled.

  • 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 your Froomle Solution Architect to configure this.