Automated Deployment - Predictive User Engagement

Automated Deployment

Before you launch the automated deployment, please review the architecture and considerations discussed in this guide. Follow the step-by-step instructions in this section to configure and deploy Predictive User Engagement into your account.

Time to deploy: Approximately five minutes

Prerequisites

Before you deploy the solution, verify that meet the following prerequisites.

  • You must have an account with permissions to create resources for each service. You can manually add permissions for each service to your account, or you can use an account with administrative permissions.

  • You must have the AWS Command Line Interface (AWS CLI) installed. For instructions, see Installing the AWS CLI in the AWS CLI User Guide.

  • You must have the Jupyter Notebook App installed. For instructions, see Installation in the Jupyter/iPython Notebook Quick Start Guide.

What We'll Cover

The procedure for deploying this architecture and demonstrating its functionality consists of the following steps. For detailed instructions, follow the links for each step.

Step 1. Create an Amazon Pinpoint Project

  • Create an Amazon Pinpoint project to test the solution.

Step 2. Configure Amazon Personalize

  • Configure the sample Amazon Personalize resources and campaign.

Step 3. Launch the Stack

  • Launch the AWS CloudFormation template into your AWS account.

  • Enter values for required parameter: Stack Name, Personalize Campaign ARN, Pinpoint Project ID

Step 4. Create an Endpoint in the Amazon Pinpoint Project

  • Create an endpoint for testing the Amazon Pinpoint project.

Step 5. Validate the Endpoint

  • Verify that the endpoint is loaded correctly with the correct attributes.

Step 6. Test the Lambda Function

  • Execute the pue-get-recs Lambda function to retrieve recommendations and update the endpoint.

Step 7. Create a Segment That Filters on Recommended Items

  • Create Amazon Pinpoint segments from the Amazon Personalize recommendations.

Step 8. Create a Campaign Using the Recommendations Segment

  • Create and send a campaign using the Amazon Personalize recommendations.

Step 1. Create an Amazon Pinpoint Project

Use this procedure to create a project in Amazon Pinpoint.

  1. Navigate to the Amazon Pinpoint console.

  2. On the All projects page, choose Create a project.

  3. For Project name, enter pueDemo, and then choose Create.

  4. On the Configure features page, under SMS and voice, choose Configure.

  5. Select Enable the SMS channel for this project.

  6. Select Save changes.

  7. In the navigation pane, select Settings, General settings.

  8. Copy the Project ID. You will need it when you launch the stack.

Step 2. Configure Amazon Personalize

Use this procedure to create sample data, load it into Amazon Personalize datasets, and create campaigns and training.

  1. In a terminal window, run the following command to clone the sample data and Jupyter Notebooks GitHub repository.

    git clone https://github.com/markproy/personalize-car-search.git
  2. Navigate to the directory that contains the sample data and run the following command.

    jupyter notebook

    The Jupyter interface opens in a browser window.

  3. In the Jupyter notebook interface, open the 01_generate_data.ipynb file.

  4. In the Cell dropdown menu, select Run All to run the file.

  5. Open the 02_make_dataset_group.ipynb file.

  6. In the Cell dropdown menu, select Run All to run the file.

  7. Open the 03_make_campaigns.ipynb file.

  8. In the Cell dropdown menu, select Run All to run the file.

  9. Open the 04_use_the_campaign.ipynb file.

  10. In the Cell dropdown menu, select Run All to run the file.

  11. Navigate to the Amazon Personalize console.

  12. In the navigation pane, select Dataset groups and verify that Amazon Personalize contains the car-dg dataset group.

  13. Select the car-dg dataset group.

  14. In the navigation pane, choose Campaigns and verify that the car-hrnn campaign shows with an Active status.

  15. Select the car-hrnn campaign and copy the Campaign ARN. You will need it when you launch the stack.

Step 3. Launch the Stack

This automated AWS CloudFormation template deploys Predictive User Engagement in the AWS Cloud. Please make sure that you’ve reviewed the architecture, prerequisites, and considerations before launching the stack.

Note

You are responsible for the cost of the AWS services used while running this solution. See the Cost section for more details. For full details, see the pricing webpage for each AWS service you will be using in this solution.

  1. Sign in to the AWS Management Console and click the button below to launch the predictive-user-engagement AWS CloudFormation template.

    
                                Predictive User Engagement launch button

    You can also download the template as a starting point for your own implementation.

  2. The template is launched in the US East (N. Virginia) Region by default. To launch this solution in a different AWS Region, use the region selector in the console navigation bar.

    Note

    This solution uses Amazon Pinpoint and Amazon Personalize, which are currently available in specific AWS Regions only. Therefore, you must launch this solution in an AWS Region where these services are available. For the most current service availability by region, see AWS service offerings by region.

  3. On the Create stack page, verify that the correct template URL shows in the Amazon S3 URL text box and choose Next.

  4. On the Specify stack details page, assign a name to your solution stack.

  5. Under Parameters, review the parameters for the template, and modify them as necessary. This solution uses the following default values.

    Parameter Default Description
    Personalize Campaign ARN <Requires input>

    The car-hrnn campaign ARN of the Amazon Personalize campaign you created in Step 2

    Pinpoint Project Id <Requires input> The project ID of the Amazon Pinpoint project you created in Step 1
  6. Choose Next.

  7. On the Configure stack options page, choose Next.

  8. On the Review page, review and confirm the settings. Be sure to check the box acknowledging that the template will create AWS Identity and Access Management (IAM) resources.

  9. Choose Create stack to deploy the stack.

    You can view the status of the stack in the AWS CloudFormation console in the Status column. You should see a status of CREATE_COMPLETE in approximately five minutes.

