Promoting items in real-time recommendations
With all domain use cases and some custom recipes, you can specify a promotion when you get real-time recommendations.
A promotion defines additional business rules that apply to a configurable subset of recommended items. For example, you might have a streaming app and want to promote your own shows and movies but also recommend relevant titles. You could use a promotion to specify that a certain percentage of recommended items must come from the category in-house. The remaining recommended items would continue to be relevant recommendations based on your recipe and any request filters.
To apply a promotion, you specify the following in your recommendation request:
-
The percentage of recommended items to apply the promotion filter to.
-
A filter that specifies the promotion criteria. For more information, see Promotion filters.
In the recommendation response, promoted items are positioned randomly relative to other recommended items, but in sorted order relative to other promoted items. Depending on your recipe, recommended items that aren't part of a promotion are sorted by relevance to the user, popularity, or similarity. If there aren't enough items that meet the promotion criteria, the result will contain as many promoted items as possible.
You can apply a promotion to recommendations with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs.
Topics
Use cases and recipes that support promotions
All use cases support promotions. The following custom recipes support promotions:
-
User-Personalization-v2 and User-Personalization recipes
-
Similar-Items and SIMSrecipes
-
Trending-Now and Popularity-Count recipes
Promotion filters
When you apply a promotion to a recommendation request, you choose a filter that specifies the promotion criteria. You can use an existing filter or create a new one. You create and manage filters for promotions as you would other filters in Amazon Personalize. For information about creating and managing filters, see Filtering results.
The only difference between a promotion filter and a filter that you choose outside the promotion (the request filter) is how Amazon Personalize applies them. A promotion filter applies to only promoted items, while a request filter applies to only the remaining recommended items. If you specify a request filter and promotion filter, and want to apply both filters to promoted items, your promotion filter's expression must include both expressions. The way you combine two expressions depends on the datasets you use. For more information on filter expressions, their rules, and how to create them, see Filter expressions.
Filter expression examples
The following expression includes only items from the category "in-house". You might use this expression if you want to promote your own content in your recommendations.
INCLUDE ItemID WHERE Items.OWNER IN ("in-house")
The following expression includes only items created more recently than a timestamp you specify. You might use this expression to promote new items in recommendations.
INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE
The following expression shows how you might apply a request filter to promoted items. It includes only available clothing items as promoted items.
In this scenario, the Items.AVAILABLE IN ("True")
would also be used in the request filter expression, so that all recommendations are for items that are available.
INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") AND Items.AVAILABLE IN ("True")
For a more complete list of filter examples, see Filter expression examples.
Promoting new items
If you use the User-Personalization-v2 recipe, Amazon Personalize recommends the most relevant items to users and more frequently recommends existing items with interactions data. To make sure recommendations include some new items, you can apply a promotion to recommendation requests that includes items based on creation timestamp.
If you don't already use a promotion, your filter expression can promote items created after a certain date:
INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE
If you already use a promotion, you create an expression that chains both the promotion and the new item condition statements:
INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") OR Items.CREATION_TIMESTAMP > $DATE
Promoting items (console)
To promote certain items in recommendations with the Amazon Personalize console, create a filter, and then provide the promotion details in the recommendation request. For information on other fields, see Getting item recommendations (console).
To promote items in recommendations
-
Open the Amazon Personalize console at https://console.aws.amazon.com/personalize/home
and sign into your account. -
Choose the dataset group that contains the campaign or recommender you are using.
-
If you haven't already, create a filter that specifies the promotion criteria. You create filters for promotions the same way that you create request filters. For information on creating and managing filters, see Filtering results.
-
In the navigation pane, choose Recommenders or Campaigns.
-
Choose the target campaign or recommender.
-
For campaigns, under Test campaign results, enter your recommendation request details based on the recipe you used. For recommenders, choose Test recommender and enter your recommendation request details.
-
Optionally choose a filter for the request. This filter applies to only non-promoted items. For information on creating and managing filters, see Filtering results.
-
If you use contextual metadata, provide data for each context. For each context, for the Key enter the metadata field. For the Value, enter the context data. For more information, see Increasing recommendation relevance with contextual metadata.
-
For Promotion specify the following:
-
Percent promoted items: Enter the percentage of recommended items to apply the promotion to.
-
Filter: Choose a filter that specifies the promotion criteria. This filter applies to the promoted items instead of any request filter that you may have specified in step 7.
-
Filter parameter: If your promotion uses a filter with placeholder parameters, for each parameter, enter the value to set the filter criteria. To use multiple values for one parameter, separate each value with a comma.
-
-
Choose Get recommendations. A table containing the user’s top 25 recommended items displays. The Promoted item column indicates whether the item was included because of your promotion. Promoted items are positioned randomly relative to other recommended items, but in sorted order relative to other promoted items. Depending on your use case or recipe, recommended items that aren't part of a promotion are sorted by relevance to the user, popularity, or similarity. If there aren't enough items that meet the promotion criteria, the result will contain as many promoted items as possible.
Promoting items (AWS CLI)
The following code shows how to promote items in recommendations with the AWS CLI and a custom campaign. To
promote items with a recommender, replace the campaign-arn
parameter with a recommender-arn
and specify the Amazon Resource Name (ARN) for the recommender.
For the promotion fields, specify the following:
-
name: Give the promotion a name. The recommendation response uses the name to identify promoted items.
-
percent-promoted-items: The percentage of recommended items to apply the promotion to. In this example, 50% of items will be promoted items.
-
filterArn: Specify the Amazon Resource Name (ARN) of the filter that defines the promotion criteria. For more information, see Promotion filters.
-
parameter names and values: If your filter expression has any parameters, provide the parameter names (case sensitive) and the values. For example, if your filter expression has a
$GENRE
parameter, provide GENRE as the key, and a genre or genres, such as Comedy, as the value. Separate multiple values with a comma. When you use the AWS CLI, for each value you must use the/
character to escape both quotes and the/
character. The following code example shows how to format the values.
The code shows how to use both a request filter and a promotion filter. A promotion filter applies to only promoted items, while a request filter applies to only the remaining recommended items. For more information, see Promotion filters.
For information about additional fields, see Getting item recommendations (AWS SDKs) and Getting a personalized ranking using contextual metadata.
aws personalize-runtime get-recommendations \ --campaign-arn
CampaignArn
\ --user-id1
\ --num-results10
\ --filter-arnRequestFilterArn
\ --filter-values '{ "RequestFilterParameterName
": "\"value
\"", "RequestFilterParameterName
": "\"value1
\",\"value2
\",\"value3
\"" }' \ --promotions "[{ \"name\": \"promotionName
\", \"percentPromotedItems\":50
, \"filterArn\": \"PromotionFilterARN
\", \"filterValues\": {\"PromotionParameterName
\":\"\\\"value1
,value2
\\\"\"} }]"
A list of recommended items displays. Promoted items are positioned randomly relative to other recommended items, but in sorted order relative to other promoted items. Depending on your recipe, recommended items that aren't part of a promotion are sorted by relevance to the user, popularity, or similarity. If there aren't enough items that meet the promotion criteria, the result will contain as many promoted items as possible.
{ "itemList": [ { "itemId1": "123", "score": .0117211, "promotionName": "promotionName" }, { "itemId2": "456", "score": .0077976 }, { "itemId3": "789", "score": .0067171 }, ..... ]
Promoting items (AWS SDKs)
The following code shows how to promote items in recommendations with the SDK for Python (Boto3) and the SDK for Java 2.x and a custom
campaign. To
promote items with a recommender, replace the campaignArn
parameter with recommenderArn
and specify the Amazon Resource Name (ARN) for the recommender.
For the promotion fields, specify the following:
-
name: Specify the name of the promotion. The recommendation response includes the name to identify promoted items.
-
percentPromotedItems: The percentage of recommended items to apply the promotion to.
-
promotionFilterARN: The Amazon Resource Name (ARN) of the filter that defines the promotion criteria. For more information, see Promotion filters.
-
Any parameter names and values: If your filter expression has any parameters, for each parameter in your filter expression, provide the parameter name (case sensitive) and the values. For example, if your filter expression has a
$GENRE
parameter, provide"GENRE"
as the key, and a genre or genres, such as "\"Comedy"\", as the value. Separate multiple values with a comma. For example,"\"comedy\",\"drama\",\"horror"\"
.
The following code shows how to use both a request filter and a promotion filter. A promotion filter applies to only promoted items, while a request filter applies to only the remaining recommended items. For more information, see Promotion filters.
For information about additional fields, see Getting item recommendations (AWS SDKs) and Getting a personalized ranking using contextual metadata.
A list of recommended items displays. Promoted items are positioned randomly relative to other recommended items, but in sorted order relative to other promoted items. Depending on your recipe, recommended items that aren't part of a promotion are sorted by relevance to the user, popularity, or similarity. If there aren't enough items that meet the promotion criteria, the result will contain as many promoted items as possible.
{ "itemList": [ { "itemId1": "123", "score": .0117211, "promotionName": "promotionName" }, { "itemId2": "456", "score": .0077976 }, { "itemId3": "789", "score": .0067171 }, ..... ]