Skip to main content
The Constructor.io JavaScript Client SDK is initialized with a configuration object that controls API communication, user identification, tracking behavior, and network settings.

​
Basic Initialization

The only required parameter is your Constructor.io API key: 
import ConstructorIO from '@constructor-io/constructorio-client-javascript';

const constructorClient = new ConstructorIO({
  apiKey: 'YOUR_API_KEY'
});

​
Configuration Options

​
Required Parameters

​
apiKey
string
required
Your Constructor.io API key. This authenticates your application with the Constructor.io service.
const constructorClient = new ConstructorIO({
  apiKey: 'key_1234567890'
});

​
Service URLs

Customize API endpoints for different Constructor.io services:
​
serviceUrl
string
default:"https://ac.cnstrc.com"
The base URL for Constructor.io API requests (search, autocomplete, browse, recommendations).
serviceUrl: 'https://ac.cnstrc.com'
​
quizzesServiceUrl
string
default:"https://quizzes.cnstrc.com"
The base URL for the Quizzes API.
quizzesServiceUrl: 'https://quizzes.cnstrc.com'
​
agentServiceUrl
string
default:"https://agent.cnstrc.com"
The base URL for the AI Shopping Agent API.
agentServiceUrl: 'https://agent.cnstrc.com'
​
mediaServiceUrl
string
default:"https://media-cnstrc.com"
The base URL for the Media API (banner ads and display advertising).
mediaServiceUrl: 'https://media-cnstrc.com'

​
User Identification

Identify and segment users for personalized experiences:
​
clientId
string
A unique identifier for the current client/device. If not provided, the SDK automatically generates one using the constructorio-id module.
In DOM-less (server-side) environments, you must provide a clientId.
clientId: 'client_abc123def456'
​
sessionId
number
A unique identifier for the current user session. If not provided in browser environments, the SDK automatically generates one using the constructorio-id module.
In DOM-less (server-side) environments, you must provide a sessionId.
sessionId: 1234567890
​
userId
string
Your internal user identifier. Use this to tie Constructor.io events to your own user tracking system.
userId: 'user_789xyz'
​
segments
array
An array of user segment names for personalization. See User Segments for more details.
segments: ['VIP', 'mobile_user', 'returning_customer']
​
testCells
object
Key-value pairs defining A/B test assignments for the user. See User Segments for more details.
testCells: {
  'homepage_layout': 'variant_b',
  'search_algorithm': 'test_v2'
}

​
Tracking Configuration

Control how tracking events are sent to Constructor.io:
​
sendTrackingEvents
boolean
default:false
When true, enables automatic sending of tracking events to Constructor.io. Events are queued and sent asynchronously.
Set this to true to enable behavioral tracking and analytics. Without this, search, click, and conversion events won’t be recorded.
sendTrackingEvents: true
​
trackingSendDelay
number
default:250
Delay in milliseconds before sending queued tracking events. This helps batch events and avoid sending too many requests.
trackingSendDelay: 500 // Wait 500ms before sending
​
sendReferrerWithTrackingEvents
boolean
default:true
Include the page referrer (origin URL) with tracking events. Also includes UTM parameters if present.
sendReferrerWithTrackingEvents: true

​
Event Dispatcher Options

Configure the event dispatcher for custom event handling:
​
eventDispatcher
object
Configuration for the internal event dispatcher that emits custom DOM events.
​
eventDispatcher.enabled
boolean
default:true
Whether to dispatch custom events on the window object (e.g., cio.client.instantiated).
eventDispatcher: {
  enabled: true
}
​
eventDispatcher.waitForBeacon
boolean
default:true
Wait for the Constructor.io beacon to load before dispatching events. The beacon is loaded from legacy Constructor.io integrations.
eventDispatcher: {
  waitForBeacon: false // Dispatch immediately
}

eventDispatcher: {
  enabled: true,
  waitForBeacon: true
}

​
Network Configuration

​
fetch
function
Custom fetch implementation. By default, the SDK uses the native Fetch API. Provide your own if you need custom request handling.
fetch: customFetchFunction
​
networkParameters
object
Global network settings applied to all requests.
​
networkParameters.timeout
number
Request timeout in milliseconds. Can be overridden in individual method calls.
networkParameters: {
  timeout: 5000 // 5 second timeout
}

​
Advanced Options

​
idOptions
object
Options passed to the constructorio-id module for client and session ID generation.
idOptions: {
  // Custom options for ID generation
}
​
humanityCheckLocation
string
default:"session"
Storage location for the humanity check flag. Use 'session' for sessionStorage or 'local' for localStorage.The humanity check prevents bot traffic from being tracked.
humanityCheckLocation: 'local' // Use localStorage
​
beaconMode
boolean
default:true
Enable beacon mode for tracking requests. When enabled, adds a beacon=true parameter to POST requests.
beaconMode: true

​
Complete Configuration Example

import ConstructorIO from '@constructor-io/constructorio-client-javascript';

const constructorClient = new ConstructorIO({
  // Required
  apiKey: 'key_1234567890',
  
  // User identification
  userId: 'user_abc123',
  segments: ['premium', 'mobile'],
  testCells: {
    'search_test': 'variant_a',
    'ui_test': 'control'
  },
  
  // Tracking
  sendTrackingEvents: true,
  trackingSendDelay: 250,
  sendReferrerWithTrackingEvents: true,
  
  // Network
  networkParameters: {
    timeout: 10000 // 10 second timeout
  },
  
  // Event dispatcher
  eventDispatcher: {
    enabled: true,
    waitForBeacon: false
  }
});

​
Updating Configuration at Runtime

You can update certain client options after initialization using the setClientOptions method: 
constructorClient.setClientOptions({
  userId: 'new_user_id',
  segments: ['VIP', 'returning'],
  testCells: { 'experiment_1': 'variant_b' },
  sendTrackingEvents: true
});
Only the following options can be updated at runtime:
  • apiKey
  • userId
  • segments
  • testCells
  • sendTrackingEvents
  • sessionId (only in DOM-less environments)

​
Server-Side Usage

When using the SDK in a server-side (DOM-less) environment, you must provide clientId and sessionId: 
const constructorClient = new ConstructorIO({
  apiKey: 'key_1234567890',
  clientId: 'server_client_123',
  sessionId: 9876543210,
  sendTrackingEvents: true
});
If you don’t provide clientId and sessionId in a server-side environment, the SDK will throw an error.

​
Accessing SDK Modules

Once initialized, the client provides access to various modules: 
// Search
constructorClient.search.getSearchResults('query');

// Autocomplete
constructorClient.autocomplete.getAutocompleteResults('que');

// Browse
constructorClient.browse.getBrowseResults('filter_name', 'filter_value');

// Recommendations
constructorClient.recommendations.getRecommendations('pod_id');

// Tracker
constructorClient.tracker.trackSearchResultClick('query', { itemId: '123' });

// Quizzes
constructorClient.quizzes.getQuizNextQuestion('quiz_id');

// Agent
constructorClient.agent.sendMessage('conversation_id', 'message');
Each module is fully configured with the options you provided during initialization.

Build docs developers (and LLMs) love

Get started for freeTalk to us