Constructor.io JavaScript Client

A JavaScript client for Constructor.io. Constructor.io provides search as a service that optimizes results using artificial intelligence (including natural language processing, re-ranking to optimize for conversions, and user personalization).

This client is intended for use in a browser environment but can also be used in React Native based mobile applications. Additional information about utilization in a React Native context can be found on the Wiki. If you want a JavaScript client for server side integrations please use @constructor-io/constructorio-node

Documentation

Full API documentation is available on Github Pages

1. Install

This package can be installed via npm: npm i @constructor-io/constructorio-client-javascript. Once installed, simply import or require the package into your repository.

Alternatively, a bundled version consisting of a single JavaScript file is published within the ./dist folder on Github. This can be utilized within a browser context if hosted locally - please do not link directly to the Github hosted version.

Important: this library should only be used in a client-side context where standard HTTP request headers are populated by the client (User-Agent, Referer, etc.).

2. Retrieve an API key

You can find this in your Constructor.io dashboard. Contact sales if you'd like to sign up, or support if you believe your company already has an account.

3. Implement the Client

Once imported, an instance of the client can be created as follows:

const ConstructorioClient = require('@constructor-io/constructorio-client-javascript');

const constructorio = new ConstructorioClient({
    apiKey: 'YOUR API KEY',
});

4. Retrieve Results

After instantiating an instance of the client, seven modules will be exposed as properties to help retrieve data or send behavioral events: search, browse, autocomplete, recommendations, quizzes, agent, and tracker.

AI Shopping Agent and Product Insights Agent

• agent retrieves AI Shopping Agent (ASA) results as a stream.
• agent.pia retrieves Product Insights Agent (PIA) questions and answers.
• tracker has the trackAgent* methods for ASA events and the trackProductInsightsAgent* methods for PIA events.

Note:

1. The assistant namespace is deprecated. Use agent instead.

2. agent receives results through the browser EventSource interface. React Native does not include EventSource. If you use agent in React Native, add an EventSource polyfill.

Dispatched events

Modules may dispatch custom events on the browser window with response data when a request has been completed. The event name follows the following structure: cio.client.[moduleName].[methodName].completed. Example consuming code can be found below:

window.addEventListener('cio.client.search.getSearchResults.completed', (event) => {
  // `event.detail` will be response data
}, false);

Development / npm commands

npm run prepare       # one-time after cloning: install husky git hooks (pre-push lint)
npm run lint          # run lint on source code and tests
npm run test          # run tests
npm run coverage      # run tests and serves coverage reports from localhost:8081
npm run docs          # output documentation to `./docs` directory

npm version <patch|minor|major> --ignore-scripts=false   # bump version (see note below)

Note: .npmrc sets ignore-scripts=true for supply-chain safety, so lifecycle scripts do not run automatically. This affects two workflows:

• husky git hooks: run npm run prepare once after cloning to enable the pre-push lint hook.
• npm version: the version lifecycle script (which regenerates src/version.js, docs, and the ./dist bundle and stages them into the release commit) is skipped. Always pass --ignore-scripts=false when bumping the version so these artifacts are regenerated.