RecommendationService

This function returns a paginated list of recommended items based on a given request. The request can specify criteria such as configuration name, location, and page size to tailor the recommendations. It returns a RecommendationPages object that can be used to iterate through the list of items.

The ConfigName parameter determines how the recommendation engine ranks and returns items. For example, you can have configurations that optimize for views, likes, or purchases. For the ranking to be effective, you must ensure that you are logging the corresponding user interactions using LogImpressionEvent and LogActionEvent.

Supported ConfigName are:

• MaximizeTimespent: Optimizes recommendations to prioritize content that engages users for longer periods.
• MaximizeReactions: Optimizes recommendations to highlight content that generates the most user reactions, such as likes and favorites.
• MaximizePlays: Optimizes recommendations to prioritize content that generates the most Play actions. To use this configuration effectively, you must log both impressions and Play actions. It's recommended to filter for "quality" plays (for example play duration greater than 60 seconds) before logging to reduce noise and improve the system's learning accuracy.
• MaximizeEngagement: Optimizes recommendations through a balanced approach that considers multiple engagement signals, including quality views and reactions. This config is designed to highlight content that performs well across different engagement areas.
• PlayerSpecific: Returns public items created by the player specified in the request and sorted by the most recent creation time. To use this config, you must pass the UserId in the CustomContexts.
• RecentlyAdded: Returns items sorted by how recent they are, and displays the most recently added public content first.
• MaximizeJoins: Optimizes recommendations to prioritize game joins. This configuration is exclusive to Roblox Moments and focuses on maximizing interactions leading to a teleport. In contrast, MaximizePlays is purely optimizing Play actions.
• PlayerOwnedItems: Displays the user's own creations sorted by creation time. This config requires user authentication because it displays private items. This config is only available on the client.

This function can be called from both the server and the client. When called from the server, you must pass the UserId in the CustomContexts.

This function returns a single recommendation item by its ItemId. This is useful for getting the details of a specific item without having to fetch a whole list.

This function can be called only from the server.

This function logs a user action on a recommended item, such as a "like," "share," or "purchase." It requires the itemId of the item and a tracingId from the GenerateItemListAsync response to link the action to a specific recommendation context. Additional details about the action can be provided in the actionEventDetails dictionary.

Logging actions is essential for recommendation configurations that rank items based on user engagement such as number of likes or purchases.

This function can only be called from the client.

Note: Only LogActionEvent calls in production actually log actions. Calling this function in Studio doesn't have any effect; you can call it as many times as you want when testing.

This function logs an impression event, such as a user viewing a recommended item. It requires the itemId and a tracingId to associate the impression with the recommendation context. Details like view duration and position can be passed in the impressionEventDetails dictionary to provide more context for the recommendation engine.

Logging impressions, especially Duration, is critical for recommendation configurations that rank items based on view time.

This function can only be called from the client.

Note: Only LogImpressionEvent calls in production actually log impressions. Calling this function in Studio doesn't have any effect; you can call it as many times as you want when testing.

This function logs a user preference signal, such as follow, unfollow, mute, or unmute, directed at another user, a universe, or a custom content tag. It requires a preferenceType, a targetType, and a targetId whose format depends on the target type: the user key for User, the universe ID as a string for Universe, or the tag string for CustomTag. When the preference originates from a recommendation card served by GenerateItemListAsync, pass the card's tracingId and itemId to correlate the event with the recommendation context; otherwise pass empty strings for both.

Logging preferences helps the recommendation engine personalize future results across every recommendation surface, not just item feeds.

This function can only be called from the client.

Note: Only LogPreferenceEvent calls in production actually log preferences. Calling this function in Studio doesn't have any effect; you can call it as many times as you want when testing.

This function registers a new item to be included in recommendations. It requires a player object and a registerRecommendationItemsRequest dictionary containing details about the item, such as its content type, reference ID, and custom tags. It returns a dictionary with the ItemId and the ReferenceId of the newly registered item.

When selecting a ContentType, choose the type that best represents your item. Note that different content types are not ranked against each other directly. Instead, they are mixed into the final recommendation list based on a configured ratio. For example, a configuration might display one Static item for every ten items. If your experience only features a single type of content, ensure that all registered items share the same ContentType.

The ItemId is a unique ID returned by the RecommendationService. All functions in the RecommendationService use the ItemId as input and output.

The ReferenceId is a developer-provided identifier for an item. To make sure that this reference ID is unique, we recommend that you use a UUID. You can use this reference ID as a key to store rendering-specific metadata in a data store.

When you register an item, you should only provide information that is relevant for ranking and recommendations. All other data needed for rendering should be stored separately in, for example, a data store. This approach decouples the recommendation logic from the rendering process, and results in a system that is more modular and easier to maintain.

Attributes is a list of content attributes associated with the item. Each attribute in the list can contain the following fields:

• AssetId — The ID of an asset, such as an image or video.
• Text — A short text string, like a title.
• Description — A longer text description for the attribute.
• SeekStartTime / SeekEndTime — The start and end times for seeking within video content.
• TrimStartTime / TrimEndTime — The start and end times for trimming video content.

Common Error Codes:

• HTTP 403 (Forbidden) — This error can occur when you call RegisterItemAsync from Studio. Even if you run it as a server script in Studio, the request is not issued from a Roblox server. To resolve this, publish your experience and run it in the Roblox client.
• HTTP 400 (Bad Request) — This error indicates that a parameter is malformed. Common causes include a custom tag containing a comma or the Attributes table exceeding its size limit. If you encounter a 400 error and have a large Attributes table, try reducing its size. Remember to only include attributes that are relevant for ranking.

This function can only be called from the server.

This function removes an item from the recommendation system. It takes the itemId of the item to be deleted as a parameter.

This function can be called from both the server and the client, with the following limitations:

• When called from the server, it can only remove items registered under the same universeId.
• When called from the client, it can only remove items registered by the current player.

This function updates the attributes of an existing recommendation item. It takes an updateRecommendationItemRequest dictionary containing the itemId and the fields to be updated. Any fields not included in the request will remain unchanged.

Items with their RecommendationItemVisibility set to Private are not recommended to other users, but they can still be returned when a user requests their own creations by using the ConfigName of PlayerOwnedItems.

In Roblox Moments, moderated items are set to Private. While this prevents other users from seeing them, the item creator can still see these moderated items and check their moderation status in their My Moments tab.

This function can only be called from the server.