Batch Recommendations API

When a use case calls for getting personalized recommendations for multiple users 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 on the same SFTP, which contains the recommendations for the users.

Requesting recommendations in batch happens by uploading a CSV file to the Froomle SFTP. The Froomle platform will then compute the recommendations and upload a CSV file back onto the SFTP.

After reading this page you should have an understanding of

The structure of the request file
The structure of the response file
How to use the Froomle SFTP to get batch recommendations

SFTP

Authentication

You authenticate to the SFTP server using SSH, as shown in the diagram below.

Figure 1. SFTP Communication Diagram

Froomle requires that a public/private SSH2 (RSA) key pair is generated for communication with Froomle only. This key pair should not have a passphrase.

The generated key should be of type SSH2 RSA. When using modern tools to generate an RSA key, the default key type is usually an SSH2 RSA key. In case of any doubt, consult the documentation of the key-gen tool you used.

The private key will live on the server used to export your files and should be stored securely. The public key should be mailed to support@froomle.com. Froomle will then take the necessary actions so that you can access the SFTP server with the feeder account, using your private key. We advise to generate a separate key pair per server if multiple servers will export files to the Froomle SFTP.

The Froomle SFTP server only accepts incoming connections from whitelisted IP ranges. These IP ranges should be delivered by email to support@froomle.com. We only accept connections on port 2222. Note that this is different from the standard port 22 typically used for SFTP.

Target directories

Our SFTP server has 2 directories for batch specifically: Requests and responses.

requests: Reserved for batch recommendation requests files. In case of a batch integration this is where the batch request files have to be uploaded. The request filename has to contain the date of the campaign to allow for easier tracking and analysis.
responses: Reserved for batch recommendation response files. This is the only directory that is reserved for Froomle to write to. In case of a batch integration this is where our generated response files will be stored. The filename of the response will match the one provided in the requests directory.

These directories are standard and can not be removed/renamed. Creating additional directories is not possible.

Files uploaded to the SFTP server are removed automatically by Froomle after the upload is completed to our internal infrastructure. Files uploaded by Froomle (e.g. in the responses directory) can be removed after you consume them. If not removed, we will automatically remove them after 7 days.

For the batch recommendations we will only use the requests and responses folders.

Request file

The request file should be uploaded in the requests folder on the Froomle SFTP.

How should I name my request file?

The Froomle platform uses substring matching on the filename to identify what to do with the file. We therefore encourage you to use semantically meaningful names of the form <{environment-name}_{campaign_name}_YYYY-MM-DDTHH:mm:ssZ.csv>.

For example a batch computation to send a weekly mail would look like: lorem_weekly_mail_2020-02-02T20:22:02Z.csv.

What type of CSV should I send?

The CSV file should use , as delimiter.
strings should be quoted using ".
The file should contain a header.
Optional fields with null values are sent by leaving that position empty in the csv (,,)

What structure should the request file be?

The request file contains a row for each list of recommendations that needs to be generated. If multiple lists need to be generated for a single user, multiple lines in the request need to be present.

Specification
Example

Field

Schema

Description

environment*

string

Required. Defines the environment for which Froomle computes recommendations. There can be only 1 environment used in a single request file.

user_id

string

Required. The identifier of the user to generate recommendations for.

device_id

string

Optional. The identifier of the device to generate recommendations for. At least 1 way of identifying who to generate recommendations for needs to be present. If there is no user_id, then a device_id needs to be present and the other way around. It is also possible to give a value for both.

list_name*

string

Required. Defines the name of the list the recommendations will be shown in. It should be the same as the title of the list where the recommendations are shown. It is not interpreted, but will be sent back in the response to make clear which recommendations belong together. It is also used for performance tracking in dashboards.

list_size*

integer

Required. The number of recommendations to compute in the list.

page_type*

string

