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. This service can automatically create personalized recommendations in batches according to the configured schedule.

An important prerequisite is the use of Customer IDs in the analytics collection process. Customer IDs are identifiers of logged-in users. Check the Events API documentation to learn how to track Customer IDs. Based on collected user data, the batch publisher can recommend personalized content for requested users.

The process for defining, generating, and retrieving a batch of published recommendations consists of the following steps:

1. The client defines the set of users to recommend for.
2. Luigi’s Box sets up recommendation logics based on the client’s preferences.
3. Luigi’s Box sets up a recommendation batch publisher schedule based on the client’s preferences.
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.

Step 1 - The client defines the set of users to recommend for

Before a batch of recommendations can be prepared, the client needs to define the set of users to recommend for. Typically, the client defines a set of customer_id values depending on the integration.

Another option is to have Luigi’s Box recommend for all known users whose customer_id was active in the past 6 months.

SmartEmailing integration

For SmartEmailing integration, Luigi’s Box retrieves the user list from the SmartEmailing API automatically. The client needs to tell Luigi’s Box which field stores the user identifier.

Klaviyo integration

Klaviyo has a profiles API for retrieving user data stored in the Klaviyo database. To match Klaviyo users with user profiles saved in the Luigi’s Box database, the Luigi’s Box customer_id needs to be saved in the Klaviyo user profile. The customer_id can be saved in any attribute under the attributes.properties structure.

For more information about customer_id, see Events API common parameters.

Other integrations

To integrate with other platforms, use the Batching users API to upload the set of users.

Batching users API

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. File format details are described in Import file format.

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

For more information, see the OpenAPI specification.

Restrictions

1. Uploading a new file removes existing users for the specified tracker ID.
2. Uploaded files 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.
3. An uploaded file must be fully transmitted within 10 minutes. If the upload takes longer than the 10-minute timeout limit, the server returns an error and cancels the upload. If you encounter issues while uploading, reach out to support@luigisbox.com.

Import file format

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

Attribute	Description
auth_user_id	Required. ID of the user. Previously named user_id; the old name is still supported.

Example of an import file in JSON Lines format:

{"auth_user_id": "u123"}
{"auth_user_id": "u234"}
{"auth_user_id": "u345"}

Example of an import file in CSV format. The file should not contain a header. Each row contains the auth_user_id field:

"u123"
"u234"
"u345"

Step 2 - Luigi’s Box sets up recommendation logics based on the client’s preferences

The 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

The client defines how often recommendations for each logic 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

The client provides a Luigi’s Box username and API key for access to the SmartEmailing API.

Klaviyo integration

To access and modify user profiles via the Klaviyo API, Luigi’s Box requires a private key with the following permissions:

1. lists:read
2. lists:write
3. profiles:read
4. profiles:write

For more information about private keys, see the Klaviyo documentation about private key authentication.

Step 5 - The integrated platform retrieves the generated recommendations

For each user, recommendations contain a 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 personalized recommendation sets for the defined users, Luigi’s Box also generates one generic set of non-personalized recommendations. It is stored under the key default and can be used for recommendations to new users, users without browsing history, users without cookie consent granted, and similar cases.

Batches of recommendations are generated at the highest configured 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.

The format of recommendations and the way of retrieving data differ depending on the integration. Note that each result’s url contains a tracking parameter named recommendation_id, generated by the recommender. This identifier is used by the analytics collector. See Step 7.

SmartEmailing integration

For SmartEmailing integration, the batch recommendation results are uploaded directly to the SmartEmailing API in JSON format. Luigi’s Box creates a 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/?recommendation_id=1234abcd-7425-4fee-bed2-214dwxyz7890",
        "title": "Product 1",
        "image_link": "https://www.client-xyz.com/product1-img.jpg/"
      }
    ]
  }
}

Klaviyo integration

Generated recommendations are uploaded directly to user profiles via the Klaviyo API. They are stored in JSON format under the attributes.properties structure of individual profiles.

As described above, Luigi’s Box generates one set of non-personalized recommendations and saves it under the default profile. A Klaviyo profile is considered to be the default profile if its attributes.external_id attribute is equal to default. If no such profile is present, Luigi’s Box automatically creates one.

Published recommendations JSON format

The following snippet shows a user profile with generated recommendations under the key mail-recommender-1.

{
  "data": {
    "type": "profile",
    "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
    "attributes": {
      "email": "sarah.mason@klaviyo-demo.com",
      "properties": {
        "mail-recommender-1": [
          {
            "id": "product1-id",
            "url": "https://www.client-xyz.com/product1-url/?recommendation_id=1234abcd-7425-4fee-bed2-214dwxyz7890",
            "title": "Product 1",
            "image_link": "https://www.client-xyz.com/product1-img.jpg/"
          }
        ]
      }
    }
  }
}

Other integrations

To integrate with a platform other than SmartEmailing, contact Luigi’s Box to obtain a link for accessing the generated recommendations in XML format.

Published recommendations XML format

Published recommendations have the following structure:

<?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>
    <auth_user_id>u123</auth_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/?recommendation_id=1234abcd-7425-4fee-bed2-214dwxyz7890</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/?recommendation_id=1234abcd-7425-4fee-bed2-214dwxyz7890</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/?recommendation_id=wxyz7890-7425-4fee-bed2-214d1234abcd</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/?recommendation_id=wxyz7890-7425-4fee-bed2-214d1234abcd</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

Luigi’s Box only generates batch recommendations and does not handle delivery of the recommendations to end customers. Luigi’s Box does not collect email addresses or any other contact data. The integrated platform is responsible for delivery.

Step 7 - Luigi’s Box / client collects analytics data

By default, the Luigi’s Box analytics collector supports tracking recommendations from batch publishers. This is possible because the URLs of generated recommendations contain the recommendation_id parameter, for example https://www.client-xyz.com/product1-url/?recommendation_id=1234abcd-7425-4fee-bed2-214dwxyz7890. Based on these URLs, the Luigi’s Box analytics collector on the client’s website can collect user interactions with recommendations.

The analytics dashboard at https://app.luigisbox.com/sites/<TRACKER_ID>/recommenders/analytics then shows statistics for individual newsletter recommendations in the same way as for other models.

For a custom analytics integration, follow the Events API documentation and pass the value of recommendation_id into the Impression analytics event.