AWS Machine Learning Blog

Customize your recommendations by promoting specific items using business rules with Amazon Personalize

Today, we are excited to announce Promotions feature in Amazon Personalize that allows you to explicitly recommend specific items to your users based on rules that align with your business goals. For instance, you can have marketing partnerships that require you to promote certain brands, in-house content, or categories that you want to improve the visibility of. Promotions give you more control over recommended items. You can define business rules to identify promotional items and showcase them across your entire user base, without any extra cost. You also control the percentage of the promoted content in your recommendations. Amazon Personalize automatically finds the relevant items within the set of promotional items that meet your business rule and distributes them within each user’s recommendations.

Amazon Personalize enables you to improve customer engagement by powering personalized product and content recommendations in websites, applications, and targeted marketing campaigns. You can get started without any prior machine learning (ML) experience, using APIs to easily build sophisticated personalization capabilities in a few clicks. All your data is encrypted to be private and secure, and is only used to create recommendations for your users.

In this post, we demonstrate how to customize your recommendations with the new promotions feature for an ecommerce use case.

Solution overview

Different businesses can use promotions based on their individual goals for the type of content they want to increase engagement on. You can use promotions to have a percentage of your recommendations be of a particular type for any application regardless of the domain. For example, in ecommerce applications, you can use this feature to have 20% of recommended items be those marked as on sale, or from a certain brand, or category. For video-on-demand use cases, you can use this feature to fill 40% of a carousel with newly launched shows and movies that you want to highlight, or to promote live content. You can use promotions in domain dataset groups and custom dataset groups (User-Personalization and Similar-Items recipes).

Amazon Personalize makes configuring promotions simple: first, create a filter that selects the items you want promoted. You can use the Amazon Personalize console or API to create a filter with your logic using the Amazon Personalize DSL (domain-specific language). It only takes a few minutes. Then, when requesting recommendations, specify the promotion by specifying the filter, the percentage of the recommendations that should match that filter, and, if required, the dynamic filter parameters. The promoted items are randomly distributed in the recommendations, but any existing recommendations aren’t removed.

The following diagram shows how you can use promotions in recommendations in Amazon Personalize.

You define the items to promote in the catalog system, load them to the Amazon Personalize items dataset, and then get recommendations. Getting recommendations without specifying a promotion returns the most relevant items, and in this example, only one item from the promoted items. There is no guarantee of promoted items being returned. Getting recommendations with 50% promoted items returns half the items belonging to the promoted items.

This post walks you through the process of defining and applying promotions in your recommendations in Amazon Personalize to ensure the results from a campaign or recommender contain specific items that you want users to see. For this example, we create a retail recommender and promote items with CATEGORY_L2 as halloween, which corresponds to Halloween decorations. A code sample for this use case is available on GitHub.

Prerequisites

To use promotions, you first set up some Amazon Personalize resources on the Amazon Personalize console. Create your dataset group, load your data, and train a recommender. For full instructions, see Getting started.

  1. Create a dataset group.
  2. Create an Interactions dataset using the following schema: 
    {
    "type": "record",
    "name": "Interactions",
    "namespace": "com.amazonaws.personalize.schema",
    "fields": [
        {
            "name": "USER_ID",
            "type": "string"
        },
        {
            "name": "ITEM_ID",
            "type": "string"
        },
        {
            "name": "TIMESTAMP",
            "type": "long"
        },
        {
            "name": "EVENT_TYPE",
            "type": "string"
        }
    ],
    "version": "1.0"
}
  3. Import the interaction data to Amazon Personalize from Amazon Simple Storage Service (Amazon S3). For this example, we use the following data file. We generated the synthetic data based on the code in the Retail Demo Store project. Refer to the GitHub repo to learn more about the data and potential uses.
  4. Create an Items dataset using the following schema: 
    {
    "type": "record",
    "name": "Items",
    "namespace": "com.amazonaws.personalize.schema",
    "fields": [
        {
            "name": "ITEM_ID",
            "type": "string"
        },
        {
            "name": "PRICE",
            "type": "float"
        },
        {
            "name": "CATEGORY_L1",
            "type": ["string"],
            "categorical": true
        },
        {
            "name": "CATEGORY_L2",
            "type": ["string"],
            "categorical": true
        },
        {
            "name": "GENDER",
            "type": ["string"],
            "categorical": true
        }
    ],
    "version": "1.0"
}
  5. Import the item data to Amazon Personalize from Amazon S3. For this example, we use the following data file, based on the code in the Retail Demo Store project.For more information on formatting and importing your interactions and items data from Amazon S3, see Importing bulk records.
  6. Create a recommender. In this example, we create a “Recommended for you” recommender.

