Skip to main content
Traditional e-commerce search matches keywords. Refine understands what products look like. When you search for “floral midi dress,” Refine:
  1. Understands the text — semantic understanding of “floral,” “midi,” and “dress”
  2. Analyzes visual features — patterns, colors, silhouettes from product images
  3. Combines both signals — the visualWeight parameter controls the balance
// Text-heavy search (specs matter more)
const results = await refine.search.text({
  query: 'laptop 16gb ram',
  visualWeight: 0.2  // 80% text, 20% visual
});

// Visual-heavy search (appearance matters more)
const results = await refine.search.text({
  query: 'boho summer dress',
  visualWeight: 0.7  // 30% text, 70% visual
});

​
Catalogs

A catalog is a collection of products that share a search index. Most stores have one catalog, but you might use multiple for:
  • Separate indexes per locale (US, EU, APAC)
  • B2B vs B2C product sets
  • Multiple brands under one organization
Each catalog has a unique ID used in SDK initialization: 
const refine = new Refine({
  catalogId: 'cat_us_retail_2024'
});

​
Visual Embeddings

When you upload a product, Refine generates a visual embedding — a numerical representation of what the product looks like. These embeddings power:
  • Visual similarity — finding products that look alike
  • Image search — matching uploaded photos to your catalog
  • Visual weight — the visual component of text search
Embeddings are generated automatically. You don’t need to manage them directly.

​
Surfaces and Sources

When tracking events, you specify where the products appeared and how they got there.

​
Surface

The UI location where products are displayed:
SurfaceDescription
search_resultsMain search results page
product_pageProduct detail page recommendations
home_pageHomepage recommendations
cart_pageCart page cross-sells
category_pageCategory/PLP pages
checkoutCheckout page suggestions

​
Source

How the products were generated:
SourceDescription
text-searchText search results
image-searchImage search results
similar-itemsSimilar product recommendations
visitor-recsVisitor-based recommendations
user-recsUser-based recommendations
plpProduct listing page
const context = refine.events.trackItemsServed({
  surface: 'product_page',
  source: 'similar-items',
  itemIds: productIds
});

​
Identity Hierarchy

Refine tracks three levels of identity:
1

Visitor ID

Auto-generated, persisted in localStorage. Survives sessions but not device changes. Every user starts as a visitor.
2

Session ID

Auto-generated per browsing session. Expires after 30 minutes of inactivity (configurable).
3

User ID

Your identifier, set via refine.identify(). Links visitor behavior to a known user account.
// Anonymous visitor browsing
const visitorId = refine.getVisitorId(); // Auto-generated

// User logs in
refine.identify('user_12345');

// Now visitor history is linked to user_12345
const recs = await refine.recs.forUser({ configId: 'config_abc' });

​
Recommendation Strategies

Refine supports three recommendation types:

​
Similar Items

Find products visually and contextually similar to a specific product. Best for product detail pages. 
const recs = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',  // The product being viewed
  topK: 8
});

​
Visitor Recommendations

Personalized suggestions based on the current visitor’s browsing behavior. No login required. 
const recs = await refine.recs.forVisitor({
  configId: 'homepage_recs',
  topK: 12
});

​
User Recommendations

Deep personalization based on a logged-in user’s full history across sessions and devices. 
refine.identify('user_12345');
const recs = await refine.recs.forUser({
  configId: 'you_may_like',
  topK: 12
});

​
ServeContext Pattern

The SDK uses a ServeContext pattern for event tracking. When products are displayed, you get a context object that tracks subsequent interactions: 
// Products are served
const context = refine.events.trackSearch(query, results.results, options);

// User interacts
context.trackClick(productId, position);    // They clicked
context.trackView(productId, position);     // It became visible
context.trackAddToCart(productId);          // They added to cart
This pattern ensures all interactions are correctly attributed to the original search or recommendation serve.

​
Next Steps

Glossary

Full terminology reference

SDK Overview

Start building with the SDK