# RecommendationService

Roblox Engine API class from Roblox Studio 0.744.0.7441077 (version-7aaa6838d36c4448).

- Inherits from, nearest first: [Instance](https://rapi.sleaze.dev/classes/Instance.md), [Object](https://rapi.sleaze.dev/classes/Object.md)
- Tags: Not creatable, Service
- Memory category: Instances
- HTML page: https://rapi.sleaze.dev/classes/RecommendationService/
- Roblox documentation: https://create.roblox.com/docs/reference/engine/classes/RecommendationService

A service that provides an interface for you to manage and display personalized content recommendations.

## Methods

### GenerateItemListAsync

```luau
RecommendationService:GenerateItemListAsync(generateRecommendationItemListRequest: { [string]: any }): RecommendationPages
```

- Tags: Yields, Capabilities: Basic

Returns a paginated list of personalized recommendation items for the specified request configuration.

Parameters:

- `generateRecommendationItemListRequest`: A dictionary containing the following fields:

- `ConfigName` — A unique ID for the specific configuration. This determines how the candidates are ranked.
- `LocationId` — A developer-defined string that specifies the location where the recommendation is used, such as `"For_you"` or `"Lobby"`. This parameter will not affect the items returned, and it can help you track the performance of multiple recommendation features within your experience. Recommendation metrics for each individual location will be displayed in the Creator Hub. `LocationId`**must** be a string and cannot be `"Other"` or `"other"` as these values are reserved by the Creator Hub.
- `PageSize` — The number of items returned for each page.
- `BoostCustomTags` — A list of string tags. Any item with this tag will be boosted in ranking. Supports boosting one tag.
- `CustomContexts` — A table of key-value pairs used to pass in additional context data for ranking. For example, `UserId` for a Server script.

Returns: A [`RecommendationPages`](https://rapi.sleaze.dev/classes/RecommendationPages.md) object containing the paginated list of recommended items for the given request configuration.

### GetRecommendationItemAsync

```luau
RecommendationService:GetRecommendationItemAsync(itemId: string): { [string]: any }
```

- Tags: Yields, Capabilities: Basic

Retrieves a single registered recommendation item by its `ItemId`.

Parameters:

- `itemId`: The ID of the item to retrieve.

Returns: A dictionary representing the recommendation item with the following fields:

- `ItemId` — The unique ID for the item.
- `ReferenceId` — The developer-provided ID for the item.
- `TracingId` — An ID for tracking recommendation sessions. This will be empty when fetching a single item directly.
- `Creator` — A table containing the `CreatorId` and `CreatorType`.
- [`Attributes`](https://rapi.sleaze.dev/classes/Instance.md) — A list of content attributes associated with the item.
- `CustomTags` — A list of custom string tags.
- `Visibility` — An enum of type `RecommendationItemVisibility`.

### LogActionEvent

```luau
RecommendationService:LogActionEvent(actionType: Enum.RecommendationActionType, itemId: string, tracingId: string, actionEventDetails: { [string]: any }? = nil)
```

- Tags: Capabilities: Basic

Logs a user action, such as a reaction or play, taken on a recommended item.

Parameters:

- `actionType`: The enum for the type of action.
- `itemId`: The item ID returned from registration and [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md).
- `tracingId`: The tracing ID returned from the [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md) response. Each item has a `TracingId`.
- `actionEventDetails`: A dictionary containing the following fields:

- `Weight` — A number representing the weight of the action. Default is 1.
- `DestinationPlaceId` — The ID of the place the user was sent to after the action. Used for `Play`.
- `CommentText` — Any text associated with the action, such as a comment. Used for `Comment`.
- `ReactionType` — A string describing the type of reaction, for example, "like" or "dislike". Used for `AddReaction` or `RemoveReaction`.

### LogImpressionEvent

```luau
RecommendationService:LogImpressionEvent(impressionType: Enum.RecommendationImpressionType, itemId: string, tracingId: string, impressionEventDetails: { [string]: any }? = nil)
```

- Tags: Capabilities: Basic

Logs an impression event, such as a user viewing a recommended item.

Parameters:

- `impressionType`: The enum for the type of the impression.
- `itemId`: The item ID returned from registration and [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md).
- `tracingId`: The tracing ID returned from the [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md) response. Each item has a `TracingId`.
- `impressionEventDetails`: A dictionary containing the following fields:

- `Duration` — The duration of the impression in seconds.
- `Weight` — A number representing the weight of the impression. Default is 1.
- `ItemPosition` — The position of the item in the recommendation list.
- `DepartureIntent` — The `RecommendationDepartureIntent` indicating the user's intent when leaving a view. For example, `Positive` if the view is considered good.

### LogPreferenceEvent

```luau
RecommendationService:LogPreferenceEvent(preferenceType: Enum.RecommendationPreferenceType, targetType: Enum.RecommendationPreferenceTargetType, targetId: string, tracingId: string? = "", itemId: string? = "")
```

- Tags: Capabilities: Basic

Logs a user preference signal, such as follow or mute, toward a user, universe, or custom content tag.

Parameters:

- `preferenceType`: The enum for the type of preference.
- `targetType`: The enum for the type of target.
- `targetId`: The identifier of the preference target. The format depends on `targetType`.
- `tracingId`: The tracing ID returned from the [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md) response. Pass an empty string if the preference originates outside a recommendation feed.
- `itemId`: The item ID returned from the [`GenerateItemListAsync`](https://rapi.sleaze.dev/classes/RecommendationService.md) response. Pass an empty string if the preference originates outside a recommendation feed.

### RegisterItemAsync

```luau
RecommendationService:RegisterItemAsync(player: Player, registerRecommendationItemsRequest: { [string]: any }): { [string]: any }
```

- Tags: Yields, Capabilities: Basic

Registers a new item on the server so it can be included in recommendations, returning the generated `ItemId` and `ReferenceId`.

Parameters:

- `player`: The player who created the item.
- `registerRecommendationItemsRequest`: A dictionary containing the following fields:

- `ContentType` — The `RecommendationItemContentType` specifying the type of content. Type is defined in a generic way. For example, you can use `Static` for images, `Dynamic` for videos, and `Interactive` for 3D models that support interaction.
- `ReferenceId` — The developer-defined string that uniquely identifies the item.
- `Duration` — The duration of the content in seconds.
- [`Attributes`](https://rapi.sleaze.dev/classes/Instance.md) — The table of attributes for the item, such as `AssetId` or `Description`.
- `CustomTags` — The list of string tags for filtering and boosting. Individual custom tags can't contain commas.
- `Visibility` — The `RecommendationItemVisibility` enum that controls the item's visibility, such as `Public` or `Private`.

Returns: A table with only two fields: `ItemId` and `ReferenceId`.

### RemoveItemAsync

```luau
RecommendationService:RemoveItemAsync(itemId: string)
```

- Tags: Yields, Capabilities: Basic

Removes a registered item from the recommendation system by its `ItemId`.

Parameters:

- `itemId`: The itemId to remove.

### UpdateItemAsync

```luau
RecommendationService:UpdateItemAsync(updateRecommendationItemRequest: { [string]: any })
```

- Tags: Yields, Capabilities: Basic

Updates the mutable attributes of an existing recommendation item.

Parameters:

- `updateRecommendationItemRequest`: A dictionary containing the following fields:

- `ItemId` — The ID of the item to update.
- `ReferenceId` — The new developer-defined string to identify the item.
- `Creator` — The new creator for the item. Creator is a table containing two fields: `CreatorId: number` and `CreatorType: Enum.CreatorType`.
- `Duration` — The new duration for the content in seconds.
- `Visibility` — The new visibility setting for the item.
- [`Attributes`](https://rapi.sleaze.dev/classes/Instance.md) — The new table of attributes for the item.
- `CustomTags` — The new list of string tags. Individual custom tags can't contain commas.

## Inherited members

- From [Instance](https://rapi.sleaze.dev/classes/Instance.md): `Archivable`, `archivable`, `Attributes`, `AttributesReplicate`, `AttributesSerialize`, `HistoryId`, `Name`, `Parent`, `PredictionMode`, `PropertyStatusStudio`, `RobloxLocked`, `SerializedOverrides`, `SourceAssetId`, `Tags`, `UniqueId`, `numExpectedDirectChildren`, `DataCost`, `Capabilities`, `DefinesCapabilities`, `IsInSandbox`, `Sandboxed`, `AddTag`, `ClearAllChildren`, `Clone`, `Destroy`, `FindFirstAncestor`, `FindFirstAncestorOfClass`, `FindFirstAncestorWhichIsA`, `FindFirstChild`, `FindFirstChildOfClass`, `FindFirstChildWhichIsA`, `FindFirstDescendant`, `GetActor`, `GetAttribute`, `GetAttributeChangedSignal`, `GetAttributes`, `GetChildren`, `GetDebugId`, `GetDescendants`, `GetFullName`, `GetStyled`, `GetStyledPropertyChangedSignal`, `GetTags`, `HasTag`, `IsAncestorOf`, `IsDescendantOf`, `IsPropertyModified`, `QueryDescendants`, `RemoveTag`, `ResetPropertyToDefault`, `SetAttribute`, `WaitForChild`, `Remove`, `children`, `clone`, `destroy`, `findFirstChild`, `getChildren`, `isDescendantOf`, `remove`, `AncestryChanged`, `AttributeChanged`, `ChildAdded`, `ChildRemoved`, `DescendantAdded`, `DescendantRemoving`, `Destroying`, `StyledPropertiesChanged`, `childAdded`
- From [Object](https://rapi.sleaze.dev/classes/Object.md): `ClassName`, `className`, `GetPropertyChangedSignal`, `IsA`, `isA`, `Changed`