Create a filter for your promotions

Now that you have set up your Amazon Personalize resources, you can create a filter that selects the items for your promotion.

You can create a static filter where all variables are hardcoded at filter creation. For example, to add all items that have CATEGORY_L2 as halloween, use the following filter expression:

INCLUDE ItemID WHERE Items.CATEGORY_L2 IN ("halloween")

You can also create dynamic filters. Dynamic filters are customizable in real time when you request the recommendations. To create a dynamic filter, you define your filter expression criteria using a placeholder parameter instead of a fixed value. This allows you to choose the values to filter by applying a filter to a recommendation request, rather than when you create your expression. You provide a filter when you call the GetRecommendations or GetPersonalizedRanking API operations, or as a part of your input data when generating recommendations in batch mode through a batch inference job.

For example, to select all items in a category chosen when you make your inference call with a filter applied, use the following filter expression:

INCLUDE ItemID WHERE Items.CATEGORY_L2 IN ($CATEGORY)

You can use the preceding DSL to create a customizable filter on the Amazon Personalize console. Complete the following steps:

  1. On the Amazon Personalize console, on the Filters page, choose Create filter.
  2. For Filter name, enter the name for your filter (for this post, we enter category_filter).
  3. Select Build expression or add your expression manually to create your custom filter.
  4. Build the expression “Include ItemID WHERE Items.CATEGORY_L2 IN $CATEGORY”For Value, you enter a value of $ plus a parameter name that is similar to your property name and easy to remember (for this example, $CATEGORY).
  5. Optionally, to chain additional expressions with your filter, choose, the plus sign.
  6. To add additional filter expressions, choose Add expression.
  7. Choose Create filter.

You can also create filters via the createFilter API in Amazon Personalize. For more information, see CreateFilter.

Apply promotions to your recommendations

Applying a filter when getting recommendations is a good way to tailor your recommendations to specific criteria. However, using filters directly applies the filter to all the recommendations returned. When using promotions, you can select what percentage of the recommendations correspond to the promoted items, allowing you to mix and match personalized recommendations and the best items that match the promotion criteria for each user in the proportions that make sense for your business use case.

The following example code is a request body for the GetRecommendations API that gets recommendations for a user using the “Recommended for You” recommender:

{
    "recommenderArn" = "arn:aws:personalize:us-west-2:000000000000:recommender/test-recommender",
    userId = "1",
    numResults = 20
}

This request returns personalized recommendations for the specified user. Of the items in the catalog, these are the 20 most relevant items for the user.

We can do the same call and apply a filter to return only items that match the filter. The following example code is a request body for the GetRecommendations API that gets recommendations for a user using the “Recommended for You” recommender and applies a dynamic filter to only return relevant items that have CATEGORY_L2 as halloween:

{
    "recommenderArn" = "arn:aws:personalize:us-west-2:000000000000:recommender/test-recommender",
    userId = "1",
    numResults = 20,
    filterArn = "arn:aws:personalize:us-west-2:000000000000:filter/category_filter",
    filterValues={ "CATEGORY": "\"halloween\""}
}

This request returns personalized recommendations for the specified user that have CATEGORY_L2 as halloween. Out of the items in the catalog, these are the 20 most relevant items with CATEGORY_L2 as halloween for the user.