Required. The identifier of the page where the recommendations will be used. If more than one list is requested for a (user_id, device_id)-pair, use the same page_type for each row in the request file. The first one will always be used. For simplicity and evaluation we suggest using a single page_type per request. Accepted page_types are: email, emailweekly, emaildaily, emailadhoc, emailtopical and push. If none of these fit your use case, please get in touch with your account manager.

other variables

string

Optional. The CSV can also contain a number of other fields. Before these can be used, discuss with your SA what the best approach is, and which fields need to be used. An example could be a category to select the items from. category and then the values can be shoes in a retail context or sport in a news context.

"environment","user_id","device_id","list_name","list_size","page_type"
"lorem","some-user",,"Relevant for you this week",5,"weekly_mail"
"lorem","some-other-user",,"Relevant for you this week",5,"weekly_mail"
"lorem","some-user",,"Discover this",5,"weekly_mail"

Response File

Froomle will upload the response file in the responses folder on the Froomle SFTP once the computation is ready.

What structure will the response file have?

The response file will also be a CSV file. It will contain a row per item recommended for a user.

Specification
Example

Field Schema Description

Field	Schema	Description
`user_id`	`string`	The identifier of the user the recommendations were for.
`device_id`	`string`	The identifier of the device the recommendations have been generated for.
*`user_group`**	`string`	identifies which provider generated the recommendations. `froomle` if the Froomle platform was used.
*`campaign_id`**	`string`	the identifier of the generated batch of recommendations. Needs to be sent in the events related to any of the recommendations in this batch.
*`request_id`**	`string`	The identifier of a set of recommendations. Each user, device_id, list_name tuple will have a single unique request_id.
*`list_name`**	`string`	Defines the name of the list the recommendations will be shown in. Together with the user_id and device id the list name defines a single list of recommendations which will have ranks from 1 to N. These recommendations are supposed to be shown together in the use case.
*`rank`**	`integer`	The rank of the recommendation, when a list contains multiple recommendations, they should be shown ordered by their rank field.
*`item_id`**	`string`	The identifier of the recommended item
`information_field(s)`	`string`	If additional information about the recommended item is expected to be returned, contact your SA to have Froomle set these up for you. The names of these fields can be chosen. In the example we will use url.

user_id

string

The identifier of the user the recommendations were for.

device_id

string

The identifier of the device the recommendations have been generated for.

user_group*

string

identifies which provider generated the recommendations. froomle if the Froomle platform was used.

campaign_id*

string

the identifier of the generated batch of recommendations. Needs to be sent in the events related to any of the recommendations in this batch.

request_id*

string

The identifier of a set of recommendations. Each user, device_id, list_name tuple will have a single unique request_id.

list_name*

string

Defines the name of the list the recommendations will be shown in. Together with the user_id and device id the list name defines a single list of recommendations which will have ranks from 1 to N. These recommendations are supposed to be shown together in the use case.

rank*

integer

The rank of the recommendation, when a list contains multiple recommendations, they should be shown ordered by their rank field.

item_id*

string

The identifier of the recommended item

information_field(s)

string

If additional information about the recommended item is expected to be returned, contact your SA to have Froomle set these up for you. The names of these fields can be chosen. In the example we will use url.

”user_id”,”device_id”,”user_group”,”campaign_id”,”request_id”,”list_name”,”item_id”,"url,”rank”
"some-user",,"froomle","11211211","12411511511","Relevant for you this week","item_id_1","some_url.net",1
"some-user",,"froomle","11211211","12411511511","Relevant for you this week","item_id_2","some_url2.net",2
...
"some-user",,"froomle","11211211","12411511511","Discover this","item_id_7","some_url.net",1
"some-user",,"froomle","11211211","12411511511","Discover this","item_id_9","some_url2.net",2
...
"some-other-user",,"froomle","11211211","52411511541","Relevant for you this week","item_id_1","some_url.net",1
"some-other-user",,"froomle","11211211","52411511541","Relevant for you this week","item_id_10","some_url10.net",2
...