> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recommendations

> Fetch recommended items from a MoEngage recommendation in your React Native app and build your own UI.

## Overview

The MoEngage React Native SDK fetches the recommended items for a recommendation you created on the MoEngage dashboard and returns them to your app as key-value data, handling user identity, networking, and caching internally.

> [!TIP]
>
> **Prerequisites**
>
> * Recommendations must be enabled for your workspace. Contact your MoEngage account manager to enable it.
> * Integrate `react-native-moengage` 13.1.0 or above, which the Recommendations plugin requires. For more information, refer to [Framework Dependency](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-installation/framework-dependency.md).
> * You have created a recommendation on the MoEngage dashboard and know its Recommendation ID. For more information, refer to [Recommendations](https://moengage.com/docs/user-guide/content/recommendations/getting-started/overview.md).
> * You have initialized the core MoEngage SDK in your application. For more information, refer to [React Native SDK Initialization](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-initialization/manual-initialization/framework-initialization.md).

## Install the Module

Add the MoEngage Recommendations plugin to your project:

```shellscript Shell theme={null}
npm install react-native-moengage-recommendations
```

### iOS Installation

Install the iOS dependencies for the `react-native-moengage-recommendations` plugin with either CocoaPods or Swift Package Manager (SPM). For the supported packages and setup details, refer to [iOS Installation](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-installation/ios.md).

> [tab] CocoaPods
>
> 1. Navigate to the `ios` directory.
> 2. Run the following command:
>
>    ```bash Bash theme={null}
>    bundle exec pod install
>    ```

> [tab] Swift Package Manager (SPM)
>
> > [!WARNING]
> >
> > SPM support is experimental and requires React Native 0.87 or later. For the supported packages, setup details, and limitations, refer to [iOS Installation](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-installation/ios.md).
>
> 1. Navigate to the `ios` directory.
> 2. Set up SPM:
>
>    * If the iOS project still uses CocoaPods, convert it once with `npx react-native spm add --deintegrate`. For more information, refer to [Migrate From CocoaPods to SPM](https://moengage.com/docs/developer-guide/react-native-sdk/migration/migration-of-moengage-sdk-from-cocoapods-to-spm.md).
>    * If the iOS project already uses SPM, run:
>
>      ```bash Bash theme={null}
>      npx react-native spm
>      ```
>
> With SPM you no longer run `pod install`. The MoEngage native SDKs resolve automatically from their SPM repositories.

## Fetch Recommended Items

> [!WARNING]
>
> Initialize the core MoEngage SDK before you call `fetchRecommendations()`. If the SDK is not initialized, the promise rejects with the `SDK_STATE` reason and the SDK makes no request. For more information, refer to [React Native SDK Initialization](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-initialization/manual-initialization/framework-initialization.md).

Call `fetchRecommendations()` on a `ReactMoEngageRecommendations` instance to retrieve the items of a recommendation. Pass the Recommendation ID of the recommendation you want to fetch items from, as defined on the MoEngage dashboard. You can also pass an anchor item ID and the catalog fields you want returned for each item. The method returns a promise.

```javascript React Native wrap theme={null}
import ReactMoEngageRecommendations, {
  RecommendationsFailureReason,
} from "react-native-moengage-recommendations";

const recommendations = new ReactMoEngageRecommendations("YOUR_WORKSPACE_ID");

recommendations
  .fetchRecommendations("YOUR_RECOMMENDATION_ID", "YOUR_ITEM_ID", ["title", "price"])
  .then((recommendedItems) => {
    if (recommendedItems.items.length === 0) {
      // No recommended items are available for this user. Show your empty state.
    } else {
      // Render the items.
    }
  })
  .catch((failure) => {
    switch (failure.failureReason) {
      case RecommendationsFailureReason.NETWORK_ERROR:
        // The device is offline. Retry when connectivity returns.
        break;
      default:
        // Show your error state.
        break;
    }
  });
```

> [!NOTE]
>
> Each `ReactMoEngageRecommendations` instance is scoped to the workspace you pass to its constructor. If your application runs multiple MoEngage workspaces, create one instance per workspace.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `recommendationId` | string | Yes | ID of the recommendation created on the MoEngage dashboard. Must not be blank. |
| `itemId` | string | No | ID of the item you want recommendations for, such as `shirts`. Ignored when blank. Defaults to an empty string. |
| `includedFields` | Array\<string> | No | Catalog attributes to return for each item in addition to the core fields, such as `size` and `color`. Ignored when empty, and duplicate values are dropped. Defaults to an empty array. |

### Handle the Result

The promise resolves with a `RecommendedItems` object. Its `items` property is a list of objects ranked best-first, where each object is one recommended item keyed by its catalog attribute names. An empty list is a successful result and means no recommended items are available for the user.

The SDK passes the keys and value types through from your [catalog](https://moengage.com/docs/user-guide/content/recommendations/getting-started/catalogs.md) unchanged, so keys are `snake_case`, such as `product_id` and `image_link`, and values differ between catalogs. Each value is typed `unknown`, so narrow its type before you use it:

```javascript React Native wrap theme={null}
const products = recommendedItems.items.map((item) => ({
  id: typeof item.product_id === "string" ? item.product_id : "",
  price: typeof item.price === "number" ? item.price : 0,
}));
```

To serve a default set of items when a recommendation returns nothing, configure [Fallback Items](https://moengage.com/docs/user-guide/content/recommendations/getting-started/fallback-items.md) on the recommendation. The SDK returns those items in the resolved result, in the same `items` list. Fallback Items apply to a successful fetch that has no recommended items. They do not apply when the fetch fails.

### Handle Failures

The promise rejects with a `RecommendationsFailure` object. Use its `failureReason` property to identify the failure. Its `message` property carries details for logging only and can be empty. The SDK writes nothing to the cache on failure and leaves any cached items untouched.

`failureReason` is a `RecommendationsFailureReason`, which combines the reasons specific to Recommendations with the reasons common to every MoEngage SDK request. A reason the SDK cannot classify maps to `UNKNOWN_ERROR`.

The following reasons are specific to Recommendations:

| Reason | Cause |
| - | - |
| `INVALID_REQUEST` | The Recommendation ID was blank, or the server rejected the request. |
| `PAYLOAD_TOO_LARGE` | The request exceeded the size limit the server accepts. |
| `RATE_LIMIT_EXCEEDED` | The request exceeded the fair use policy rate limit. |
| `INTERNAL_SERVER_ERROR` | The server failed to process the request. |

The following reasons are common to every MoEngage SDK request:

| Reason | Cause |
| - | - |
| `SDK_STATE` | The SDK is not initialized, or it is not in a state that allows the operation. |
| `FEATURE_DISABLED` | Recommendations is blocked from the dashboard, or disabled in the SDK configuration. |
| `NETWORK_ERROR` | A network error occurred while making the request. |
| `PARSE_ERROR` | The response could not be parsed. |
| `INVALID_PARAMETERS` | One or more parameters passed to the API are invalid. |
| `SERVER_ERROR` | The server failed to process the request. |
| `AUTHENTICATION_FAILED` | The request could not be authenticated. |
| `UNKNOWN_ERROR` | The failure could not be classified. |

The SDK does not retry a failed request. To try again, call `fetchRecommendations()` again. Because the SDK caches nothing on failure, the next call makes a fresh network request. Retry only for these reasons:

* `NETWORK_ERROR`
* `RATE_LIMIT_EXCEEDED`, after a delay
* `INTERNAL_SERVER_ERROR`
* `SERVER_ERROR`
* `UNKNOWN_ERROR`

## Caching

The SDK caches the items it fetches, so repeated calls for the same recommendation do not trigger a network request.

* The SDK scopes each cache entry to the combination of Recommendation ID, item ID, and included fields. Changing any of the three fetches a fresh list.
* Within the cache duration, `fetchRecommendations()` returns the cached items without a network call.
* After the cache duration elapses, the next call fetches the items from the server and refreshes the entry.
* The SDK caches an empty result in the same way, so an empty recommendation does not trigger a network call on every screen render.
* The SDK clears the cache when the user logs out, when the user identity changes, and when the SDK is disabled.

### Configure the Cache Duration

The SDK caches recommended items for 24 hours (86400 seconds). To cache items for longer, set the cache duration in the native initialization on each platform. The plugin does not expose this setting in JavaScript. Make the following changes in the native classes where you initialize the MoEngage framework.

```kotlin Android wrap theme={null}
import com.moengage.core.DataCenter
import com.moengage.core.MoEngage
import com.moengage.core.config.RecommendationConfig
import com.moengage.react.MoEInitializer

// Replace X with your data center number
val moEngage = MoEngage.Builder(this, "YOUR_WORKSPACE_ID", DataCenter.DATA_CENTER_X)
    .configureRecommendations(RecommendationConfig(recommendedItemsCacheDuration = 172800L))
MoEInitializer.initializeDefaultInstance(applicationContext, moEngage)
```

```swift iOS wrap theme={null}
// Replace 0x with your data center number
let sdkConfig = MoEngageSDKConfig(appId: "YOUR_WORKSPACE_ID", dataCenter: MoEngageDataCenter.data_center_0x)
sdkConfig.recommendationConfig = MoEngageRecommendationConfig(recommendedItemsCacheDuration: 172800)
MoEngageInitializer.sharedInstance().initializeDefaultSDKConfig(sdkConfig, andLaunchOptions: launchOptions)
```

> [!NOTE]
>
> The duration is in seconds. The minimum cache duration is 86400 seconds (24 hours). The SDK ignores a smaller value and uses 86400 seconds instead.

## FAQs

> [accordion] Does the SDK render the recommended items?
>
> No, the SDK returns the item data only. Your application parses the response and builds the user interface.

> [accordion] Does the SDK download the images referenced in the items?
>
> No, the SDK does not download or cache media. Use a standard image loading library for the image URLs in the response.

> [accordion] What happens if I call fetchRecommendations() before I initialize the SDK?
>
> The promise rejects with the `SDK_STATE` reason. Initialize the core SDK before you fetch recommendations. For more information, refer to [React Native SDK Initialization](https://moengage.com/docs/developer-guide/react-native-sdk/sdk-integration/react-native/sdk-initialization/manual-initialization/framework-initialization.md).

> [accordion] Can I force a fresh fetch before the cache expires?
>
> No, the SDK serves the cached items until the cache duration elapses. Configure a duration that matches how frequently your catalog changes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.