Recommendation batch publisher
Luigi's Box typically provides real-time recommendations through the Recommender API. However, for situations requiring recommendations to be generated for a large, defined user set at a scheduled time – for example, sending personalized recommendations via newsletter – Luigi's Box offers a Recommendation batch publisher service. This service can automatically create personalized recommendations in batches per the configured schedule.
The process for defining, generating and retrieving a batch of published recommendations consists of the following steps:
- Step 1 - The client uploads a set of users to be recommended for
- Step 2 - Luigi's Box sets up recommendation logics based on the client's preferences
- Step 3 - Luigi's Box sets up a recommendation batch publisher schedule based on the client's preferences
- Step 4 - Luigi's Box prepares and publishes recommendations at the scheduled time
- Step 5 - The integrated platform retrieves the generated recommendations
- Step 6 - The integrated platform distributes recommendations to customers
Step 1 - The client uploads a set of users to be recommended for
Before batch of recommendations can be prepared, client needs to define list of users to recommend for. The process differs depending on the used integration.
SmartEmailing integration
For SmartEmailing integration, Luigi's Box downloads the user list from SmartEmailing API. The client needs to specify to Luigi's Box the field in which the user identifier is stored.
Other integrations
For integrating with a platform other than SmartEmailing, use Batching users API to upload the set of users.
Batching users API
POST http://live.luigisbox.com/v1/batching/<TRACKER_ID>/users
Request Headers
| Header | Content |
|---|---|
| Content-Type | multipart/form-data; boundary=sk13jk8sd823j9 |
Keep in mind that when the HMAC token is generated, the provided Content-Type should
be multipart/form-data, without the boundary.
Request body
The request body is a file containing user ids. File format details are described in the section Import file format.
| Form | Content |
|---|---|
| file | @"/path/to/file.json" |
For more information see openapi.yaml.
Restrictions
- Uploading a new file will remove existing users for the specified tracker id.
- The size of any uploaded file cannot be larger than 300 MB. Files exceeding this limit will be rejected. Reach out to support@luigisbox.com if you need to upload larger files.
- An uploaded file must fully transmit within 10 minutes. If the upload takes longer than the 10-minute timeout limit, an error will be returned and the upload canceled. If you encounter issues while uploading, reach out to support@luigisbox.com.
Import file format
The import file must be in the JSON Lines or CSV format. It has one mandatory attribute user_id.
| Attribute | Description |
|---|---|
user_id required
|
Id of the user. |
Example of an import file in the JSON Lines format:
{"user_id": "u123"}
{"user_id": "u234"}
{"user_id": "u345"}
Example of an import file in the CSV format. File should not contain the header, rows contain field user_id:
"u123"
"u234"
"u345"
Step 2 - Luigi's Box sets up recommendation logics based on the client's preferences
Client defines business requirements, based on which Luigi's Box prepares recommendation logics.
Step 3 - Luigi's Box sets up a recommendation batch publisher schedule based on the client's preferences
Client defines how often recommendations for each logics should be generated.
Step 4 - Luigi's Box prepares and publishes recommendations at the scheduled time
Using the recommendation batch publisher service, Luigi's Box prepares and publishes the recommendations according to the configured recommendation logics and schedule. However, certain integrations may require providing additional data for the batch generation process.
SmartEmailing integration
Client provides Luigi's Box username and API key for access SmartEmailing API.
Step 5 - The integrated platform retrieves the generated recommendations
For each user, recommendations contain personalized list of results (typically products) for each recommender logic.
Recommendations are generated for users with interaction data from the past 6 months. In addition to batch of
personalized recommendation sets for defined users, Luigi's Box generates also 1 generic set of non-personalized
recommendations. It can be found under key default. It can be used for recommendation to new users without browsing
history, users without cookie consent granted, etc.
Batches of recommendations are generated at the highest set frequency. For example, if recommender_logic_1 is set
to be generated biweekly and recommender_logic_2 is set for weekly generation, Luigi's Box will generate
recommendations for both logics on a weekly basis.
Format of recommendations and way of retrieving data differs depending on the integration.
SmartEmailing integration
For SmartEmailing integration, the batch recommendation results in JSON format are uploaded directly to SmartEmailing API. Luigi's Box creates collection to which recommendations are uploaded.
Published recommendations JSON format
{
"id": "u123",
"data": {
"mail-recommender-1": [
{
"id": "product1-id",
"url": "https://www.client-xyz.com/product1-url/",
"title": "Product 1",
"image_link": "https://www.client-xyz.com/product1-img.jpg/"
},
...
]
},
...
}
Other integrations
For integrating with a platform other than SmartEmailing, contact Luigi's Box to obtain a link for accessing the generated recommendations in an XML format.
Published recommendations XML format
Published recommendations have the following structure where one line contains recommendations for one user:
<?xml version='1.0' encoding='UTF-8'?>
<users>
<user> ... </user>
<user> ... </user>
<user> ... </user>
</users>
Detailed structure of recommendations for one user:
<?xml version='1.0' encoding='UTF-8'?>
<users>
<user>
<user_id>u123</user_id>
<data>
<_metadata>
<updated_at>2024-08-28T10:00:00</updated_at>
</_metadata>
<recommendations>
<recommendation>
<recommendation_type>mail-recommender-1</recommendation_type>
<results>
<result>
<id>product1-id</id>
<url>https://www.client-xyz.com/product1-url/</url>
<title>Product 1</title>
<image_link>https://www.client-xyz.com/product1-img.jpg/</image_link>
</result>
<result>
<id>product2-id</id>
<url>https://www.client-xyz.com/product2-url/</url>
<title>Product 2</title>
<image_link>https://www.client-xyz.com/product2-img.jpg/</image_link>
</result>
</results>
</recommendation>
<recommendation>
<recommendation_type>mail-recommender-2</recommendation_type>
<results>
<result>
<id>product3-id</id>
<url>https://www.client-xyz.com/product3-url/</url>
<title>Product 3</title>
<image_link>https://www.client-xyz.com/product3-img.jpg/</image_link>
</result>
<result>
<id>product4-id</id>
<url>https://www.client-xyz.com/product4-url/</url>
<title>Product 4</title>
<image_link>https://www.client-xyz.com/product4-img.jpg/</image_link>
</result>
</results>
</recommendation>
</recommendations>
</data>
</user>
</users>
Step 6 - The integrated platform distributes recommendations to customers
It is important to stress that Luigi's Box only generates batch recommendations and does not handle actual delivery of the recommendations to end customers. In fact, email addresses or any other contact data are not even collected in the Luigi's Box database. This responsibility is delegated to the integrated platform.