ConstructorIO Client - Constructor.io JavaScript Client

The ConstructorIO class is the main entry point for the Constructor.io JavaScript Client SDK. It provides access to all SDK modules including search, browse, autocomplete, recommendations, tracking, quizzes, and agent functionality.

Constructor

Creates a new instance of the ConstructorIO client.

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

const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY',
  userId: 'user-123',
  segments: ['desktop', 'premium'],
  testCells: {
    'test-1': 'variant-a',
    'test-2': 'variant-b'
  }
});

Parameters

options

object

required

Configuration options for the client

Show properties

apiKey

string

required

Constructor.io API key for authentication

serviceUrl

string

default:"https://ac.cnstrc.com"

API URL endpoint for the main Constructor.io service

quizzesServiceUrl

string

default:"https://quizzes.cnstrc.com"

Quizzes API URL endpoint

agentServiceUrl

string

default:"https://agent.cnstrc.com"

AI Shopping Agent API URL endpoint

mediaServiceUrl

string

default:"https://media-cnstrc.com"

Media API URL endpoint

assistantServiceUrl

string

default:"https://assistant.cnstrc.com"

Deprecated: Use agentServiceUrl instead. This parameter will be removed in a future version.

AI Shopping Assistant API URL endpoint

segments

string[]

User segments for personalization and targeting

testCells

Record<string, string>

User test cells for A/B testing. Object mapping test names to variant names

clientId

string

Client ID. Defaults to value supplied by the constructorio-id module. Required in DOM-less environments

sessionId

number

Session ID. Defaults to value supplied by the constructorio-id module. Required in DOM-less environments

userId

string

User ID for tracking and personalization

fetch

function

Custom fetch implementation. If supplied, will be used for requests instead of the default Fetch API

trackingSendDelay

number

default:250

Amount of time to wait before sending tracking events (in milliseconds)

sendReferrerWithTrackingEvents

boolean

default:true

Indicates if the referrer is sent with tracking events

sendTrackingEvents

boolean

default:false

Indicates if tracking events should be automatically dispatched

idOptions

IdOptions

Options object to be supplied to the constructorio-id module. See Client Options for details

eventDispatcher

EventDispatcherOptions

Options related to the EventDispatcher class

Show properties

enabled

boolean

default:true

Determine if events should be dispatched

waitForBeacon

boolean

default:true

Wait for beacon before dispatching events

networkParameters

NetworkParameters

Parameters relevant to network requests

Show properties

timeout

number

Request timeout in milliseconds. May be overridden within individual method calls

beaconMode

boolean

default:true

Enable or disable beacon mode for tracking

humanityCheckLocation

'session' | 'local'

default:"session"

Storage location for the humanity check flag. Use 'session' for sessionStorage or 'local' for localStorage

Returns

A ConstructorIO instance with the following module properties:

search - Interface to the Search module
browse - Interface to the Browse module
autocomplete - Interface to the Autocomplete module
recommendations - Interface to the Recommendations module
tracker - Interface to the Tracker module
quizzes - Interface to the Quizzes module
agent - Interface to the AI Shopping Agent module
assistant - Interface to the Assistant module (deprecated, use agent instead)

Example

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

// Basic initialization
const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY'
});

// Advanced initialization with custom options
const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY',
  userId: 'user-123',
  segments: ['premium', 'mobile'],
  testCells: {
    'homepage-redesign': 'variant-b',
    'checkout-flow': 'control'
  },
  sendTrackingEvents: true,
  trackingSendDelay: 500,
  networkParameters: {
    timeout: 5000
  },
  eventDispatcher: {
    enabled: true,
    waitForBeacon: true
  }
});

// Use the client modules
constructorio.search.getSearchResults('red shoes');
constructorio.autocomplete.getAutocompleteResults('shoe');

DOM-less Environment Example

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

// In Node.js or other DOM-less environments, clientId and sessionId are required
const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY',
  clientId: 'client-abc123',
  sessionId: 12345678,
  userId: 'user-456',
  fetch: customFetchImplementation // Optional custom fetch
});

setClientOptions

Updates the client options after initialization. This method allows you to modify certain client settings without creating a new instance.

constructorio.setClientOptions({
  userId: 'new-user-id',
  segments: ['vip', 'desktop'],
  sendTrackingEvents: true
});

Parameters

options

object

required

Client options to update

Show properties

apiKey

string

Constructor.io API key

segments

string[]

User segments for personalization and targeting

testCells

Record<string, string>

User test cells for A/B testing

sessionId

number

Session ID. Will only be set in DOM-less environments

userId

string

User ID for tracking and personalization. Pass null or undefined to clear the user ID

sendTrackingEvents

boolean

Indicates if tracking events should be dispatched

Returns

void

Example

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

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

// Update user information after login
constructorio.setClientOptions({
  userId: 'authenticated-user-123',
  segments: ['premium', 'logged-in']
});

// Update test cells based on experiment assignment
constructorio.setClientOptions({
  testCells: {
    'new-feature-test': 'variant-a'
  }
});

// Enable tracking events
constructorio.setClientOptions({
  sendTrackingEvents: true
});

// Clear user ID on logout
constructorio.setClientOptions({
  userId: null
});

// Update session ID in DOM-less environment
constructorio.setClientOptions({
  sessionId: 98765432
});

Notes

Only the specified options will be updated; other options remain unchanged
The sessionId parameter will only be updated in DOM-less environments
To clear the userId, pass null or undefined as the value
The sendTrackingEvents option also updates the tracker module’s configuration

Client

Search

Autocomplete

Browse

Recommendations

Quizzes

Agent

Tracker

​Constructor

​Parameters

​Returns

​Example

​DOM-less Environment Example

​setClientOptions

​Parameters

​Returns

​Example

​Notes

Build docs developers (and LLMs) love

Constructor

Parameters

Returns

Example

DOM-less Environment Example

setClientOptions

Parameters

Returns

Example

Notes