You can use promotions if you want a certain percentage of items to be of an attribute you want to promote, and the rest to be items that are the most relevant for this user out of all items in the catalog. We can do the same call and apply a promotion. The following example code is a request body for the GetRecommendations API that gets recommendations for a user using the “Recommended for You” recommender and applies a promotion to include a certain percentage of relevant items that have CATEGORY_L2 as halloween:

{
    recommenderArn = "arn:aws:personalize:us-west-2:000000000000:recommender/test-recommender",
    userId = "1",
    numResults = 20,
    promotions = [{
        "name" : "halloween_promotion",
        "percentPromotedItems" : 20,
        "filterArn": "arn:aws:personalize:us-west-2:000000000000:filter/category_filter",
        "filterValues": {
            "CATEGORY" : "\"halloween\""
        }
    }]
}

This request returns 20% of recommendations that match the filter specified in the promotion: items with CATEGORY_L2 as halloween; and 80% personalized recommendations for the specified user that are the most relevant items for the user out of the items in the catalog.

You can use a filter combined with promotions. The filter in the top-level parameter block applies only to the non-promoted items.

The filter to select the promoted items is specified in the promotions parameter block. The following example code is a request body for the GetRecommendations API that gets recommendations for a user using the “Recommended for You” recommender and uses the dynamic filter we have been using twice. The first filter applies to non-promoted items, selecting items with CATEGORY_L2 as decorative, and the second filter applies to the promotion, promoting items with CATEGORY_L2 as halloween:

{
    recommenderArn = "arn:aws:personalize:us-west-2:000000000000:recommender/test-recommender",
    userId = "1",
    numResults = 20,
    "filterArn": "arn:aws:personalize:us-west-2:000000000000:filter/category_filter",
    "filterValues": {
        "CATEGORY" : "\"decorative\""
    }
    promotions = [{
        "name" : "halloween_promotion",
        "percentPromotedItems" : 20,
        "filterArn": "arn:aws:personalize:us-west-2:000000000000:filter/category_filter",
        "filterValues": {
            "CATEGORY" : "\"halloween\""
        }
    }]
}

This request returns 20% of recommendations that match the filter specified in the promotion: items with CATEGORY_L2 as halloween. The remaining 80% of recommended items are personalized recommendations for the specified user with CATEGORY_L2 as decorative. These are the most relevant items for the user out of the items in the catalog with CATEGORY_L2 as decorative.

Clean up

Make sure you clean up any unused resources you created in your account while following the steps outlined in this post. You can delete filters, recommenders, datasets, and dataset groups via the AWS Management Console or using the Python SDK.

Summary

Adding promotions  in Amazon Personalize allows you to customize your recommendations for each user by including items that you want to explicitly increase visibility and engagement on. Promotions also allow you to specify what percentage of the recommended items should be promoted items, which tailors the recommendations to meet your business objectives at no extra cost. You can use promotions for recommendations using the User-Personalization and Similar-Items recipes, as well as use case optimized recommenders.

For more information about Amazon Personalize, see What Is Amazon Personalize?

About the authors

Anna Gruebler is a Specialist Solutions Architect at AWS focusing on in Artificial Intelligence. She has more than 10 years experience helping customers develop and deploy machine learning applications. Her passion is taking new technologies and putting them in the hands of everyone, and solving difficult problems leveraging the advantages of using AI in the cloud.

Alex Burkleaux is a Solutions Architect at AWS. She focuses on helping customers apply machine learning and data analytics to solve problems in the media and entertainment industry.  In her free time, she enjoys spending time with family and volunteering as a ski patroller at her local ski hill.

Liam Morrison is a Solutions Architect Manager at AWS. He leads a team focused on Marketing Intelligence services. He has spent the last 5 years focused on practical applications of Machine Learning in Media & Entertainment, helping customers implement personalization, natural language processing, computer vision and more.