本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 記錄即時事件以影響建議
<a name="recording-events"></a>

 *事件*是使用者與您的目錄之間的互動。它可以是與*項目*的互動，例如購買項目或觀看影片的使用者，或者可以採取*動作*，例如申請信用卡或註冊成員資格計劃。

Amazon Personalize 可以根據僅即時事件資料、僅歷史事件資料或兩者的混合提出建議。當您的客戶與建議互動時，記錄即時事件。這會建置您的互動資料，並保持資料的更新。它告訴 Amazon Personalize 您使用者目前的興趣，這可以改善建議相關性。

如果您的網域使用案例或自訂配方支援[即時個人化](use-case-recipe-features.md#about-real-time-personalization)，Amazon Personalize 會根據使用者不斷變化的興趣，即時使用事件來更新和調整建議。

如何記錄即時事件取決於您匯入的互動資料類型：
+ 對於*項目互動*，您可以使用 [PutEvents](API_UBS_PutEvents.md) API 操作記錄即時事件。Amazon Personalize 會將此資料附加至資料集群組中的[項目互動](interactions-datasets.md)資料。如需詳細資訊，請參閱[記錄即時項目互動事件](recording-item-interaction-events.md)。
+ 對於*動作互動*，您可以使用 [PutActionInteractions](API_UBS_PutActionInteractions.md) API 操作記錄即時事件。Amazon Personalize 會將此資料附加至資料集群組中的[動作互動](action-interactions-datasets.md)資料集。只有 PersonalIZED\$1ACTIONS 配方會使用動作互動資料。如需詳細資訊，請參閱[記錄即時動作互動事件記錄動作互動事件](recording-action-interaction-events.md)。

**Topics**
+ [即時事件如何影響建議](#recorded-events-influence-recommendations)
+ [記錄即時項目互動事件](recording-item-interaction-events.md)
+ [記錄即時動作互動事件](recording-action-interaction-events.md)
+ [記錄匿名使用者的事件](#recording-anonymous-user-events)
+ [第三方事件追蹤服務](#record-events-third-parties)
+ [實作範例](#recording-events-sample-architecture)

## 即時事件如何影響建議
<a name="recorded-events-influence-recommendations"></a>

 如果您的配方支援即時個人化，則在您建立推薦者或自訂行銷活動之後，Amazon Personalize 會在匯入後的幾秒內為現有項目或動作使用新的記錄事件資料。下列使用案例和配方支援即時個人化：
+ [建議您使用 (ECOMMERCE 使用案例）](ECOMMERCE-use-cases.md#recommended-for-you-use-case)
+ [最適合您的選項 (VIDEO\$1ON\$1DEMAND 使用案例）](VIDEO_ON_DEMAND-use-cases.md#top-picks-use-case)
+ [User-Personalization-v2 配方](native-recipe-user-personalization-v2.md)
+ [使用者個人化配方](native-recipe-new-item-USER_PERSONALIZATION.md)
+ [Personalized-Ranking-v2 配方](native-recipe-personalized-ranking-v2.md)
+ [個人化執行配方](native-recipe-search.md)
+ [Next-Best-Action 配方](native-recipe-next-best-action.md)

如果您使用 Trending-Now 配方，Amazon Personalize 會透過可設定的間隔自動考慮來自新事件資料的項目。您不需要建立新的解決方案版本。如需詳細資訊，請參閱[Trending-Now 配方](native-recipe-trending-now.md)。

 如果事件中的項目、動作或使用者是新的，Amazon Personalize 如何使用資料取決於您的使用案例或配方。如需詳細資訊，請參閱[訓練後更新資料集中的資料](updating-datasets.md)。

# 記錄即時項目互動事件
<a name="recording-item-interaction-events"></a>

 *項目互動事件*是使用者與目錄中項目之間的互動。例如，使用者購買鞋子或觀看電影。

當您顯示客戶項目建議時，記錄即時項目互動事件。這會建置您的互動資料，並保持資料的新鮮度。它告訴 Amazon Personalize 您使用者目前的興趣，這可以改善建議相關性。

 您可以使用 [PutEvents](API_UBS_PutEvents.md) API 操作記錄項目互動事件。Amazon Personalize 會將事件資料附加到資料集群組中的*項目互動*資料集。如果您使用完全相同的時間戳記和相同的屬性記錄兩個事件，Amazon Personalize 只會保留其中一個事件。您可以使用 AWS SDKs、 AWS Amplify 或 AWS Command Line Interface () 記錄項目互動事件AWS CLI。

如果您使用 Apache Kafka，您可以使用 *Amazon Personalize 的 Kafka 連接器*，將項目互動即時串流至 Amazon Personalize。如需詳細資訊，請參閱 *personalize-kafka-connector*[-connector Github 儲存庫中的 Kafka Connector for Amazon Personalize](https://github.com/aws/personalize-kafka-connector/blob/main/README.md)。

 AWS Amplify 包含一個用於記錄 Web 用戶端應用程式項目互動事件的 JavaScript 程式庫，以及一個用於記錄伺服器程式碼中事件的程式庫。如需詳細資訊，請參閱 [Amplify 文件](https://docs.amplify.aws/)。

**Topics**
+ [記錄項目互動事件和訓練模型的需求](#recording-events-requirements)
+ [建立項目互動事件追蹤器](event-get-tracker.md)
+ [記錄單一項目互動事件](putevents-example.md)
+ [使用事件值資料記錄多個項目互動事件](recording-events-example-event-value.md)
+ [使用印模資料記錄項目互動事件](putevents-including-impressions-data.md)
+ [事件指標和屬性報告](event-metrics.md)

## 記錄項目互動事件和訓練模型的需求
<a name="recording-events-requirements"></a>

若要記錄項目互動事件，您需要下列項目：
+ 包含 `Item interactions` 資料集群組，其中資料集可以是空的。如果您完成[入門教學課程](getting-started.md)指南，則可以使用您建立的相同資料集群組和資料集。如需建立資料集群組和資料集的資訊，請參閱 [將訓練資料匯入 Amazon Personalize 資料集](import-data.md)。
+ 事件追蹤器。
+ 呼叫 [PutEvents](API_UBS_PutEvents.md) API 操作。
+  如果您使用 AWS Lambda 函數呼叫 PutEvents 操作，則函數的執行角色必須具有在 `Resource`元素`*`中使用萬用字元執行`personalize:PutEvents`動作的許可。

您可以從空的項目互動資料集開始，並在記錄足夠的資料時，僅使用新的記錄事件來訓練模型。對於所有使用案例 （網域資料集群組） 和配方 （自訂資料集群組），您的互動資料在訓練之前必須具有下列項目：
+ 至少 1000 個項目互動記錄來自與目錄中項目互動的使用者。這些互動可以來自大量匯入、串流事件或兩者。
+ 至少 25 個唯一的使用者 IDs，每個 ID 至少有兩個項目互動。

對於品質建議，我們建議您從至少 1，000 個使用者中至少有 50，000 個項目互動，每個使用者有兩個或更多項目互動。

# 建立項目互動事件追蹤器
<a name="event-get-tracker"></a>

您必須先建立項目互動事件追蹤器，才能記錄項目互動事件。*事件追蹤器*會將新的事件資料導向至資料集群組中的*項目互動*資料集。

您可以使用 Amazon Personalize 主控台或 [CreateEventTracker](API_CreateEventTracker.md) API 操作建立事件追蹤器。您可以將包含目標項目互動資料集之資料集群組的 Amazon Resource Name (ARN) 做為參數傳遞。如需使用 Amazon Personalize 主控台建立事件追蹤器的說明，請參閱 [建立事件追蹤器 （主控台）](importing-interactions.md#event-tracker-console)。

 事件追蹤器包含*追蹤 ID*，您在使用 [PutEvents](https://docs.aws.amazon.com/personalize/latest/dg/API_UBS_PutEvents.html) 操作時以參數形式傳遞。然後，Amazon Personalize 會將新的事件資料附加到您在事件追蹤器中指定的資料集群組的項目互動資料集。

**注意**  
您只能為資料集群組建立一個項目互動事件追蹤器。

------
#### [ Python ]

```
import boto3

personalize = boto3.client('personalize')

response = personalize.create_event_tracker(
    name='MovieClickTracker',
    datasetGroupArn='arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieClickGroup'
)
print(response['eventTrackerArn'])
print(response['trackingId'])
```

事件追蹤器 ARN 和追蹤 ID 顯示，例如：

```
{
    "eventTrackerArn": "arn:aws:personalize:us-west-2:acct-id:event-tracker/MovieClickTracker",
    "trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

------
#### [ AWS CLI ]

```
aws personalize create-event-tracker \
    --name MovieClickTracker \
    --dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieClickGroup
```

事件追蹤器 ARN 和追蹤 ID 顯示，例如：

```
{
    "eventTrackerArn": "arn:aws:personalize:us-west-2:acct-id:event-tracker/MovieClickTracker",
    "trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateEventTrackerCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";

// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the event tracker's parameters.
export const createEventTrackerParam = {
  datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
  name: "NAME" /* required */,
};

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

------
#### [ SDK for Java 2.x ]

```
public static String createEventTracker(PersonalizeClient personalizeClient, 
                                      String eventTrackerName, 
                                      String datasetGroupArn) {
        
    String eventTrackerId = null;
    String eventTrackerArn = null;
    long maxTime = 3 * 60 * 60; 
    long waitInMilliseconds = 30 * 1000;
    String status;
    
    try {
        CreateEventTrackerRequest createEventTrackerRequest = CreateEventTrackerRequest.builder()
            .name(eventTrackerName)
            .datasetGroupArn(datasetGroupArn)
            .build();
       
        CreateEventTrackerResponse createEventTrackerResponse = 
            personalizeClient.createEventTracker(createEventTrackerRequest);
        
        eventTrackerArn = createEventTrackerResponse.eventTrackerArn();
        eventTrackerId = createEventTrackerResponse.trackingId();
        
        System.out.println("Event tracker ARN: " + eventTrackerArn);
        System.out.println("Event tracker ID: " + eventTrackerId);

        maxTime = Instant.now().getEpochSecond() + maxTime;

        DescribeEventTrackerRequest describeRequest = DescribeEventTrackerRequest.builder()
            .eventTrackerArn(eventTrackerArn)
            .build();
        
        while (Instant.now().getEpochSecond() < maxTime) {

            status = personalizeClient.describeEventTracker(describeRequest).eventTracker().status();
            System.out.println("EventTracker status: " + status);

            if (status.equals("ACTIVE") || status.equals("CREATE FAILED")) {
                break;
            }
            try {
                Thread.sleep(waitInMilliseconds);
            } catch (InterruptedException e) {
                System.out.println(e.getMessage());
            }
        }
        return eventTrackerId;
    }
    catch (PersonalizeException e){
        System.out.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
    return eventTrackerId;
}
```

------

# 記錄單一項目互動事件
<a name="putevents-example"></a>

為資料集群組建立*項目互動資料集*和[事件追蹤器](event-get-tracker.md)之後，您就可以記錄項目互動事件。下列範例顯示傳遞一個項目互動事件`PutEvents`的操作。隨即會顯示對應的結構描述，以及項目互動資料集的範例資料列。

 當使用者第一次造訪您的網站或使用應用程式`sessionId`時，您的應用程式會產生唯一的 。您必須在整個工作階段的所有事件`sessionId`中使用相同的 。Amazon Personalize 使用 `sessionId`，在事件登入 （匿名） 之前，將事件與使用者建立關聯。如需詳細資訊，請參閱[記錄匿名使用者的事件](recording-events.md#recording-anonymous-user-events)。

事件清單是 [Event](API_UBS_Event.md) 物件的陣列。每個事件`eventType`都需要 。如果您沒有事件類型資料，您可以提供預留位置值以滿足需求。

`trackingId` 來自您在 中建立的事件追蹤器[建立項目互動事件追蹤器](event-get-tracker.md)。`userId`、`itemId` 和 `sentAt` 參數對應到相應歷史 `Interactions` 資料集的 USER\$1ID、ITEM\$1ID 和 TIMESTAMP 欄位。如需詳細資訊，請參閱[為 Amazon Personalize 結構描述建立結構描述 JSON 檔案](how-it-works-dataset-schema.md)。

**對應的資料集資料欄**

```
Dataset columns: USER_ID, ITEM_ID, TIMESTAMP, EVENT_TYPE
Example data: user123, item-xyz, 1543631760, click
```

**程式碼範例**

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'USER_ID',
    sessionId = 'session_id',
    eventList = [{
        'sentAt': 1719511760,
        'eventType': 'click',
        'itemId': 'ITEM_ID'
        }]
)
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { PutEventsCommand } from "@aws-sdk/client-personalize-events";
import { personalizeEventsClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeEventsClient = new PersonalizeEventsClient({ region: "REGION"});

// Convert your UNIX timestamp to a Date.
const sentAtDate = new Date(1613443801 * 1000); // 1613443801 is a testing value. Replace it with your sentAt timestamp in UNIX format.

// Set put events parameters.
const putEventsParam = {
  eventList: [
    /* required */
    {
      eventType: "EVENT_TYPE" /* required */,
      sentAt: sentAtDate /* required, must be a Date with js */,
      eventId: "EVENT_ID" /* optional */,
      itemId: "ITEM_ID" /* optional */,
    },
  ],
  sessionId: "SESSION_ID" /* required */,
  trackingId: "TRACKING_ID" /* required */,
  userId: "USER_ID" /* required */,
};
export const run = async () => {
  try {
    const response = await personalizeEventsClient.send(
      new PutEventsCommand(putEventsParam),
    );
    console.log("Success!", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------
#### [ AWS CLI ]

```
aws personalize-events put-events \
    --tracking-id tracking_id \
    --user-id USER_ID \
    --session-id session_id \
    --event-list '[{
        "sentAt": 1719511760,
        "eventType": "click",
        "itemId": "ITEM_ID"
      }]'
```

------
#### [ SDK for Java 2.x ]

```
public static void putEvents(PersonalizeEventsClient personalizeEventsClient, 
                            String trackingId, 
                            String sessionId, 
                            String userId, 
                            String itemId,
                            String eventType) {
    
    try { 
        Event event = Event.builder()
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(itemId)
            .eventType(eventType)
            .build();

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(event)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
        System.out.println("Response code: " + responseCode);

        } catch (PersonalizeEventsException e) {
            System.out.println(e.awsErrorDetails().errorMessage());
        }
}
```

------

# 使用事件值資料記錄多個項目互動事件
<a name="recording-events-example-event-value"></a>

為資料集群組建立*項目互動資料集*和[事件追蹤器](event-get-tracker.md)之後，您就可以記錄項目互動事件。下列範例顯示如何記錄具有不同事件類型和不同事件值的多個項目互動事件。

 當您設定解決方案時，如果您*的項目互動資料集*包含 EVENT\$1TYPE 和 EVENT\$1VALUE 欄位，您可以將特定值設定為閾值，以排除訓練中的記錄。如需詳細資訊，請參閱[選擇用於訓練的項目互動資料](event-values-types.md)。

------
#### [ Python ]

```
import boto3
import json

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'user555',
    sessionId = 'session1',
    eventList = [{
        'eventId': 'event1',
        'sentAt': 1553631760,
        'eventType': 'like',
        'properties': json.dumps({
            'itemId': 'choc-panama',
            'eventValue': 4
            })
        }, {
        'eventId': 'event2',
        'sentAt': 1553631782,
        'eventType': 'rating',
        'properties': json.dumps({
            'itemId': 'movie_ten',
            'eventValue': 3
            })
        }]
)
```

------
#### [ AWS CLI ]

```
aws personalize-events put-events \
    --tracking-id tracking_id \
    --user-id user555 \
    --session-id session1 \
    --event-list '[{
        "eventId": "event1",
        "sentAt": 1553631760,
        "eventType": "like",
        "properties": "{\"itemId\": \"choc-panama\", \"eventValue\": \"true\"}"
      }, {
        "eventId": "event2",
        "sentAt": 1553631782,
        "eventType": "rating",
        "properties": "{\"itemId\": \"movie_ten\", \"eventValue\": \"4\", \"numRatings\": \"13\"}"
      }]'
```

------
#### [ SDK for Java 2.x ]

```
public static void putMultipleEvents(PersonalizeEventsClient personalizeEventsClient, 
                            String trackingId, 
                            String sessionId, 
                            String userId, 
                            String event1Type, 
                            Float event1Value, 
                            String event1ItemId,
                            int event1NumRatings,
                            String event2Type, 
                            Float event2Value, 
                            String event2ItemId,
                            int event2NumRatings) {  
                                                    
    ArrayList<Event> eventList = new ArrayList<Event>();
                        
    try {
        Event event1 = Event.builder()
            .eventType(event1Type)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(event1ItemId)
            .eventValue(event1Value)
            .properties("{\"numRatings\": "+ event1NumRatings +"}")
            .build(); 

        eventList.add(event1); 

        Event event2 = Event.builder()
            .eventType(event2Type)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(event2ItemId)
            .eventValue(event2Value)
            .properties("{\"numRatings\": "+ event2NumRatings +"}")
            .build();

        eventList.add(event2);

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(eventList)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
            
        System.out.println("Response code: " + responseCode);

    } catch (PersonalizeEventsException e) {
        System.out.println(e.awsErrorDetails().errorMessage());
    }
}
```

------

**注意**  
屬性機碼使用與「互動」結構描述中的欄位相符的小寫連字 (camel case) 名稱。例如，如果互動結構描述中定義了欄位 'NUM\$1RATINGS'，則屬性索引鍵應為 `numRatings`。

# 使用印模資料記錄項目互動事件
<a name="putevents-including-impressions-data"></a>

如果您使用[使用者個人化](native-recipe-new-item-USER_PERSONALIZATION.md)配方或將 IMPRESSIONS 欄位新增至網域資料集群組中資料集的結構描述，您可以在 PutEvents 操作中記錄曝光資料。印模是使用者與特定項目互動 （例如，點按或觀看） 時可見的項目清單。Amazon Personalize 使用曝光資料來引導探勘，其中的建議包括互動資料較少或相關性較低的項目。如需 Amazon Personalize 可建立模型之*隱含*和*明確*印象的相關資訊，請參閱 [印象資料](interactions-datasets.md#interactions-impressions-data)。

**重要**  
如果您在`PutEvents`請求中提供衝突的隱含和明確印模資料，Amazon Personalize 預設會使用明確印模。

若要記錄將使用者顯示為曝光資料的 Amazon Personalize 建議，請在[PutEvents](API_UBS_PutEvents.md)請求`recommendationId`中包含 ，Amazon Personalize 會根據您的建議資料衍生隱含曝光。

若要手動記錄事件的曝光資料，請在[PutEvents](API_UBS_PutEvents.md)命令的`impression`輸入參數中列出曝光。下列程式碼範例示範如何使用適用於 Python 的 SDK (Boto3) 或適用於 Java 的 SDK 2.x，在 PutEvents 操作`impression`中包含 `recommendationId`和 。如果您同時包含兩者，Amazon Personalize 預設會使用明確印模。

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_events = boto3.client(service_name='personalize-events')

personalize_events.put_events(
    trackingId = 'tracking_id',
    userId= 'userId',
    sessionId = 'sessionId',
    eventList = [{
        'eventId': 'event1',
        'eventType': 'rating',
        'sentAt': 1553631760,
        'itemId': 'item id',
        'recommendationId': 'recommendation id',
        'impression': ['itemId1', 'itemId2', 'itemId3']
        }]
)
```

------
#### [ SDK for Java 2.x ]

使用下列`putEvents`方法記錄具有曝光資料和 recommendationId 的事件。對於印模參數，傳遞 itemIds 清單做為 ArrayList。

```
public static void putEvents(PersonalizeEventsClient personalizeEventsClient, 
                                String trackingId, 
                                String sessionId, 
                                String userId, 
                                String eventType, 
                                Float eventValue, 
                                String itemId,
                                ArrayList<String> impressions,
                                String recommendationId) {

    try { 
        Event event = Event.builder()
            .eventType(eventType)
            .sentAt(Instant.ofEpochMilli(System.currentTimeMillis() + 10 * 60 * 1000))
            .itemId(itemId)
            .eventValue(eventValue)
            .impression(impressions)
            .recommendationId(recommendationId)
            .build();

        PutEventsRequest putEventsRequest = PutEventsRequest.builder()
            .trackingId(trackingId)
            .userId(userId)
            .sessionId(sessionId)
            .eventList(event)
            .build();

        int responseCode = personalizeEventsClient.putEvents(putEventsRequest)
            .sdkHttpResponse()
            .statusCode();
        System.out.println("Response code: " + responseCode);

    } catch (PersonalizeEventsException e) {
        System.out.println(e.awsErrorDetails().errorMessage());
    }
}
```

------

# 事件指標和屬性報告
<a name="event-metrics"></a>

若要監控傳送至 Amazon Personalize 的事件類型和數量，請使用 Amazon CloudWatch 指標。如需詳細資訊，請參閱[使用 Amazon CloudWatch 監控 Amazon Personalize](personalize-monitoring.md)。

 若要產生顯示建議影響的 CloudWatch 報告，請建立指標屬性，並使用即時建議記錄使用者互動。如需建立指標屬性的資訊，請參閱 [測量 Amazon Personalize 建議的影響](measuring-recommendation-impact.md)。

 對於每個事件，包括您向使用者顯示的建議的建議 ID。或包含事件來源，例如第三方。匯入此資料以比較不同的行銷活動、推薦者和第三方。您最多可以匯入 100 個事件屬性來源。
+  如果您提供 `recommendationId`，Amazon Personalize 會自動判斷來源行銷活動或建議者，並在 EVENT\$1ATTRIBUTION\$1SOURCE 欄中的報告中識別。
+  如果您提供這兩個屬性，Amazon Personalize 只會使用 `eventAttributionSource`。
+  如果您不提供來源，Amazon Personalize 會在`SOURCE_NAME_UNDEFINED`報告中標記來源。

 下列程式碼示範如何在 PutEvents 操作中`eventAttributionSource`為 事件提供 。

```
response = personalize_events.put_events(
    trackingId = 'eventTrackerId',
    userId= 'userId',
    sessionId = 'sessionId123',
    eventList = [{
        'eventId': 'event1',
        'eventType': 'watch',
        'sentAt': '1667260945',
        'itemId': '123',
        'metricAttribution': { 
            'eventAttributionSource': 'thirdPartyServiceXYZ'
        }
    }]
)
statusCode = response['ResponseMetadata']['HTTPStatusCode']
print(statusCode)
```

下列程式碼示範如何在 PutEvents 操作中`recommendationId`為事件提供 。

```
response = personalize_events.put_events(
    trackingId = 'eventTrackerId',
    userId= 'userId',
    sessionId = 'sessionId123',
    eventList = [{
        'eventId': 'event1',
        'eventType': 'watch',
        'sentAt': '1667260945',
        'itemId': '123',
        'recommendationId': 'RID-12345678-1234-1234-1234-abcdefghijkl'
    }]
)
statusCode = response['ResponseMetadata']['HTTPStatusCode']
print(statusCode)
```

# 記錄即時動作互動事件
<a name="recording-action-interaction-events"></a>

*動作互動*事件是使用者與*動作*之間的互動。例如，註冊成員資格計劃或申請信用卡的使用者。

如果您使用 PersonalIZED\$1ACTIONS 自訂配方，請在客戶與動作建議互動時記錄即時動作互動事件。這會建置您的互動資料，並保持資料的新鮮度。它還告訴 Amazon Personalize 有關使用者目前的興趣，這可以提高建議相關性。只有 PersonalIZED\$1ACTIONS 自訂配方會使用動作互動資料。

您可以使用 [PutActionInteractions](API_UBS_PutActionInteractions.md) API 操作記錄動作互動事件。Amazon Personalize 會將此資料附加至資料集群組中的[動作互動](action-interactions-datasets.md)資料集。

動作互動事件必須具有事件類型屬性，可以是下列其中一項：
+ 採取 – **記錄使用者採取建議動作時所採取的事件。
+ 未採取 – 當您的使用者刻意選擇在檢視後不採取動作時，記錄*未採取*的事件。例如，如果他們在向他們顯示動作時選擇*否*。*未採取*的事件可能表示客戶對 動作不感興趣。
+ 已檢視 – 當您在使用者選擇採取或不採取動作之前向他們顯示動作時，記錄*已檢視*的事件。Amazon Personalize 使用*檢視*事件來了解使用者的興趣。例如，如果使用者檢視動作但未採取動作，則該使用者未來可能不會對此動作感興趣。

 您可以使用 AWS SDKs或 AWS Command Line Interface () 記錄即時事件AWS CLI。如果您使用完全相同的時間戳記和相同的屬性記錄兩個事件，Amazon Personalize 只會保留其中一個事件。

**Topics**
+ [記錄動作互動事件的需求](#recording-action-interaction-requirements)
+ [尋找動作互動事件追蹤器的 ID](action-interaction-tracker-id.md)
+ [記錄單一動作互動事件](record-single-action-interaction.md)
+ [記錄多個動作互動事件](recording-multiple-action-interactions.md)

## 記錄動作互動事件的需求
<a name="recording-action-interaction-requirements"></a>

若要記錄即時動作互動事件，您需要下列項目：
+ 包含 的資料集群組`Action interactions dataset`，可以是空的。如需建立資料集群組和資料集的資訊，請參閱 [將訓練資料匯入 Amazon Personalize 資料集](import-data.md)。
+ 事件追蹤器的 ID。您可以在 PutActionInteractions 操作中指定此 ID。當您建立動作互動資料集時，Amazon Personalize 會自動為您建立動作互動事件追蹤器。如需詳細資訊，請參閱[尋找動作互動事件追蹤器的 ID](action-interaction-tracker-id.md)。
+ 呼叫 [PutActionInteractions](API_UBS_PutActionInteractions.md) 操作。

# 尋找動作互動事件追蹤器的 ID
<a name="action-interaction-tracker-id"></a>

當您建立動作互動資料集時，Amazon Personalize 會自動為您建立*動作互動*事件追蹤器。您可以在 PutActionInteractions API 操作中指定追蹤器的 ID。Amazon Personalize 會使用它，將新資料導向至資料集群組中的*動作互動*資料集。

 您可以在 Amazon Personalize 主控台的動作互動資料集的詳細資訊頁面上找到事件追蹤器的 ID。您也可以呼叫 DescribeDataset API 操作來尋找 ID。下列 Python 程式碼會列印動作互動資料集的追蹤 ID。

```
import boto3
      
personalize = boto3.client(service_name='personalize')

response = personalize.describe_dataset(
  datasetArn="Action interactions dataset ARN"
)

print(response['trackingId'])
```

# 記錄單一動作互動事件
<a name="record-single-action-interaction"></a>

建立動作互動資料集之後，您就可以使用 [PutActionInteractions](API_UBS_PutActionInteractions.md)操作記錄動作互動事件。下列程式碼顯示傳遞 TakeN 事件`PutActionInteractions`的操作。當您向 Amazon Personalize 顯示使用者建議並採取動作時，您可以記錄此事件，例如申請您的信用卡。

`actionInteractions` 是 ActionInteraction 物件的陣列。`trackingId` 來自您建立動作互動資料集時建立的事件追蹤器 Amazon Personalize。如需詳細資訊，請參閱[尋找動作互動事件追蹤器的 ID](action-interaction-tracker-id.md)。

當使用者第一次造訪您的網站或使用應用程式`sessionId`時，您的應用程式會產生唯一的 。您必須在整個工作階段的所有事件`sessionId`中使用相同的 。Amazon Personalize 使用 `sessionId`，在事件登入 （匿名） 之前，將事件與使用者建立關聯。如需詳細資訊，請參閱[記錄匿名使用者的事件](recording-events.md#recording-anonymous-user-events)。

`userId`、 `actionId`和 `sentAt` 參數對應至動作互動資料集的 USER\$1ID、ACTION\$1ID、EVENT\$1TYPE 和 TIMESTAMP 欄位。

**對應的動作互動資料集**

```
USER_ID, ACTION_ID, TIMESTAMP, EVENT_TYPE
user123, action-xyz, 1543631760, TAKEN
```

**程式碼範例**

------
#### [ AWS CLI ]

```
aws personalize-events put-action-interactions \
--tracking-id 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--action-interactions '[{
  "userId": "user123",
  "sessionId": "abcdefg",
  "timestamp": 1543631760,
  "eventType": "TAKEN",
  "actionId": "action-xyz"}]'
```

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_events = boto3.client(service_name='personalize-events')

response = personalize_events.put_action_interactions(
  trackingId='12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  actionInteractions=[{
    'userId': 'user123',
    'sessionId': 'abcdefg',
    'timestamp': 1543631760,
    'eventType': 'Taken',
    'actionId': 'action-xyz'
  }]
)
```

------

# 記錄多個動作互動事件
<a name="recording-multiple-action-interactions"></a>

下列程式碼說明如何為具有相同 sessionId 的相同使用者記錄多個動作互動事件。

**對應的動作互動資料集**

```
USER_ID, ACTION_ID, EVENT_TYPE, TIMESTAMP
user123, action123, Taken, 1543531139
user123, action345, Not Taken, 1543531139
```

------
#### [ AWS CLI ]

```
aws personalize-events put-action-interactions \
--tracking-id 6ddfe6b7-cd83-4dd4-b09d-4c35ecbacfe1 \
--action-interactions '[{
  "userId": "user123",
  "sessionId": "abcdefg",
  "timestamp": 1543531139,
  "eventType": "Taken",
  "actionId": "action123"
},
{
  "userId": "user123",
  "sessionId": "abcdefg",
  "timestamp": 1543531139,
  "eventType": "Not Taken",
  "actionId": "action345"}]'
```

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_events = boto3.client(service_name='personalize-events')

response = personalize_events.put_action_interactions(
  trackingId='12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  actionInteractions=[{
    'userId': 'user123',
    'sessionId': 'abcdefg',
    'timestamp': 1697848587,
    'eventType': 'Taken',
    'actionId': 'action123'
  },
  {
    'userId': 'user123',
    'sessionId': 'abcdefg',
    'timestamp': 1697848622,
    'eventType': 'Not Taken',
    'actionId': 'action345'
  }]
)
```

------

## 記錄匿名使用者的事件
<a name="recording-anonymous-user-events"></a>

**重要**  
如果您未使用 `sessionId`和 `userId` 為使用者記錄至少一個事件，Amazon Personalize 不會在訓練`sessionId`時僅使用追蹤到 的活動。訓練完成後，建議將不再以追蹤到 的活動為基礎`sessionId`。這將在登入前後為 userIds 建立連續事件歷史記錄。

您可以在使用者建立帳戶之前記錄其項目互動或動作互動事件。為匿名使用者記錄事件，以建立持續事件歷史記錄，其中包含登入前後的事件。這可提供 Amazon Personalize 更多與使用者相關的互動資料，這有助於產生更相關的建議。

若要記錄匿名使用者 （尚未登入的使用者） 的事件，每個事件只會指定 `sessionId`。當使用者第一次造訪您的網站或使用應用程式`sessionId`時，您的應用程式會產生唯一的 。您必須在整個工作階段的所有事件`sessionId`中使用相同的 。Amazon Personalize 使用 `sessionId`，在事件登入之前將事件與使用者建立關聯。

除非您將匿名使用者的事件與 建立關聯，否則 Amazon Personalize 不會在訓練時使用這些事件`userId`。如需詳細資訊，請參閱[為匿名使用者建立持續事件歷史記錄](#recording-events-building-continuous-event-history)。

若要為匿名使用者提供[即時個人化](use-case-recipe-features.md#about-real-time-personalization)，請在 [GetRecommendations](API_RS_GetRecommendations.md)或 GetActionRecommendations 請求中將 sessionId 指定為 userId。
+ 如需示範如何使用 PutEvents 操作和 sessionId 和 userId 記錄項目互動事件的程式碼範例，請參閱 [記錄單一項目互動事件](putevents-example.md)。
+ 如需示範如何使用 PutActionInteractions 操作和 sessionId 和 userId 記錄動作互動事件的程式碼範例，請參閱 [記錄單一動作互動事件](record-single-action-interaction.md)。

### 為匿名使用者建立持續事件歷史記錄
<a name="recording-events-building-continuous-event-history"></a>

 若要為匿名使用者建立事件歷史記錄，並讓 Amazon Personalize 在訓練時使用其事件，請使用 `sessionId`和 記錄至少一個事件`userId`。然後，您可以為 記錄任意數量的事件`userId`。開始提供 後`userId`， `sessionId`可能會變更。在下一次完整重新訓練期間，Amazon Personalize 會將 `userId` 與追蹤到原始 的匿名使用者歷史記錄建立關聯`sessionId`。

重新訓練完成後，建議將根據`sessionId`從匿名事件追蹤到 的活動，以及追蹤到其 的任何事件`userId`。

**注意**  
 如果您的使用者未建立 帳戶，而且您希望 Amazon Personalize 在訓練時使用資料，您可以使用 `sessionId`做為事件`userId`中的 。不過，如果使用者最終建立 帳戶，您將無法將來自其匿名瀏覽的事件與其新的 建立關聯`userId`。

## 第三方事件追蹤服務
<a name="record-events-third-parties"></a>

下列客戶資料平台 (CDPs) 可協助您從應用程式收集事件資料，並將其傳送至 Amazon Personalize。
+ **振幅** – 您可以使用振幅來追蹤使用者動作，以協助您了解使用者的行為。如需使用 Amplitude 和 Amazon Personalize 的資訊，請參閱下列 AWS 合作夥伴網路 (APN) 部落格文章：[使用 Amplitude 和 Amazon Personalize 測量個人化的有效性](https://aws.amazon.com/blogs/apn/measuring-the-effectiveness-of-personalization-with-amplitude-and-amazon-personalize/)。
+ **客群** – 您可以使用客群將資料傳送至 Amazon Personalize。如需整合客群與 Amazon Personalize 的詳細資訊，請參閱 [Amazon Personalize Destination](https://segment.com/docs/connections/destinations/catalog/amazon-personalize/)。

## 實作範例
<a name="recording-events-sample-architecture"></a>

如需示範如何使用 Amazon Personalize 來回應使用事件追蹤器和 [PutEvents](API_UBS_PutEvents.md)操作之使用者的即時行為的範例 Jupyter 筆記本，請參閱 [amazon-personalize-samples](https://github.com/aws-samples/amazon-personalize-samples) GitHub 儲存庫的 **get\$1started** 資料夾中的 [2.View\$1Campaign\$1And\$1Interactions.ipynb](https://github.com/aws-samples/amazon-personalize-samples/blob/master/getting_started/notebooks/2.View_Campaign_And_Interactions.ipynb)。

 如需示範如何從與建議互動的使用者串流事件的範例，請參閱 Amazon Personalize 範例 GitHub 儲存庫中的 [streaming\$1events](https://github.com/aws-samples/amazon-personalize-samples/tree/master/next_steps/operations/streaming_events)。

 如需包含原始碼和支援檔案的完整範例，以在 Amazon Personalize 資源和用戶端應用程式之間部署即時 APIs，請參閱 GitHub 儲存庫 AWS 範例中[的即時個人化 APIs](https://github.com/aws-samples/personalization-apis)。此專案包含如何實作下列項目：
+ 使用者內容和使用者事件集合
+ 回應快取
+ 根據項目中繼資料來裝飾建議
+ A/B 測試
+  API 身分驗證