Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating a campaign

For real-time recommendations with custom resources, after you complete Creating a solution version, you are ready to deploy your solution version with a campaign.

A campaign deploys a solution version (trained model) with a provisioned transaction capacity for generating real-time recommendations. After you create a campaign, you use the GetRecommendations or GetPersonalizedRanking API operations to get recommendations. If you are getting batch recommendations, you don't need to create a campaign. For more information see Batch recommendations and user segments (custom resources).

You create a campaign with the Amazon Personalize console, Amazon Command Line Interface (Amazon CLI), or Amazon SDKs.

Minimum provisioned transactions per second and auto-scaling

When you create an Amazon Personalize campaign, you specify a provisioned transaction capacity for generating recommendations. A transaction is a single GetRecommendations or GetPersonalizedRanking call. Transactions per second (TPS) is the throughput and unit of billing for Amazon Personalize. The minimum provisioned TPS (minProvisionedTPS) specifies the baseline throughput provisioned by Amazon Personalize, and thus, the minimum billing charge.

If your TPS increases beyond minProvisionedTPS, Amazon Personalize auto-scales the provisioned capacity up and down, but never below minProvisionedTPS. There's a short time delay while the capacity is increased that might cause loss of transactions.

The actual TPS used is calculated as the average requests/second within a 5-minute window. You pay for maximum of the minimum provisioned TPS or the actual TPS. We recommend starting with a low minProvisionedTPS, track your usage using Amazon CloudWatch metrics, and then increase the minProvisionedTPS as necessary.

Creating a campaign (console)

After your solution version status is Active you are ready to deploy it with an Amazon Personalize campaign.

Creating a campaign (Amazon CLI)

After your solution version status is Active, you are ready to deploy it with an Amazon Personalize campaign. Use the following create-campaign Amazon CLI command to create a campaign that deploys a solution version trained using the User-Personalization recipe. Give the campaign a name and specify the solution version ARN (Amazon Resource Name). Optionally change the minProvisionedTPS if your use case requires a higher provisioned capacity. The minimum value is 1.

The campaign-config parameters are specific to the recipe that you used to train the solution version (for more information about recipes see Choosing a recipe). The example uses the following User-Personalization recipe specific itemExplorationConfig fields with their default values: explorationWeight and explorationItemAgeCutOff. If you omit the campaign-config parameter, the default values apply. For more information about the itemExplorationConfig fields, see the Properties and hyperparameters for the User-Personalization recipe.

aws personalize create-campaign \
--name campaign name \
--solution-version-arn solution version arn \
--min-provisioned-tps 1 \
--campaign-config "{\"itemExplorationConfig\":{\"explorationWeight\":\"0.3\",\"explorationItemAgeCutOff\":\"30\"}}"

The campaign is ready when its status is ACTIVE. To get the current status, call DescribeCampaign and check that the status field is ACTIVE.

If you retrain your solution version or want to change your campaign settings, you must update your campaign. For more information see Updating a campaign.

Amazon Personalize provides operations for managing campaigns such as ListCampaigns to list the campaigns you have created. You can delete a campaign by calling DeleteCampaign. If you delete a campaign, the solution versions that are part of the campaign are not deleted.

After you have created your campaign, use it to make recommendations. For more information, see Step 4: Getting recommendations.

Creating a campaign (Amazon SDKs)

After your solution version status is Active you are ready to deploy it with an Amazon Personalize campaign. Use the following code to create a campaign. Give the campaign a name, specify the Amazon Resource Name (ARN) of the solution version to deploy, and optionally specify the Minimum provisioned TPS the campaign will support (the default value for this parameter is 1). If you use the User-Personalization recipe, you can configure item exploration with the itemExplorationWeight and explorationItemAgeCutOff parameters.

SDK for Python (Boto3)

In this example, the itemExplorationWeight and explorationItemAgeCutOff parameters are specific to the User-Personalization recipe. The default itemExplorationWeight is 0.3 and the default explorationItemAgeCutOff is 30. If you leave out campaign configuration parameters, the default values apply.

