Integration Overview

Luigi’s Box is a product discovery suite that relies on a feedback loop between your catalog data and user behavior.

To integrate successfully, you must connect three distinct systems:

1. Analytics: Send us user behavior signals (Clicks, Purchases).
2. Data Sync: Send us your product data (Catalog).
3. Service Integration: Display our results (Search, Recommendations) to your users.

---

Analytics

The foundation of intelligent discovery.

We recommend implementing Analytics first. Even though your catalog might not be synced yet, starting analytics immediately allows the system to buffer user behavior data.

Caution

Critical Prerequisite: You must decide on your Object Identity now. If you plan to use SKUs in your product feed later, you must send those same SKUs in your analytics events now. The system will retrospectively link this data once the catalog is synced.

Option A: DataLayer collector (recommended)

This is the ideal approach for most stores. It captures events you are likely already pushing to the dataLayer for Google Analytics (GA4).

• Pros: Seamless integration; reliable tracking of all event types.
• Cons: Requires GTM configuration.
• Read the DataLayer Collector Guide

Option B: Events API

Designed for mobile apps or custom websites that want to avoid 3rd-party scripts.

• Pros: Absolute control; no external script weight.
• Cons: Requires backend development effort.
• Read the Events API Documentation

Option C: Managed integration

If you lack a development team, Luigi’s Box can hook into your existing HTML structure.

• Pros: Zero dev effort.
• Cons: Brittle. Breaks if you redesign your HTML.
• Contact support for this option.

---

Data synchronization

Keep your product catalog up to date.

You need to choose a method to keep your database in sync with Luigi’s Box.

flowchart LR
A["Supported platform"]
B["Custom backend"]
C["Legacy system"]
D["Luigi's Box index"]
A -->|Platform connector| D
B -->|Content Updates API| D
C -->|XML feed pull| D

Option A: Platform connectors (best for supported platforms)

If you run on a supported platform, use our native plugin. This is the most reliable method.

Supported: Shopify, Shoptet, Shopware, Commercetools, WooCommerce, Prestashop, Contentspeed, BSShop, Creativesites, WPJ.

Option B: Content updates API (real-time)

Push data changes to our servers immediately as they happen in your backend.

• Pros: Real-time sync; efficient (only updates changed items).
• Cons: Requires development to identify “save” hooks in your code.
• Read the Content Updates API Guide

Option C: XML/JSON feeds

We periodically download and process a static file from your server.

• Pros: Easy to implement (just generate a file).
• Cons: Slow. Updates only appear after the next scheduled fetch (e.g., every 3 hours).
• Read the Feeds Guide

---

Service integration

Displaying results to the customer.

You can integrate our services on the Frontend (Browser) or Backend (Server).

flowchart TD
User1["User"]
FE["Frontend integration"]
LB1["Luigi's Box API"]
User2["User"]
Server["Your server"]
LB2["Luigi's Box API"]
User1 -->|"Uses JS library"| FE
FE -->|"Calls API"| LB1
LB1 -->|"Returns data"| FE
FE -->|"Renders results"| User1
User2 -->|"Requests page"| Server
Server -->|"Calls API"| LB2
LB2 -->|"Returns data"| Server
Server -->|"Renders HTML"| User2

Backend integration

You call the Luigi’s Box API from your server and render the HTML yourself.

• Best for: Search Results, Product Listings (Categories).
• Why: Keeps your URL structure and SEO control entirely on your side. Allows complex B2B pricing logic before rendering.

Frontend integration

You use our JavaScript libraries (Autocomplete.js, Search.js) to render results in the browser.

• Best for: Autocomplete, Recommendations.
• Why: Extremely fast implementation. Visuals are handled by the library, and we can deploy new features remotely.

---

Summary of recommendations

For a typical e-commerce store, we recommend the following “Hybrid” setup:

Service	Recommended Integration	Why?
Analytics	Frontend	Use the DataLayer collector to leverage your existing GA events.
Autocomplete	Frontend	Use autocomplete.js for a fast, beautiful overlay that requires minimal coding.
Search	Backend	Ensures the search results page (SERP) looks exactly like the rest of your site and retains SEO benefits.
Listings	Backend	Same as Search — ensures consistency for category and brand pages.
Recommenders	Frontend	Flexible placement anywhere on the site without impacting server performance.