Object Identity
Object Identity is the cornerstone of the Luigi's Box feedback loop.
The "Identity" is a unique string (numerical or textual) used to unambiguously identify a specific item in your catalog—whether it is a product, category, brand, or article.
Important The Golden Rule: The Identity must be unique across all types and immutable (it should never change).
Why Identity Matters
Object identity controls two critical processes in Luigi's Box: Updates and Pairing.
1. Updates & Deduplication
Object identities serve as primary keys in our database. When you use the Indexing APIs to send data, we use the identity to decide whether to create a new item or update an existing one.
ID: 123] end subgraph Logic A --> B{Does ID 123 exist?} B -- Yes --> C[Update Existing Item] B -- No --> D[Create New Item] end style C fill:#bbf style D fill:#bbf
The Trap of Mutable IDs (URLs)
If you use a mutable value (like a URL) as an ID, you risk creating duplicates.
-
Day 1: You send Product A with ID
url-1. (Created) -
Day 2: You change the URL. You send Product A with ID
url-2. (Created as Duplicate) - Result: You now have two versions of the same product. The history is split, and search relevance suffers.
Tip Best Practice: Always use an internal, immutable ID (such as a database Primary Key or SKU) rather than a URL.
2. Pairing (The Feedback Loop)
"Pairing" is the process of matching a user's action (Analytics) to a specific item in the data you indexed (Catalog).
For the AI to learn from user behavior, the ID sent in the analytics event must match the ID provided in the product feed exactly.
(User Click)"] B["Product Feed
(Catalog Data)"] end subgraph LB ["Luigi's Box AI"] A -- "Sends ID: 123" --> C{Pairing Check} B -- "Sends ID: 123" --> C C -- Match --> D[Learning Signal] C -- Mismatch --> E[Signal Ignored] end style D fill:#9f9,stroke:#333 style E fill:#f99,stroke:#333
Common Pairing Errors:
| Catalog ID | Analytics ID | Result | Reason |
12345 |
12345 |
✓ Match | Perfect alignment. |
12345 |
SKU_12345 |
✕ Fail | Prefix mismatch. |
12345 |
https://site.com/p/12345 |
✕ Fail | Sending URL instead of ID. |
Warning Check your status: You can check your pairing health in the Luigi's Box application under Catalog browser > Data quality checks. You should aim for near 100% pairing.
Migrating from URLs to Immutable IDs
Historically, it was common to use URLs as object identities. However, because URLs often change (e.g., SEO updates, category restructuring), this causes data loss. When a URL changes, the product effectively becomes a "new" item, losing all historical ranking and behavioral data.
If you are currently using URLs as IDs, we strongly recommend migrating to immutable IDs (like SKUs).
Danger Stop: Do not attempt this migration without coordinating with us. Contact support to ensure your historical data is preserved.
The migration involves three steps:
Step 1: Model Migration
We need to ensure the AI doesn't lose its memory.
- Option A (ID exists in data): If your current feed already contains the new ID in a separate field, we can rebuild models internally.
-
Option B (Mapping File): If not, provide us with a CSV mapping file (Column A:
Old URL, Column B:New ID). We will use this to transfer the historical data.
Step 2: Update Analytics
You must stop sending URLs in your tracking events.
- Events API: Update your backend calls to send the new ID.
- DataLayer/Script: You must expose the new ID in your frontend code so our script can grab it. See the Product Identification guide.
Step 3: Reindex Catalog
- Content Updates API: You must delete the old objects (by URL) and send the new objects (by ID).
- Feeds: We will manage the reindex for you by reprocessing the full feed.
Summary Checklist
A valid Identity must be:
- [ ] Unique across all object types (a Category cannot have the same ID as a Product).
- [ ] Immutable (it never changes for the lifetime of the object).
- [ ] Consistent (the same string is used in both the Catalog Feed and the Analytics layer).