Skip to main content
Before you launch a recommendation widget on your site, six integrations need to be in place. The widget itself is just the rendering layer — what makes recommendations relevant is the data flowing into Maestra Platform from your site, your catalog, and your customers. Use this checklist to confirm everything is wired up.

​
1. Tracker on every page

The Maestra tracker script must load on every page where a recommendation widget will appear. The tracker is what:
  • Identifies the visitor (anonymous or known).
  • Reports page views to Maestra Platform.
  • Loads the widget engine itself.
If the tracker isn’t present on a page, the widget won’t render there — even if the targeting rules match.
The cleanest setup is to include the tracker in your global site template (header or footer partial) so it loads on every URL automatically. That way you never have to remember to add it to a new page.

​
2. Product catalog synchronization

Maestra Platform needs an up-to-date copy of your catalog to recommend from. Set up a regular product feed that delivers:
  • Product ID — must match the ID your site uses, so the widget can link back to the right product page.
  • Product URL — the canonical link to the product page.
  • Display name — the product name as shown on the site.
  • Price and old price — current selling price plus the pre-discount price, if any.
  • Image URL — main product image (and additional images if your card template uses them).
  • Categories — primary category and any secondary categories the product belongs to.
  • Availability — in stock, out of stock, low stock.
  • Brand / manufacturer — for multi-brand catalogs and brand-aware algorithms.
  • Custom fields — any extra attributes you want available in the card template (color, size, material, rating, etc.).
The feed should refresh frequently enough that price and stock changes don’t lag the storefront. For most catalogs, hourly is a safe baseline; for fast-moving inventory, every 15 minutes.
If product IDs in the feed don’t match the IDs your site emits in browsing and order events, the algorithm can’t correlate behavior with products. Sync IDs first — without that, no recommendation will work correctly.

​
3. Regional data (if you sell across zones)

If you operate in multiple zones — different countries, regions, or warehouses with different pricing and stock — you also need:
  • Regional feed — per-zone prices and stock for each product.
  • Zone attribute on the customer — every event from the customer must include their current zone so the algorithm knows which regional data to apply.
Without zone data, customers in California might see prices and availability meant for New York shoppers.

​
4. Real-time event tracking

The algorithm relies on live customer behavior. Configure the following events to flow to Maestra Platform in real time:
  • Product views — fired when a customer opens a product page.
  • Category views — fired on category and listing pages.
  • Add to cart — every time a product is added.
  • Remove from cart — every removal.
  • Add to favorites / wishlist — wishlist toggles in both directions.
  • Search — search queries entered on the site.
  • Order placed — completed purchases with line items.
Each event needs to carry the product ID (matching the catalog), the customer identifier, and a timestamp. These events feed personalization, browse-abandonment, and cart-abandonment algorithms.
Events should be sent server-side wherever possible. Client-side-only tracking is fine for views but loses data on cart and order events when customers have ad-blockers or unstable connections.

​
5. Site personalization code

Site personalization is a separate JavaScript snippet that turns the page into a surface Maestra Platform can personalize. It:
  • Loads in the page head, ideally synchronously, so it can intercept render before content paints.
  • Reads targeting rules from Maestra Platform and decides which widgets, pop-ups, and embedded blocks apply to the current visitor.
  • Triggers the widget engine to render whatever is approved.
If site personalization isn’t loaded, recommendation widgets won’t appear even if the tracker and catalog are fully set up.

​
6. Widget container markup

For each widget, you need a <div> container placed where the widget should render — or a CSS selector pointing to an existing element on the page. Two patterns:

​
Manual container

Paste the container HTML directly into your site template at the exact spot you want the widget. Use this for pixel-level control:
Then, in the widget’s display settings, point it at #recommendations-homepage.

​
Selector-based insertion

Pick an existing element on the page and let Maestra Platform inject the widget into it. Pass the CSS selector in the widget’s display settings, and the engine handles insertion at runtime. This is the easier option when you don’t want to edit site templates.
Even when using selector-based insertion, choose a stable selector — a class or ID that won’t change on the next site redesign. Avoid auto-generated class names from CSS-in-JS frameworks.

​
Putting it together

A working recommendation widget setup looks like this:
1

Tracker installed on every page

Global include in your site template.
2

Product feed running

Hourly or faster, with matching IDs.
3

Regional feed (if applicable)

Plus zone attribute on every customer event.
4

Behavior events streaming

Views, cart, favorites, search, orders — all real-time.
5

Site personalization snippet loaded

In the page head, on every page that needs widgets.
6

Widget containers in place

Either embedded div blocks or stable CSS selectors.
With all six in place, you can create a recommendation widget and it will work on the first try.