Amazon Personalize
Developer Guide

This is prerelease documentation for a service in preview release. It is subject to change.

Recording Events

You can send event data to Amazon Personalize Events by using the Amazon Personalize event ingestion SDK. You can use the Amazon Personalize console to get event-ingestion code that you can use to record events. The event ingestion SDK includes a JavaScript library for recording events from web client applications. It also includes a library for recording events in server code. When you record an event, Amazon Personalize uses it to update the associated solution.

Getting a Tracking ID

You need a tracking ID to record events. A tracking ID authorizes you to send data to Amazon Personalize Events. You can generate a tracking ID by running the create-event-tracker command, for example:

Note

The AWS CLI command you call in this step is personalize-events.

aws personalize-events create-event-tracker \ --name MediaClickTracker \ --dataset-group-arn datasetGroupArn \ --cloud-watch-role-arn cloudWatchRoleArn

The event tracker ARN and tracking ID are displayed, for example:

{ "eventTrackerArn": "arn:aws:personalize::acct-id:event-tracker/MediaClickTracker", "trackingId": "string" }

To get the value of CloudWatchRoleArn:

  1. Attach the CloudWatchFullAccess AWS managed policy to the role you created in Create an IAM Role.

  2. Use the arn of the updated role as the value for CloudWatchRoleArn.

Supported Events

Amazon Personalize supports the following events:

  • Click

  • Search

  • AddToCart

  • RemoveFromCart

  • Checkout

  • Like

  • Comment

  • Rating

  • Play

  • Pause

  • Resume

  • TimeWatched

  • Ended

Send Real Time Event Data from the Client

In the following procedure, use the AWS Amplify JavaScript Library to record media event data.

  1. Generate a Cognito identity pool ID.

    Amazon Personalize authenticates the user identities for the event data using the Cognito identity pool. To track authenticated users you need to create a Cognito user pool. To track anonymous users, you need to enable access to unauthenticated identities. Follow AWS Amplify Authentication for usage guidelines.

    An example of an identity pool ID is: us-west-2:1699ebc0-7900-4099-b910-2df94f52a030.

  2. Download personalize-events.min.js and include it in your web application (PREVIEW RELEASE).

  3. Add Amazon Personalize as a provider in Amplify.

    Add the following code to your application. Replace identityPoolId and trackingId with the identity pool ID and tracking ID generated previously.

    // Configure the plugin after adding it to the Analytics module const aws_config = { "aws_project_region": "us-west-2", "aws_cognito_identity_pool_id": "identityPoolId", "aws_cognito_region": "us-west-2", }; Analytics.addPluggable(new AmazonPersonalizeProvider("trackingId")); Auth.configure(aws_config); // Configure the plugin after adding it to the Analytics module Analytics.configure({ AmazonPersonalize: { // OPTIONAL - Amazon Personalize service region region: 'us-east-1', // OPTIONAL - The number of events to be deleted from the buffer when flushed. flushSize: 10, // OPTIONAL - The interval in milliseconds to perform a buffer check and flush if necessary. flushInterval: 5000, // 5s } });
  4. Record event data as shown in the following code.

    Note the use of the eventType and eventValue keys. These keys map to the EVENT_TYPE and EVENT_VALUE fields in your dataset schema.

    Analytics.record({ eventName: "ListView", properties: {"items": [{"id": "item1"}, {"id": "item2"}], "listViewId": "list1"} }, "AmazonPersonalize"); ===Click event:===== Analytics.record({ eventName: "Click", properties: {"id": "itemIdClickedOn", "name": "itemNameClickedOn"} }, "AmazonPersonalize"); === Page event ==== Analytics.record({ eventName: "Page", properties: {"id": "page id", "name": "page name"} }, "AmazonPersonalize"); === MediaAutoTrack event ==== Analytics.record({ eventName: "MediaAutoTrack", properties: { "id": "MEDIA DOM ELEMENT ID" } }, "AmazonPersonalize");

Recording Event Data with Python

The following procedures show you how to get the tracking ID and how to record an event.

To get a tracking identifier

  1. Use the following code to get a tracking identifier.

    import boto3 if __name__ == "__main__": personalize = boto3.client('personalize', region_name='us-west-2') response=personalize.create_event_tracker( cloudWatchRoleArn="role arn", datasetGroupArn="dataset group arn", name="tracker name" ) print("Event tracker arn: " + response['eventTrackerArn']) print("Tracking Id: " + response['trackingId'])
  2. Run the code. The tracking id is displayed. Store the value as you need it to record events.

To record an event

  • Use the following code to record an event.

    if __name__ == "__main__": events = boto3.client('personalize-events', region_name='us-west-2') events.record( trackingId = "tracking id", userId= 'user id', sessionId = 'session id', eventList = [{"eventName":"Click", "properties":'20' , "sentAt":00000000}])

Recording Event Data with Server Applications

Your application might need to implement server-side support for recording event data with Amazon Personalize. For example, processing events from other AWS services such as Amazon Kinesis. A typical approach is to implement an AWS Lambda function to process real-time Kinesis stream events and record them to Amazon Personalize with the Record operation.