This page provides detailed documentation for all configuration options available when initializing the ConstructorIO client.
ConstructorClientOptions
The main options object passed to the ConstructorIO constructor.
interface ConstructorClientOptions {
apiKey: string;
version?: string;
serviceUrl?: string;
quizzesServiceUrl?: string;
agentServiceUrl?: string;
mediaServiceUrl?: string;
assistantServiceUrl?: string;
sessionId?: number;
clientId?: string;
userId?: string;
segments?: string[];
testCells?: Record<string, string>;
idOptions?: IdOptions;
fetch?: any;
trackingSendDelay?: number;
sendTrackingEvents?: boolean;
sendReferrerWithTrackingEvents?: boolean;
eventDispatcher?: EventDispatcherOptions;
beaconMode?: boolean;
networkParameters?: NetworkParameters;
humanityCheckLocation?: 'session' | 'local';
}
Required Options
Your Constructor.io API key for authentication. This is the only required parameter.const constructorio = new ConstructorIO({
apiKey: 'key_1234567890abcdef'
});
Service URLs
serviceUrl
string
default:"https://ac.cnstrc.com"
The base API URL endpoint for the main Constructor.io service. Use this to point to a custom endpoint or proxy.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
serviceUrl: 'https://custom.cnstrc.com'
});
quizzesServiceUrl
string
default:"https://quizzes.cnstrc.com"
API URL endpoint for the Quizzes service.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
quizzesServiceUrl: 'https://custom-quizzes.cnstrc.com'
});
agentServiceUrl
string
default:"https://agent.cnstrc.com"
API URL endpoint for the AI Shopping Agent service.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
agentServiceUrl: 'https://custom-agent.cnstrc.com'
});
mediaServiceUrl
string
default:"https://media-cnstrc.com"
API URL endpoint for the Media service.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
mediaServiceUrl: 'https://custom-media.cnstrc.com'
});
assistantServiceUrl
string
default:"https://assistant.cnstrc.com"
Deprecated: Use agentServiceUrl instead. This parameter will be removed in a future version.
User Identification
A unique identifier for the client/browser. In browser environments, this defaults to a value automatically generated by the constructorio-id module. In DOM-less environments (Node.js, etc.), this is required.// DOM-less environment (Node.js)
const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
clientId: 'client-abc123def456',
sessionId: 12345678
});
A unique identifier for the user session. In browser environments, this defaults to a value automatically generated by the constructorio-id module. In DOM-less environments (Node.js, etc.), this is required.// DOM-less environment (Node.js)
const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
clientId: 'client-abc123def456',
sessionId: Date.now()
});
A unique identifier for the logged-in user. This should be set when a user is authenticated and used for personalization and tracking.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
userId: 'user-789xyz'
});
Personalization & Testing
An array of user segments for personalization and targeting. Segments allow you to customize results for different user groups.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
segments: ['premium', 'mobile', 'returning-customer']
});
An object mapping test names to variant names for A/B testing. This allows you to assign users to specific test variants.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
testCells: {
'homepage-redesign': 'variant-b',
'search-algorithm': 'control',
'checkout-flow': 'variant-a'
}
});
Tracking Configuration
Indicates whether tracking events should be automatically dispatched to Constructor.io. When enabled, user interactions are tracked automatically.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
sendTrackingEvents: true
});
The amount of time (in milliseconds) to wait before sending tracking events. This batching helps reduce the number of requests.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
sendTrackingEvents: true,
trackingSendDelay: 500 // Wait 500ms before sending
});
sendReferrerWithTrackingEvents
Indicates whether the referrer URL should be included with tracking events.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
sendTrackingEvents: true,
sendReferrerWithTrackingEvents: false
});
Enable or disable beacon mode for tracking. When enabled, the Navigator.sendBeacon() API is used for sending tracking data, which is more reliable for events sent during page unload.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
beaconMode: true
});
Network Configuration
A custom fetch implementation. If supplied, this will be used for all HTTP requests instead of the default Fetch API. Useful for server-side rendering or custom request handling.import nodeFetch from 'node-fetch';
const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
fetch: nodeFetch
});
Configuration for network requests.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
networkParameters: {
timeout: 5000 // 5 second timeout
}
});
Event Dispatcher Options
Configuration for the event dispatcher system.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
eventDispatcher: {
enabled: true,
waitForBeacon: true
}
});
Storage Configuration
humanityCheckLocation
'session' | 'local'
default:"session"
The storage location for the humanity check flag. Use 'session' for sessionStorage or 'local' for localStorage.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
humanityCheckLocation: 'local' // Use localStorage
});
Configuration options for the constructorio-id module, which manages client and session identification. See IdOptions below for details.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
idOptions: {
persist: true,
cookie_domain: '.example.com',
cookie_days_to_live: 365
}
});
Advanced Options
Custom version string for the client. This is typically auto-generated and should not be manually set unless you have a specific use case.const constructorio = new ConstructorIO({
apiKey: 'YOUR_API_KEY',
version: 'custom-client-v1.0.0'
});
IdOptions
Configuration options for the constructorio-id module, which manages client and session identification.
interface IdOptions {
base_url?: string;
ip_address?: string;
user_agent?: string;
timeout?: number;
persist?: boolean;
cookie_name_client_id?: string;
cookie_name_session_id?: string;
cookie_name_session_data?: string;
local_name_client_id?: string;
local_name_session_id?: string;
local_name_session_data?: string;
cookie_prefix_for_experiment?: string;
cookie_domain?: string;
cookie_days_to_live?: number;
on_node?: boolean;
session_is_new?: boolean;
client_id_storage_location?: 'cookie' | 'local';
session_id_storage_location?: 'cookie' | 'local';
}
Whether to persist client and session IDs across browser sessions.
The domain for storing cookies. Use a leading dot for subdomains (e.g., .example.com).idOptions: {
cookie_domain: '.mystore.com'
}
Number of days before cookies expire.idOptions: {
cookie_days_to_live: 365
}
client_id_storage_location
'cookie' | 'local'
default:"cookie"
Storage location for the client ID. Can be either 'cookie' or 'local' (localStorage).idOptions: {
client_id_storage_location: 'local'
}
session_id_storage_location
'cookie' | 'local'
default:"local"
Storage location for the session ID. Can be either 'cookie' or 'local' (localStorage).idOptions: {
session_id_storage_location: 'cookie'
}
Custom name for the client ID cookie.
Custom name for the session ID cookie.
Custom name for the session data cookie.
Custom name for the client ID in localStorage.
Custom name for the session ID in localStorage.
Custom name for the session data in localStorage.
cookie_prefix_for_experiment
Prefix for experiment-related cookies.
Base URL for the ID service.
IP address of the client (typically used in server-side environments).
User agent string (typically used in server-side environments).
Timeout for ID service requests (in milliseconds).
Indicates if running in a Node.js environment.
Indicates if this is a new session.
EventDispatcherOptions
Configuration options for the event dispatcher.
interface EventDispatcherOptions {
enabled?: boolean;
waitForBeacon?: boolean;
}
Determines whether events should be dispatched.eventDispatcher: {
enabled: true
}
Whether to wait for beacon confirmation before dispatching events.eventDispatcher: {
enabled: true,
waitForBeacon: false
}
NetworkParameters
Configuration for network requests.
interface NetworkParameters {
timeout?: number;
[key: string]: any;
}
Request timeout in milliseconds. This can be overridden within individual method calls.networkParameters: {
timeout: 5000 // 5 seconds
}
Complete Example
Here’s a comprehensive example using many of the available options:
import ConstructorIO from '@constructor-io/constructorio-client-javascript';
const constructorio = new ConstructorIO({
// Required
apiKey: 'key_1234567890abcdef',
// User identification
userId: 'user-abc123',
// Personalization
segments: ['premium', 'mobile', 'returning-customer'],
testCells: {
'homepage-redesign': 'variant-b',
'search-algorithm': 'control'
},
// Tracking
sendTrackingEvents: true,
trackingSendDelay: 500,
sendReferrerWithTrackingEvents: true,
beaconMode: true,
// Network
networkParameters: {
timeout: 5000
},
// Event dispatcher
eventDispatcher: {
enabled: true,
waitForBeacon: true
},
// ID management
idOptions: {
persist: true,
cookie_domain: '.mystore.com',
cookie_days_to_live: 365,
client_id_storage_location: 'local',
session_id_storage_location: 'local'
},
// Storage
humanityCheckLocation: 'local'
});
DOM-less Environment Example
For server-side rendering or Node.js environments:
import ConstructorIO from '@constructor-io/constructorio-client-javascript';
import nodeFetch from 'node-fetch';
const constructorio = new ConstructorIO({
// Required
apiKey: 'key_1234567890abcdef',
// Required in DOM-less environments
clientId: 'client-abc123def456',
sessionId: Date.now(),
// User identification
userId: 'user-789xyz',
// Custom fetch implementation
fetch: nodeFetch,
// Network configuration
networkParameters: {
timeout: 5000
},
// Personalization
segments: ['server-side', 'premium'],
testCells: {
'search-v2': 'enabled'
}
});
