Recommendation batch publisher

Luigi’s Box typically provides real-time recommendations through the Recommender API. However, for situations requiring recommendations 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.

An important prerequisite is the usage of Customer IDs in the analytics collection process. Based on collected user data, the batch publisher can recommend personalized content for requested users.

Process overview

1. The client defines the set of users to recommend for
2. Luigi’s Box sets up recommendation logics based on preferences
3. Luigi’s Box sets up a schedule
4. Luigi’s Box prepares and publishes recommendations at the scheduled time
5. The integrated platform retrieves the generated recommendations
6. The integrated platform distributes recommendations to customers
7. Luigi’s Box / client collects analytics data

Define the user set

Before a batch of recommendations can be prepared, you need to define the set of users. Typically this is a set of customer_id values depending on the used integration.

SmartEmailing integration

For SmartEmailing integration, Luigi’s Box retrieves the user list from the SmartEmailing API automatically. You need to specify which field stores the user identifier.

Klaviyo integration

Klaviyo’s profiles API allows retrieving user data stored in the Klaviyo database. The Luigi’s Box customer_id needs to be saved in the Klaviyo user profile under attributes.properties.

Other integrations (batching users API)

For other platforms, use the Batching users API to upload the set of users.

POST https://live.luigisbox.com/v1/recommender/batching/<TRACKER_ID>/users

Caution

This endpoint requires HMAC authentication. See API principles for details.

Request headers

Header	Content
Content-Type	multipart/form-data; boundary=sk13jk8sd823j9

When generating the HMAC token, the provided Content-Type should be multipart/form-data, without the boundary.

Request body

The request body is a file containing user ids.

Form	Content
file	@"/path/to/file.json"

Restrictions

1. Uploading a new file removes existing users for the specified tracker id.
2. Maximum file size: 300 MB.
3. Upload must complete within 10 minutes.

Import file format

The import file must be in JSON Lines or CSV format with one mandatory attribute auth_user_id.

{"auth_user_id": "user1@example.com"}
{"auth_user_id": "user2@example.com"}