If the browser or your mobile app requests results from Constructor directly, you can use a UI library, call Constructor through a client library, or call the REST API from your own code. This guide explains what each option involves, and the requirements that apply to all three.

A frontend integration is described in Integration approaches: the browser or app calls Constructor's REST API and your own code renders the response. This guide covers the choice you make within that approach. If your own servers request the results instead, see Backend integration options.

The three options

All three options call the same endpoints. The difference is how much you write yourself: a UI library renders results as well as fetching them, a client library fetches and leaves rendering to you, and calling the REST API directly leaves both to you.

Requirements for every option

The API key is public, the API token is not

A frontend integration sends the API key from the browser or app, where anyone can read it. That is by design, and Are the API key and token considered secret? explains why.

Identifiers

On a website, the beacon sets the anonymous user identifier i and the session identifier s. In an app, the iOS or Android SDK sets them. The libraries read these values for you. See Identification parameters for how these values are assigned and stored.

If you call the REST API directly, send the same values that the beacon or the SDK uses. Do not generate your own, because then your requests do not match the rest of that user's activity.

The user identifier ui is different. Only your system knows who is signed in, so no library sets it for you. For a signed-in user, pass your own user ID to the library, or send it as ui on each request. If the user is not signed in, omit it.

Choosing UI libraries

The UI libraries are for websites. For a native app, use a client library or the REST API.

Three questions decide whether a UI library fits, in this order.

Does it support your stack? The libraries are React and TypeScript, and each exposes a native JavaScript interface for use outside React. A stack that cannot use either rules this option out before the other two questions matter.

Are the surfaces you need covered? There is a library per surface, so confirm the ones you need exist rather than assuming the set is complete. UI libraries lists what each one covers, with a Storybook for each.

Can you style it the way you need? The components are customizable, but within a boundary. If your design requires markup the library does not produce, use the client library and write the view layer yourself.

Using a client library

Pick the library for the platform that makes the request:

• Website: JavaScript. It also works in React Native, as described in Utilization in a DOM-less environment.
• iOS app: iOS / Swift.
• Android app: Android / Kotlin.

Client libraries / SDKs covers installation. Each library requests results and sets i, s, and c for you, so most of the requirements above need no work from you.

Calling the REST API directly

The endpoints are documented in the API Reference: Search, Autocomplete, Browse, and Recommendations.

Because no library sets values for you, your requests must carry the parameters in Required parameters.

If a library covers your case, read Client library usage justification before choosing this option.

Verifying your integration

A frontend integration fails visibly more often than a backend one, but these checks catch the problems that still return a valid response.

• The identifiers match (REST API directly). Compare the i and s values on a results request with the values the beacon or the mobile SDK holds on the same device. Read them again for each request, because the session identifier changes when a session expires.
• Every required parameter is sent (REST API directly). Compare a real request from the browser or app against Required parameters.
• The API token is absent. Search your bundle or app binary for the token, and confirm only the API key is there.
• Zero results and redirects behave. Confirm a query with no matches renders your empty state, and that a query configured to redirect does redirect.
• Filters, sorting, and pagination. Confirm each one changes the request as well as the view, and that the result count matches what was returned.

Recommended order of work

1. Confirm your catalog is loaded into a test index, so there is data to return.
2. Place the beacon on your website, or add the mobile SDK to your app, so that tracking and the identifiers exist.
3. Pick your option using the questions above, and build against a test index.
4. Run the checks above, then move to your production index.