Skip to main content

​
What is Constructor.io?

Constructor.io provides search as a service that optimizes results using artificial intelligence, including:
  • Natural Language Processing - Understand user intent and query variations
  • AI-Powered Re-ranking - Optimize results to maximize conversions
  • Personalization - Tailor results based on user behavior and preferences
  • Product Discovery - Enable browsing, recommendations, and quizzes

​
About this SDK

The Constructor.io JavaScript Client SDK (@constructor-io/constructorio-client-javascript) is designed for client-side browser environments and React Native applications. It provides a complete interface for:

Search

Full-text search with filters, sorting, and pagination

Autocomplete

Real-time search suggestions as users type

Browse

Category and collection browsing

Recommendations

Personalized product recommendations

Quizzes

Interactive product discovery quizzes

AI Agent

AI Shopping Agent for conversational commerce

​
Key Features

​
Automatic Session Management

The client automatically handles session tracking and client identification through the integrated @constructor-io/constructorio-id package. No manual cookie management required.

​
Event Tracking

Built-in behavioral event tracking sends user interactions (clicks, conversions, etc.) to optimize your search results over time.

​
Custom Events

The SDK dispatches browser events when requests complete, allowing you to integrate with your application’s event system: 
window.addEventListener('cio.client.search.getSearchResults.completed', (event) => {
  console.log('Search results:', event.detail);
});

​
Browser vs Node Client

This JavaScript client is specifically designed for browser environments where standard HTTP headers (User-Agent, Referer, etc.) are automatically populated by the browser.

​
Use the JavaScript Client when:

  • Building frontend applications (React, Vue, Angular, vanilla JS)
  • Developing React Native mobile apps
  • You need automatic session/client ID management
  • Tracking user behavior in real-time

​
Use the Node Client instead when:

  • Building server-side applications or APIs
  • Running in Node.js without DOM environment
  • Implementing server-side rendering (SSR)
  • Performing catalog management or admin operations
For server-side integrations, use @constructor-io/constructorio-node instead.
The JavaScript client can be used in DOM-less environments (like React Native) but requires manual clientId and sessionId management. See the Wiki for details.

​
Available Modules

Once instantiated, the client exposes seven modules:
  • search - Search for products with filters, sorting, and pagination
  • browse - Browse categories, collections, and filtered results
  • autocomplete - Get search suggestions and completions
  • recommendations - Retrieve personalized product recommendations
  • quizzes - Implement interactive product discovery quizzes
  • agent - AI Shopping Agent for conversational experiences
  • tracker - Send behavioral events (clicks, conversions, etc.)

​
Next Steps

Installation

Install the SDK via npm or use the bundled version

Quickstart

Get up and running with your first search in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us