このページでは、ユーザー イベントタイプの見込みのリストを含むユーザー イベント オブジェクトについて説明し、すべてのユーザー イベントタイプのサンプルデータを提供します。
小売業向け Vertex AI Searchl は、リアルタイムのユーザー イベントを使用してレコメンデーションと検索結果を生成します。データをアップロードすると、レコメンデーションと検索の両方でそのデータを使用できるため、両方のサービスを使用する場合に、同じイベントを 2 回アップロードする必要はありません。
ユーザー イベントの記録については、リアルタイム ユーザー イベントの記録をご覧ください。
ユーザー イベントタイプ
ユーザーが販売店サイトを閲覧する際に記録できるユーザー イベントには、次のようないくつかの種類があります。
| ユーザー イベント名 | ユーザーの操作 |
|---|---|
| add-to-cart | プロダクトをカートに追加します。 |
| category-page-view | セールページやプロモーション ページなどの特別なページを表示します。 |
| detail-page-view | プロダクトの詳細ページを表示します。 |
| home-page-view | ホームページを表示します。 |
| purchase-complete | 購入手続きを完了します。 |
| 検索 | カタログを検索します。 |
| shopping-cart-page-view | ショッピング カートを表示します。 |
UserEvent オブジェクトの詳細については、UserEvent をご覧ください。
イベントタイプの優先度
最適な結果のためには、すべてのイベントタイプのユーザー イベントを記録することをおすすめします。次の表に、さまざまなユーザー イベントタイプの優先度を示します。品質の高いデータモデルを実現するには、優先度が最も高いユーザー イベントをログに記録する必要があります。
| 優先度 | ユーザー イベント |
|---|---|
| 最初のライブテストに必要 |
|
| 時間とともにレコメンデーション モデルの品質を向上させるうえで重要 |
ユーザー イベントの要件とベスト プラクティス
次の表に、レコメンデーション検索が使用するユーザー イベントタイプの要件とベスト プラクティスの一覧を示します。小売業向け Vertex AI Search が高品質の結果を生成できるように、ユーザー イベントがこれらの要件を満たしていることを確認します。
このセクションで説明する事項:
- ユーザー イベントの要件: 一般的なユーザー イベントの要件。これらの要件は、レコメンデーションと検索のどちらを使用しても適用されます。
- レコメンデーション固有の要件: レコメンデーションのユーザー イベントの要件。
- 検索固有の要件: 検索のユーザー イベントの要件。
レコメンデーション を使用する場合は、モデルタイプ データの要件もご覧ください。使用する予定の最適化案モデルのタイプと最適化目標に応じた追加の要件が示されています。
検索用のデータ品質指標は、Search for Retail コンソールの [データ品質] ページで確認できます。これらの指標は、データ品質の推奨基準を満たしているプロダクトとユーザー イベントの割合を示します。検索データ品質を表示する方法については、検索パフォーマンス階層をロック解除するをご覧ください。
ユーザー イベントの要件
小売業向け Vertex AI Search が高品質の結果を生成できるように、ユーザー イベントが次の要件を満たしていることを確認します。これらは、レコメンデーションと検索の両方に適用されます。
| イベントタイプ | 要件 | 影響 |
|---|---|---|
| すべてのイベント |
合成データまたは重複イベントを含めないでください。 |
合成イベントや重複イベントはモデルの品質に悪影響を及ぼし、多くの場合、モデルのトレーニングは失敗します。イベントが重複していると、指標の値に誤りが生じます。 |
|
取り込まれるイベントのタイプごとに 100 個以上のユニーク ユーザー ID を含みます。 |
これにより、小売業向け Vertex AI Search は高品質な結果を生成するのに十分なデータを確保します。 |
|
|
訪問者 ID は、イベントのインポートまたはイベントの記録全体で、また API リクエストでも、まったく同じ形式にする必要があります。 |
訪問者 ID に一貫した形式を使用すると、訪問者のパターンを正しく識別し、ユーザーの行動に基づいてより良い結果を提供できます。 |
|
|
イベントに含まれるプロダクトは、プロダクトのカタログに存在する必要があります。 |
未結合イベントの比率はできるだけ低くする必要があります。この比率が高いと、レコメンデーションや検索結果の品質に悪影響を与える可能性があります。 未結合のイベントデータは、モデルのトレーニングには使用されません。ただし、未結合のイベントは、関連する商品の取り込み後に、後で結合できます。詳しくは、ユーザー イベントに再結合するをご覧ください。 |
|
|
ユーザー イベントによっては、同じ訪問者 ID を使用する必要があります。 |
有効な動作シーケンスの履歴を作成するには、小売業向け Vertex AI Search が同じ訪問者 ID を持つ複数のイベントを参照できる必要があります。
たとえば、 |
|
detail-page-view |
イベントごとに 1 つのプロダクトのみを含めます。 |
プロダクトが存在しない場合、イベントは使用できません。複数のプロダクトが指定されている場合、イベントは不正な形式のため使用できません。 |
add-to-cart |
イベントごとに 1 つのプロダクトのみを含めます。 |
複数のプロダクトが含まれている場合、イベントは不正な形式になり、使用できません。 |
purchase-complete |
|
|
|
すべての購入イベントで 1 つの デフォルトの通貨コードはありません。コードを指定する必要があります。 |
このフィールドのない購入イベントでは、収益指標が正しくありません。 |
|
|
一部の購入イベントに複数のプロダクトが含まれていることを確認します。 |
一部の購入イベントには複数のプロダクトがあるため、モデルで共同購入パターンを学習できます。 |
レコメンデーション固有の要件
レコメンデーションを使用している場合は、ユーザー イベントが次の要件を満たしていることを確認します。
レコメンデーション を使用する場合は、モデルタイプ データの要件もご覧ください。使用する予定の最適化案モデルのタイプと最適化目標に応じた追加の要件が示されています。
| イベントタイプ | 要件 | 影響 |
|---|---|---|
purchase-complete |
複数アイ入った入ったカートを複数の購入イベントに平たん化しないでください。つまり、複数のプロダクトが含まれる 1 つの購入イベントとして残す必要があります。 |
これにより、有効な共同購入パターンが生成されます。 |
検索の要件
検索を使用している場合は、結果を取得するためにユーザー イベントが次の最小要件を満たしていることを確認します。
| イベントタイプ | 要件 | 影響 |
|---|---|---|
search |
検索イベントの場合は |
このフィールドを含めないと、検索結果の品質と指標に重大な悪影響が生じる可能性があります。 |
|
検索リクエスト内のユーザー ID は、その検索リクエストに関連するイベントで送信されるユーザー ID と一致する必要があります。 |
一致しない場合、イベントの形式が不正確になり、指標が不正確になる可能性があります。 |
|
|
検索イベントのプロダクト ID のリストは、ユーザーに表示されるプロダクト全体のリストと一致する必要があります。 |
一致しない場合、検索結果の品質に悪影響がおよび、指標が不正確になる可能性があります。 |
|
|
検索でフィルタを使用する場合は、 |
このフィールドが存在しない場合、小売業向け Vertex AI Search はデータのフィルタ部分を使用できないため、検索結果の品質に悪影響を及ぼす可能性があります。 |
|
|
他のイベントを検索イベントにリンクし直すには、 |
検索トークンを含めないと、検索の品質と指標の精度に重大な悪影響を及ぼします。 |
検索の最適化の要件
検索が全体的なユーザーの傾向に基づいて検索エクスペリエンスを自動的に最適化できるようにするには、次のデータをアップロードします。
イベントは少なくとも 1 日 1 回、最大24 時間の遅延でアップロードする必要があります。
| イベント指標 | イベントの量/頻度 | 説明 |
|---|---|---|
search イベントの量 |
過去 90 日間で 2,000,000 |
取り込まれたイベントに基づいて検索エクスペリエンスを最適化するには、過去 90 日間で 200 万以上のイベントが必須です。
良好なデータ品質を維持するため、イベントを少なくとも 1 日 1 回アップロードすることをおすすめします。過去のイベントのインポート中に、データの分布が最新のタイムスタンプに偏っていることを確認します。最後のタイムスタンプの日付のイベント数は、1 日の平均イベント数以上である必要があります。 |
search イベントに起因する detail-page-view の量 |
過去 30 日間で 500,000 | ユーザー イベントを使用して検索結果を最適化するには、500,000 件以上のイベントが必須です。 |
プロダクトごとに search イベントに起因する平均 detail-page-view イベント |
過去 30 日間で 10 | 過去 21 日間のイベントがアップロードされていない限り、取り込まれたイベントを使用して検索結果を最適化するために必須です。 |
解析可能なフィルタを使用した search イベントの割合 |
過去 30 日間で 0.1 | 検索レスポンスの動的ファセットの順序を最適化することをおすすめします。 |
| 検索されたプロダクトの比率（価格） | 過去 30 日間で 0.95 | 取り込まれたイベントを使用して検索結果を最適化するために必須です。 |
有料プロダクトごとに search イベントに起因する平均 add-to-cart イベント |
過去 30 日間で 0.5 | 収益最適化の検索結果に推奨されます。 |
検索可能な有料プロダクトごとに search イベントに起因する平均 purchase-complete イベント |
過去 30 日間で 0.5 | 収益最適化の検索結果に推奨されます。 |
検索のカスタマイズの要件
検索では、アクティビティに基づいてユーザーのテキスト検索とブラウジング検索の結果をカスタマイズするために、次のデータが必要です。
次のデータをアップロードすると、検索で結果が自動的にカスタマイズされます。
| イベント指標 | イベントの量/頻度 | 説明 |
|---|---|---|
検索によって提供された search イベントの量 |
過去 30 日間で 100,000 |
カスタマイズを提供するには、過去 30 日間に検索によって処理される 100,000 件以上のイベントが必要です。
|
| 検索結果はキャッシュに保存されません | 直近の 100,000 件のユーザー イベントの 1% 未満 |
カスタマイズを使用する予定がある場合、テキスト検索やブラウジング検索の検索結果をキャッシュに保存しないでください。同じ検索結果をユーザー間で再利用することで、検索が忠実にカスタマイズされた結果を任意のユーザーに提供できなくなり、ユーザーの個人データが漏洩するリスクがなくなります。キャッシュが検出された場合、検索はカスタマイズを自動的にオフにします。 検索結果のみをキャッシュに保存した場合でも、検索はブラウジングの結果をカスタマイズできます。逆に、ブラウジング結果のみをキャッシュに保存する場合でも、検索はテキストクエリの検索結果をカスタマイズできます。 |
SearchRequests とユーザー イベント間の訪問者 ID の一致 |
直近の 100,000 件のユーザー イベントに一致するものが 10% 以上 |
訪問者 ID の間隔と形式が、SearchRequests とユーザー イベント間で一致していることを確認します。一貫した訪問者 ID の形式によって、検索はユーザーのアクティビティを正しく識別できます。
|
ユーザー イベントタイプの例とスキーマ
このセクションでは、サポートされている各イベントタイプのデータ形式について説明します。
JavaScript Pixel とタグ マネージャーの例が用意されています。BigQuery の場合、各タイプのテーブル スキーマ全体が用意されています。
すべてのユーザー イベントタイプでは、userId は省略可能です。プロダクト情報のフィールド（priceInfo と availability）は省略可能です。
次のことに注意してください。
experimentIds項目は、A/B テストを実行する場合にのみ必要です。attributionToken項目は省略可能です。パフォーマンスを測定するために使用されます。クリックから生成されたpredict、search、detail-page-viewのイベントには、イベントを生成した検索や最適化案にリンクするための属性トークンが必要です。- 特に Google Cloud コンソールを使用して収益指標を取得する予定がある場合は、すべてのイベントで単一の通貨が使用されていることを確認してください。小売業向け Vertex AI Search API では、カタログごとに複数の通貨を使用することはできません。
ユーザー イベント オブジェクトの詳細については、UserEvent API リファレンス ドキュメントをご覧ください。
カートに追加
add-to-cart ユーザー イベントの形式は、次のとおりです。
最低限必要な add-to-cart オブジェクト
次の例は、add-to-cart ユーザー イベント形式の必須項目のみを示しています。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "add-to-cart",
"visitorId": "visitor-id",
"productDetails": [{
"product": {
"id": "product-id"
},
"quantity": product-quantity
}]
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'add-to-cart',
'visitorId': 'visitor-id',
// You can also define the visitor ID
// directly on the Tag Manager tag.
'productDetails': [{
'product': {
'id': 'product-id'
},
'quantity': product-quantity
}]
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
},
{
"name": "cartId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
カテゴリ ページビュー
category-page-view ユーザー イベントの形式は、次のとおりです。
最低限必要な category-page-view オブジェクト
次の例は、category-page-view ユーザー イベント形式の必須項目のみを示しています。
通常、ページに関連付けられるカテゴリは 1 つのみですが、pageCategories 項目ではカテゴリ階層もサポートし、それをリストとして指定できます。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "category-page-view",
"visitorId": "visitor-id",
"pageCategories": ["category1 > category2"]
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'category-page-view',
'visitorId": 'visitor-id',
// You can also define the user ID and visitor ID
// directly on the Tag Manager tag.
'pageCategories': ['category1 > category2']
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
詳細ページ表示
detail-page-view ユーザー イベントのデータ形式は、次のとおりです。
最低限必要な detail-page-view オブジェクト
次の例は、detail-page-view ユーザー イベント形式の必須項目のみを示しています。
ほとんどの場合、productDetails は、プロダクトをバンドルしてまとめて販売しない限り、関連付けられたプロダクトの詳細を含みます。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "detail-page-view",
"visitorId": "visitor-id",
"productDetails": [{
"product": {
"id": "product-id"
}
}]
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'detail-page-view',
'visitorId': 'visitor-id',
// You can also define the visitor ID directly on
// the Tag Manager tag.
'productDetails': [{
'product': {
'id': 'product-id'
}
}]
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
ホームページ表示
home-page-view ユーザー イベントの形式は、次のとおりです。
最低限必要な home-page-view オブジェクト
次の例は、home-page-view ユーザー イベント形式の必須項目のみを示しています。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "home-page-view",
"visitorId": "visitor-id",
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'home-page-view',
'visitorId': 'visitor-id'
// You can also define the visitor ID
// directly on the Tag Manager tag.
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
購入完了
purchase-complete ユーザー イベントのデータ形式は、次のとおりです。
最低限必要な purchase-complete オブジェクト
次の例は、purchase-complete ユーザー イベント形式の必須項目のみを示しています。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "purchase-complete",
"visitorId": "visitor-id",
"productDetails": [{
"product": {
"id": "product-id"
},
"quantity": product-quantity
}],
"purchaseTransaction": {
"revenue": revenue,
"currencyCode": "currency-code"
}
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'purchase-complete',
'visitorId': 'visitor-id',
// You can also define the visitor id directly on
// the Tag Manager tag.
'productDetails': [{
'product': {
'id': 'product-id'
},
'quantity': product-quantity
}],
'purchaseTransaction': {
'revenue': revenue,
'currencyCode': 'currency-code'
}
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "priceInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "price",
"type": "FLOAT",
"mode": "REQUIRED"
},
{
"name": "originalPrice",
"type": "FLOAT",
"mode": "NULLABLE"
},
{
"name": "currencyCode",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "cost",
"type": "FLOAT",
"mode": "NULLABLE"
}
]
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
},
{
"name": "cartId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "revenue",
"type": "FLOAT",
"mode": "REQUIRED"
},
{
"name": "tax",
"type": "FLOAT",
"mode": "NULLABLE"
},
{
"name": "cost",
"type": "FLOAT",
"mode": "NULLABLE"
},
{
"name": "currencyCode",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
検索
search ユーザー イベントの形式は、次のとおりです。
最低限必要な search オブジェクト
次の例は、search ユーザー イベント形式の必須項目のみを示しています。
searchQuery または pageCategories フィールドの少なくとも 1 つは必須です。
productDetails には、エンドユーザーに検索結果ページ内に表示される商品 ID のリストを含める必要があります。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "search",
"visitorId": "visitor-id",
"searchQuery": "search-query",
"pageCategories": ["category1 > category2"],
"productDetails": [
{
"product": {
"id": "product-id1"
}
}, {
"product": {
"id": "product-id2"
}
}
]
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'search',
'visitorId': 'visitor-id',
// You can also define the visitor ID
// directly on the Tag Manager tag.
'searchQuery': 'search-query',
'pageCategories': ['category1 > category2'],
'productDetails': [
{
'product': {
'id': 'product-id1'
}
}, {
'product': {
'id': 'product-id2'
}
}
]
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
},
{
"name": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
オートコンプリート
このフィールドは、オートコンプリートを使用する場合にのみ、検索イベントに必要です。検索には必要ありません。
次の例は、ユーザーが「sh」と入力し、候補リストで 2 つ目の候補「shoes」をクリックして検索イベントをトリガーする場合の completionDetail フィールドを示しています。ユーザーが何もクリックしなかった場合、completionDetail フィールドは空のままになります。
eventType が "search" でなければなりません。
completionAttributionToken は、completeQuery レスポンスからの attributionToken です。
selectedSuggestion は searchQuery と同じである必要があります。
JavaScript Pixel
var user_event = {
"eventType": "search",
"visitorId": "visitor-id",
"searchQuery": "search-query",
"pageCategories": ["category1 > category2"],
"productDetails": [
{
"product": {
"id": "product-id1"
}
}, {
"product": {
"id": "product-id2"
}
}
]
"completionDetail": {
"completionAttributionToken": "completion_token",
"selectedSuggestion": "search-query",
"selectedPosition": completion_position
}
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'search',
'visitorId': 'visitor-id',
// You can also define the visitor ID
// directly on the Tag Manager tag.
'searchQuery': 'search-query',
'pageCategories': ['category1 > category2'],
'productDetails': [
{
'product': {
'id': 'product-id1'
}
}, {
'product': {
'id': 'product-id2'
}
}
]
"completionDetail": {
"completionAttributionToken": 'completion_token',
"selectedSuggestion": 'search-query',
"selectedPosition": completion_position
}
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
},
{
"name": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "completionDetail",
"type": "RECORD"
"mode": "NULLABLE"
"fields": [
{
"name": "completionAttributionToken",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "selectedSuggestion",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "selectedPosition",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
}
]
ショッピング カート ページビュー
shopping-cart-page-view ユーザー イベントのデータ形式は、次のとおりです。
最低限必要な shopping-cart-page-view オブジェクト
次の例は、shopping-cart-page-view ユーザー イベント形式の必須項目のみを示しています。
ショッピング カートが空でない場合は productDetails オブジェクトを指定します。
イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
使用する API メソッドが変わったり、追加のフィールドを使用したりすると、他のフィールドが必要になることがあります。（たとえば、ユーザー イベントがエンティティに関連付けられている場合は、必ず entity フィールドを指定してください）。各フィールドの詳細と必要な場合は、UserEvent API リファレンス ドキュメントをご覧ください。
JavaScript Pixel
var user_event = {
"eventType": "shopping-cart-page-view",
"visitorId": "visitor-id
"cartId": "cart-id",
"productDetails": [{
"product": {
"id": "product-id"
},
{
"id": "product-id"
}
}]
};
タグ マネージャー
<script>
dataLayer = dataLayer || [];
dataLayer.push({
'cloud_retail': {
'eventType': 'shopping-cart-page-view',
'visitorId': 'visitor-id'
// You can also define the visitor ID
// directly on the Tag Manager tag.
'cartId': 'cart-id',
'productDetails': [{
'product': {
'id': 'product-id'
},
{
'id': 'product-id'
}
}]
}
});
</script>
BigQuery
このユーザー イベントタイプの完全な JSON スキーマです。BigQuery でこのユーザー イベント タイプのテーブルを作成する場合、このスキーマを指定します。
必須項目のモードが REQUIRED または REPEATED に設定されています。省略可能な項目のモードは NULLABLE に設定されています。
BigQuery でイベントをインポートするには、eventTime が必要です。eventTime は、タイムスタンプ形式の文字列です。
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "experimentIds",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "attributionToken",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
},
{
"name": "cartId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userInfo",
"type": "RECORD",
"mode": "NULLABLE",
"fields": [
{
"name": "userId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "ipAddress",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "userAgent",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "directUserRequest",
"type": "BOOLEAN",
"mode": "NULLABLE"
}
]
},
{
"name": "uri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "referrerUri",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageViewId",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "entity",
"type": "STRING",
"mode": "NULLABLE"
}
]
Google アナリティクス 4 のユーザー イベント フィールド
次の表は、Google アナリティクス 4 のユーザー イベント フィールドが 小売業向け Vertex AI Search のフィールドにどのようにマッピングされるかを示しています。
Google アナリティクス 4 からユーザー イベントをインポートまたは記録する前に、小売業向け Vertex AI Search がデータを正しく統合できるように、Google アナリティクス 4 のユーザー イベントで次のフィールドを使用していることを確認してください。
| Google アナリティクス 4 | 小売 |
|---|---|
ecommerce.purchase_revenue |
purchaseTransaction.revenue |
event_name |
eventType |
event_timestamp |
eventTime |
items.item_id |
productDetails.product.id |
items.price |
productDetails.product.priceInfo.price |
items.quantity |
productDetails.quantity |
キー:event_params.key を "currency" に設定値: event_params.value.string_value |
productDetails.product.priceInfo.currencyCode |
キー:event_params.key を "currency" に設定値: event_params.value.string_value |
purchaseTransaction.currencyCode |
キー:event_params.key を "search_term" に設定値: event_params.value.string_value |
searchQuery |
user_id |
userInfo.userId |
user_pseudo_id |
visitorId |
カスタム属性
ユーザー イベント用にカスタム属性と機能を追加できます。これにより、レコメンデーションを使用するときに、向上した具体的な最適化案が得られます。カスタム属性を追加するには、ユーザー イベントを記録するときに attributes を使用します。
取り込まれたユーザー イベントのカスタム属性を指定する場合は、予測リクエストに関連付けるユーザー イベントにも含めることが重要です。カスタム属性の形式は、インポートされたイベントと、予測リクエストで指定されたイベントの間で一貫している必要があります。これにより、モデルのトレーニングや予測の提供時にこれらのカスタム属性の使用が可能になり、レコメンデーションの品質向上に役立ちます。
text フィールドを使用してカスタム テキスト値を指定するか、number フィールドを使用してカスタムの数値を指定します。
たとえば、ユーザー イベントを記録するリクエストの attributes セクションを以下に示します。
"attributes": {
"user_age": {"text": ["teen", "young adult"]},
"user_location": {"text": ["CA"]}
}
ユーザー情報について
visitorId は一意のユーザー ID を表し、ユーザー イベントを記録する際に必要です。
ユーザー イベントを記録するときに表示されるユーザー情報（UserInfo）には、visitorId の値と、userId 値（使用可能な場合）が含まれます。userId は省略可能で、ユーザーがサイトにログインするたびに、デバイス間で一意の永続的な識別子として使用できます。ユーザーの userId を記録すると、小売業向け Vertex AI Search は、モバイル デバイスやウェブブラウザなど、ユーザーが複数のデバイスで 1 人のユーザーに対してカスタマイズされた結果を生成できます。
タイムスタンプについて
ユーザー イベントを記録する際は、イベントが発生した正確なタイムスタンプを必ず含めるようにしてください。正確なタイムスタンプによって、イベントが正しい順序で保存されます。タイムスタンプは、タグ マネージャーと JavaScript Pixel を使用して収集されたイベントに対して自動的に記録されます。イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。
次のステップ
- 詳しくは、ユーザー イベントを記録する方法をご覧ください。