import boto3

personalize = boto3.client('personalize')

response = personalize.create_campaign(
    name = 'campaign name',
    solutionVersionArn = 'solution version arn',
    minProvisionedTPS = 1,
    campaignConfig = {"itemExplorationConfig": {"explorationWeight": "0.3", "explorationItemAgeCutOff": "30"}}
)

arn = response['campaignArn']

description = personalize.describe_campaign(campaignArn = arn)['campaign']
print('Name: ' + description['name'])
print('ARN: ' + description['campaignArn'])
print('Status: ' + description['status'])

SDK for Java 2.x

In this example, the itemExplorationWeight and explorationItemAgeCutOff parameters are specific to the User-Personalization recipe. The default itemExplorationWeight is 0.3 and the default explorationItemAgeCutOff is 30. If you leave out campaign configuration parameters, the default values apply.

public static void createCampaign(PersonalizeClient personalizeClient, 
                                String campaignName, 
                                String solutionVersionArn, 
                                Integer minProvisionedTPS, 
                                String itemExplorationWeight, 
                                String explorationItemAgeCutOff) {
                                
    //Optional code to instantiate a HashMap and add the explorationWeight and explorationItemAgeCutOff values.
    //Remove if you aren't using User-Personaliztion.
    Map<String,String> itemExploration = new HashMap<String,String>();
    itemExploration.put("explorationWeight", itemExplorationWeight);
    itemExploration.put("explorationItemAgeCutOff", explorationItemAgeCutOff);

    try {
        // Build a User-Personalization recipe specific campaignConfig object with the itemExploration map.
        // CampaignConfig construction will vary by recipe.
        CampaignConfig campaignConfig = CampaignConfig.builder()
            .itemExplorationConfig(itemExploration)
            .build();
    
        // build the createCampaignRequest
        CreateCampaignRequest createCampaignRequest = CreateCampaignRequest.builder()
            .name(campaignName)
            .solutionVersionArn(solutionVersionArn)
            .minProvisionedTPS(minProvisionedTPS)
            .campaignConfig(campaignConfig) //
            .build();

        // create the campaign
        CreateCampaignResponse campaignResponse = personalizeClient.createCampaign(createCampaignRequest);
        String campaignArn = campaignResponse.campaignArn();
        
        DescribeCampaignRequest campaignRequest = DescribeCampaignRequest.builder()
            .campaignArn(campaignArn)
            .build();
    
        DescribeCampaignResponse campaignResponse = personalizeClient.describeCampaign(campaignRequest);
        Campaign newCampaign = campaignResponse.campaign();
        
        System.out.println("The Campaign status is " + newCampaign.status());
    
    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}

SDK for JavaScript v3

// Get service clients module and commands using ES6 syntax.
import { CreateCampaignCommand, PersonalizeClient } from
  "@aws-sdk/client-personalize";

// create personalizeClient
const personalizeClient = new PersonalizeClient({ region: "REGION" });

// set the campaign parameters
export const createCampaignParam = {
  solutionVersionArn: "SOLUTION_VERSION_ARN",    /* required */
  name: "CAMPAIGN_NAME",                         /* required */
  minProvisionedTPS: 1,                          /* optional */
  campaignConfig: {
    itemExplorationConfig: {
      explorationWeight: "0.3",                  /* optional */
      explorationItemAgeCutOff: "30",            /* optional */
    },
  },
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateCampaignCommand(createCampaignParam)
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();

The campaign is ready when its status is ACTIVE. To get the current status, call DescribeCampaign and check that the status field is ACTIVE.

If you manually retrain your solution version or want to change your campaign settings, you must update your campaign. For more information see Updating a campaign.

Amazon Personalize provides operations for managing campaigns such as ListCampaigns to list the campaigns you have created. You can delete a campaign by calling DeleteCampaign. If you delete a campaign, the solution versions that are part of the campaign are not deleted.

After you have created your campaign, use it to make recommendations. For more information, see Step 4: Getting recommendations.