Welcome to the Beam React SDK documentation page. This SDK provides reusable React hooks and utilities designed to interact smoothly with the Crossing Minds API. You can leverage Beam, our customized recommendation platform, to supercharge your application's user engagement. Learn more about Beam here.

Our library is highly versatile, being compatible with several flavors of React, such as Remix-run, Shopify Hydrogen, and Next JS. This makes it an invaluable tool, especially for Shopify merchants who have developed their storefronts using the Hydrogen framework.

Prerequisites

Before delving into the usage of this SDK, ensure that you have the following Crossing Minds account details:

• A service account serviceLoginId with a frontend role.
• A password for the service account.
• A databaseId that belongs to the same organization as your service account.

To create a service account, you can either use the Crossing Minds dashboard or contact Crossing Minds directly. Please note that individual or team accounts cannot interact with this library; it is designed exclusively for service accounts.

By default, only accounts with a frontend role can interact with this library because frontend accounts' "passwords" are non-secret, making auth implementation straightforward.

SessionId

Most parts of this library require a sessionId. This unique id assigned to an end-user of your product needs to be consistent across the server, client/browser/app as long as your product defines a session. You are responsible for generating and managing your app's session ids.

Please note, userIds are different from sessionIds. userIds are only assigned to known end-users and remain consistent for the lifetime of the end-user (permanent). In contrast, sessionIds are assigned to all end-users, including anonymous ones.

Installation

To install this library to your React application, use the package manager CLI of your choice (we prefer pnpm). The package includes TypeScript types for ease of use.

bashCopy codenpm install @crossingminds/beam-react

Exports

Our Beam React SDK exports several important functionalities that you can leverage to boost your application's user experience.

• getItemBasedRecommendations: Get recommendations for items based on an item id.
• getPersonalizedRecommendations: Fetch either sessionId or userId-based recommendations.
• useRecordItemInteractions: Hook that returns a set of functions used to record end-user interactions with items. These interactions are crucial for improving recommendation quality.
• OptimizedInputProperties: Properties included in input params of most functions. If these remain the same across multiple calls, some performance optimizations will be applied.

Usage

In this section, we'll discuss the usage of the Beam React SDK in different environments.

Remix-run, Shopify Hydrogen with Oxygen (server-side)

For Remix and Hydrogen apps, we recommend using a loader function to fetch recommendations server-side. Here we're using Oxygen as our host, but feel free to choose any host you prefer.

For example, to add recommendations to a page, a single function call to either getPersonalizedRecommendations for userId and sessionId based recommendations, or getItemBasedRecommendations for itemId based recommendations will suffice.

Your responsibility includes managing your own SessionIds, which are crucial for personalizing recommendations. The Hydrogen framework allows passing a session object into your loader function. Please refer to the Hydrogen docs for more information on using sessions.

React Query (client-side)

When fetching recommendations in a client (browser) environment, we recommend using React Query. Here's an example of getting item-based recommendations on a product page.

You will need to integrate our exported functionalities with your product display and create a dynamic, personalized user experience.

‍

Whether you're a developer looking to enhance your application or a Shopify merchant wanting to level up your store, our Beam React SDK can provide the needed boost. Please feel free to reach out if you need further assistance or have any questions.

‍