@constructor-io/constructorio-client-javascript

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, four modules will be exposed as properties to help retrieve data from Constructor.io: search, browse, autocomplete, recommendations and tracker.

Dispatched events

The search, browse, recommendations and autocomplete modules may dispatch custom events on 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 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