Recombee JavaScript API Client

6.2.1 · active · verified Tue Apr 21

The `recombee-js-api-client` is a client-side JavaScript SDK designed for seamless integration with the Recombee recommendation API. Currently at version 6.2.1, it provides a thin wrapper around the Recombee API, enabling applications to send user-item interactions (such as detail views, purchases, or cart additions) and request personalized recommendations or search results. The library exhibits an active release cadence, with multiple minor and major versions released recently, indicating ongoing development and improvements. Key differentiators include its UMD compatibility, built-in TypeScript definitions, and its specific design for browser-based or other client-side environments like React Native or NativeScript. It is crucial to note that this client-side SDK focuses on data collection and recommendation retrieval using a public token and does not support catalog management operations for security reasons, which are handled by a separate server-side Node.js SDK.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates initializing the Recombee client, sending a user-item interaction (a detail view), and requesting item-to-item recommendations with specified properties, including basic error handling.

import recombee from 'recombee-js-api-client';

const RECOMBEE_DATABASE_ID = process.env.RECOMBEE_DATABASE_ID ?? 'your-database-id';
const RECOMBEE_PUBLIC_TOKEN = process.env.RECOMBEE_PUBLIC_TOKEN ?? 'your-db-public-token';
const RECOMBEE_REGION = process.env.RECOMBEE_REGION ?? 'eu-west'; // e.g., 'us-west', 'eu-west'

// Initialize the API client with your database ID and PUBLIC token
export const client = new recombee.ApiClient(
  RECOMBEE_DATABASE_ID,
  RECOMBEE_PUBLIC_TOKEN,
  {
    region: RECOMBEE_REGION,
    // Optional: Increase default timeout if needed, e.g., 10 seconds
    // timeout: 10000,
  },
);

// Send interactions (e.g., AddDetailView, AddCartAddition, AddPurchase)
client.send(
  new recombee.AddDetailView('user-4395', 'item-129', {
    cascadeCreate: true, // Creates user/item if they don't exist
    recommId: '23eaa09b-0e24-4487-ba9c-8e255feb01bb', // Optional: Link to a previous recommendation
  }),
).then(() => {
  console.log('Detail view interaction sent successfully.');
}).catch((error) => {
  console.error('Failed to send detail view interaction:', error);
});

// Request recommendations (e.g., RecommendItemsToItem, RecommendItemsToUser)
async function getRecommendations() {
  try {
    const response = await client.send(
      new recombee.RecommendItemsToItem('item-356', 'user-13434', 5, {
        returnProperties: true, // Include item properties in the response
        includedProperties: ['title', 'imageUrl'], // Specify which properties to return
      }),
    );

    console.log('Recommendation ID:', response.recommId);

    // The `recomms` array contains recommended items with their IDs and properties
    response.recomms.forEach((item) => {
      console.log(`Recommended Item ID: ${item.id}, Title: ${item.values?.title}, Image: ${item.values?.imageUrl}`);
    });
  } catch (error) {
    console.error('Error requesting recommendations:', error);
    // Implement fallback logic here, e.g., show popular items
  }
}

getRecommendations();

view raw JSON →