Past, offline and omnichannel transactions 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 transactions they have collected before the integration. For omnichannel clients, in this way, it is possible to import user transactions 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 transactions could be used (see mandatory and optional attributes below).
-
Personalization - Non-anonymous transactions (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 theuser_id
provided in the uploaded data must have the same value as theuser_id
provided in a search / recommender / etc. requests. Otherwise, no personalization improvements can be expected.
After successful transactions upload into API, the client will recive response message 200, meaning that the data were successfully uploaded. They will be processed later on background. In case of any error, whole import is canceled. API doesn't allow data removal or update. If needed, contact support@luigisbox.com. Upload of mutlipe data files (e.g. on weekly basis or one time split of a large file) will cause their cumulative usage. Data uploaded into API are used for up to 52 weeks.
Import file format
User transactions are expected to be organized into sessions. A single session groups customer's transactions which happen at the same time and captures the ordering of these transactions in time. Currently, only 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. |
identity required
|
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
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 transactions. 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
- 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.
- 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.