Skip to main content

Overview

The MoEngage iOS 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.
Prerequisites
  • Integrate MoEngage iOS SDK 11.3.0 or above, which includes the Recommendations module. For more information, refer to SDK Integration.
  • Initialize the SDK in didFinishLaunchingWithOptions. For more information, refer to SDK Initialization.
  • Enable Recommendations for your workspace and create a recommendation on the MoEngage dashboard. For more information, refer to Recommendations Overview.

Install the Module

To install MoEngageRecommendations through SPM, perform the following steps:
  1. Navigate to File > Add Package.
  2. Enter the repository URL https://github.com/moengage/apple-sdk.git.
  3. Select the master branch or your desired version.
  4. Click Add Package.
  5. Add the MoEngageRecommendations product to your app target.
Call fetchRecommendations(recommendationId:itemId:includedFields:workspaceId:) on MoEngageSDKRecommendations and attach onSuccess and onFailure callbacks to the returned MoEngageFetchRecommendationsTask. 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. For the full parameter list, refer to the API reference.
Pass workspaceId only when your application runs multiple MoEngage instances. includedFields is a Set<String>, which does not bridge to Objective-C. Objective-C callers use the fetchRecommendations overload, which accepts an array in place of the set.

Handle the Result

The onSuccess callback receives a MoEngageRecommendedItems object. Its items property is a list of maps, where each map 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 unchanged. To serve a default set of items when a recommendation returns nothing, configure Fallback Items on the recommendation.

Handle Failures

On failure, onFailure receives a MoEngageRequestFailure object. Use its reason property to identify the failure. Its message property carries details for logging only and can be empty, and its cause property carries the underlying NSError when the failure originated in the network layer. The SDK writes nothing to the cache on failure and leaves any cached items untouched. Read reason.code to identify the failure. For the full list of codes common to all MoEngage SDK requests, refer to the API reference. 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:
  • networkError
  • serverError
  • unknownError
Recommendations also defines its own failure codes on a subclass of MoEngageRequestFailureReason, exposed through a nested ModuleCode enum and a moduleCode property. For the list of these codes, refer to the API reference.

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 recommendationConfig property on the MoEngageSDKConfig object before you initialize the SDK. For more information, refer to SDK Initialization.
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

No, the SDK does not download or cache media. Use a standard image loading library for the image URLs in the response.
The SDK raises a fatal exception and the application crashes. From iOS SDK 11.0.0, this applies to every public MoEngage API in Debug, Release, and TestFlight builds. Initialize the SDK in didFinishLaunchingWithOptions before you fetch recommendations. For more information, refer to SDK Initialization.
No, the SDK serves the cached items until the cache duration elapses. Configure a duration that matches how frequently your catalog changes.