Past, offline and omnichannel interactions import

After integrating with Luigi's Box, it takes some time to collect enough behavioral data (products bought together within same session, by same user, etc.) to achieve full effectiveness of our services. In order to shorten or completely overcome this ramp-up period, it's possible for clients to provide past user interactions (typically transactions) they have collected before the integration. For omnichannel clients, in this way, it is possible to import user interactions outside collected channels (typically from brick&mortar stores).

Individual services can benefit from it in the following way:

  • Behavioral recommendation - The behavioral algorithms are trained on co-purchases (products bought in the same session) and need a high amount of data to learn good quality recommendations. In basic scenario, anonymous interactions could be used (see mandatory and optional attributes below).
  • Personalization - Non-anonymous interactions (the attribute user_id is present) help us provide personalized responses. This can be used in search, recommender, autocomplete, product listings etc. It's important to stress that the user_id provided in the uploaded data must have the same value as the user_id provided in a search / recommender / etc. requests. Otherwise, no personalization improvements can be expected.

Import file format

User interactions are expected to be organized into sessions. A single session captures the timeline of a user's interactions on a client page. At this time, only transaction interactions representing product purchases may be included in the import. Other interaction types, such as product clicks, must be omitted. If two products were purchased together but they lack a sequential relationship, they can be provided in any order within the session.

Currently, two data formats are supported:

  • json lines - a file must contain one interaction per line. Expected file extension is .json
  • csv - a file must not contain csv header. The order of provided attributes is predefined. Expected file extension is .csv.

There are two mandatory attributes session_id and identity, which are used as the basis for global (anonymous) co-purchases learning (used in recommenders). The file can also contain two additional attributes, user_id and created_at, which, if present, allow the transaction metadata to be stored in a user profile and improve personalization (used in all Luigi's Box services).

Attribute Description
session_id required Any value enabling to identify products (rows) purchased in the same session.
identityrequired Resource identifier of the purchased product.
user_id optional Id of the user who purchased the product.
created_at optional Timestamp of a purchase used to sort purchases in time. UTC timezone is expected

Example of an import file in the json format:

{"session_id": "1","identity": "/p/123","user_id": "4", "created_at": "2023-04-22 15:04:30.12312"}
{"session_id": "1","identity": "/p/234","user_id": "4", "created_at": "2023-04-22 15:01:33.12345"}
{"session_id": "2","identity": "/p/123","user_id": "3", "created_at": "2023-04-21 00:04:38.12121"}
{"session_id": "2","identity": "/p/345","user_id": "3"}

Example of an import file in the csv format. File should not contain the header, rows contain fields in the following order - session_id, identity (optionally followed by user_id, created_at):

1,/p/123,4,"2023-04-22 15:04:30.12312"
1,/p/234,4,"2023-04-22 15:01:33.12345"
2,/p/123,3,"2023-04-21 00:04:38.12121"
2,/p/345,3

API

POST https://live.luigisbox.com/v1/interactions/<TRACKER_ID>/files

This endpoint requires HMAC authentication. Refer to the Authentication section for details.

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

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

For more information see OpenAPI Specification.

Restrictions

  1. The size of any uploaded file cannot be larger than 1 GB. Files exceeding this limit will be rejected. Reach out to support@luigisbox.com if you need to upload larger files.
  2. n 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.