Step 4. Create an Endpoint in the Amazon Pinpoint Project

Create an endpoint that you will use to test the SMS channel and store the recommendations from Amazon Personalize.

Note

For this demo, you will use the AWS Command Line Interface (AWS CLI) to create the endpoint. If necessary, install the AWS CLI.

Run the following command. Replace <project-id> with the project ID you copied in the previous step. Replace <mobile-number> with a U.S. mobile number using the using the E.164 format (+1XXX5550100).

AWS pinpoint update-endpoint --application-id "<project-id>" --endpoint-id "12456" --endpoint-request "Address='<mobile-number>',ChannelType='SMS',User={UserAttributes={recommended_items=['none']},UserId='12456'}"

For this demo, you will use 12456 for the UserId. This user ID matches the ID that is used in the Amazon Personalize dataset.

Step 5. Validate the Endpoint

Use this procedure to create a segment for the endpoint you created in the previous step.

  1. Navigate to the Amazon Pinpoint console.

  2. On the All projects page, choose the pueDemo project.

  3. In the navigation pane, select Segments. Then, select Create a segment.

  4. For Name, enter pueNoRecommendations.

  5. For Add a filter, choose Filter by user.

  6. For Choose a user attribute, select recommended-items. Then, set the value to none.

  7. Choose Create Segment.

    You might receive a Segment might include multiple channels message. If so, select I understand.

  8. In the navigation pane, select Segments and choose the segment you just created.

  9. Under Segment details, verify that Total endpoints shows 1 endpoint.

  10. In the navigation pane, select Campaigns. Then, select Create a campaign.

  11. For Campaign name, enter SMS to users with no recommendations.

  12. Select Next.

  13. On the Choose a segment page, select the pueNoRecommendations segment, choose Next.

  14. On the Create your message page, enter Sample pueNoRecommendations segment SMS test message. Then, select Next.

  15. On the Choose when to send the campaign page, select Next.

  16. Choose Launch Campaign.

  17. Verify that you received the test message at the mobile number you specified.

Step 6. Test the Lambda Function

Use this procedure to test the Lambda function you created in step 5.

  1. Navigate to the AWS Lambda console.

  2. In the navigation pane, select Functions.

  3. Select the pue-get-recs-test function.

  4. Select Test.

    The Configure test event window opens.

  5. For Event name, enter pue-get-recs-test. Then, select Create.

  6. Choose Test.

  7. Navigate to the Amazon Pinpoint console, and open the pueDemo project.

  8. In the navigation pane select Segments. Then, select the pueNoRecommendations segment.

  9. On the Segment details page, the Total endpoints should show 0 endpoints.

The Lambda function retrieved the recommendations from Amazon Personalize and updated the recommendations field of the endpoint. This segment has a filter (recommended_items attribute = 'none'). When the Lambda function updated the endpoint, the recommended_items attribute value was updated and no longer has a none value. The endpoint was removed from the segment.

To view the recommendations value of the endpoint, you can create a new segment and choose the user attributes filter of recommended_items. Then, you can look at the values in the values dropdown list.

Step 7. Create a Segment That Filters on Recommended Items

Now that the Amazon Personalize user recommendations are stored in Amazon Pinpoint as user attributes, you will create Amazon Pinpoint segments that automatically update based on which users have recommendations.

  1. Navigate to the Amazon Pinpoint console.

  2. On the All Projects page, choose the pueDemo project.

  3. In the navigation pane, select Segments. Then, select Create a segment.

  4. For Name, enter pueItemRecommendations.

  5. For Add a filter, choose Filter by user.

  6. For Choose a user attribute, select recommended-items. Then, set the value to any item ID in the dropdown list.

  7. Choose Create Segment.

    You might receive a Segment might include multiple channels message. If so, select I understand.

  8. In the navigation pane, select Segments and choose the pueNoRecommendations segment.

  9. Under Segment details, verify that Total endpoints shows 0 endpoint.

    When the Lambda function retrieved the Amazon Personalize recommendations, the endpoint's recommended_items attribute was updated to include a list of item IDs. Because the filter on this segment is recommended_items attribute = 'none' there will be no endpoints in the segment.

  10. Optional: You can do Step 3 again and verify that the pueNoRecommendations segment shows one endpoint and that the pueItemRecommendations segment shows no endpoints.

  11. To populate the endpoint recommended_items attribute with recommendations from Amazon Personalize, invoke the pue-get-recs Lambda function again.

  12. Verify that the pueNoRecommendations segment shows no endpoints and that the pueItemRecommendations segment shows one endpoint.

Step 8. Create a Campaign Using the Recommendations Segment

Use this procedure to create an Amazon Pinpoint campaign that uses the pueItemRecommendations segment.

  1. In the navigation pane, select Campaigns. Then, select Create a campaign.

  2. For Campaign name, enter SMS to users with item recommendations.

  3. Select Next.

  4. On the Choose a segment page, select the pueItemRecommendations segment, choose Next.

  5. On the Create your message page, enter Sample item recommendations segment SMS test message. Then, select Next.

  6. On the Choose when to send the campaign page, select Next.

  7. Choose Launch Campaign.

  8. Verify that you received the test message at the mobile number you specified in Step 4.

You can set this campaign to execute on a recurring basis. You can also set the campaign to run the pue-get-recs Lambda function automatically when it executes, updating this list of endpoints that will receive the message based on the most current recommendations data from Amazon Personalize. For more information, see Customizing Segments with AWS Lambda.