この Recommendations AI ドキュメントでは、Recommendations コンソールについて説明します。Retail コンソールに切り替え、Retail ドキュメントを使用することをおすすめします。このドキュメントでは、Recommendations AI、Retail コンソール、Retail Search について説明しています。

Recommendations AI の v1beta バージョンを使用している場合は、Retail API バージョンに移行してください。

ユーザー イベント

このページでは、ユーザー イベントタイプの見込みのリストを含むユーザー イベント オブジェクトについて説明し、すべてのユーザー イベントタイプのサンプルデータを提供します。

ユーザー イベントの記録については、リアルタイム ユーザー イベントの記録をご覧ください。

ユーザー イベントタイプ

ユーザーが販売店サイトを閲覧する際に記録できるユーザー イベントには、次のようないくつかの種類があります。

ユーザー イベント名 ユーザーの操作
add-to-cart 商品をカートに追加
category-page-view セールページやプロモーション ページなどの特別なページを表示する
detail-page-view 商品の詳細ページを表示する
home-page-view ホームページを表示する
purchase-complete 購入手続きを完了する
検索 カタログを検索する
shopping-cart-page-view ショッピング カートを表示する

UserEvent オブジェクトの詳細については、UserEvent をご覧ください。

イベントタイプの優先度

最適なレコメンデーションのためには、すべてのイベントタイプのユーザー イベントを記録することをおすすめします。次の表に、さまざまなユーザー イベントタイプの優先度を示します。品質の高いデータモデルを実現するには、優先度が最も高いユーザー イベントをログに記録する必要があります。

優先度 ユーザー イベント
最初のライブテストに必要

add-to-cart

detail-page-view

home-page-view

purchase-complete
時間とともにモデルの品質を向上させるうえで重要

category-page-view

search

shopping-cart-page-view

ユーザー イベントの要件とベスト プラクティス

ユーザー イベントが次の要件を満たして、Retail API が高品質の結果を生成できるようにします。

また、Recommendations AI モデルを使用する場合は、ユーザー イベント データの要件もご覧ください。使用する予定のレコメンデーション モデルのタイプと最適化目標に応じた追加の要件を示しています。

イベントタイプ 要件 影響
すべてのイベント

重複するイベントは含めないでください。

イベントが重複していると、指標の値に誤りが生じ、モデルの品質に悪影響を与える可能性があります。

取り込まれるイベントのタイプごとに 100 個以上のユニーク ユーザー ID を含みます。

これにより、Retail API は十分な品質のデータを生成できるようになります。

Product.name フィールドはすべてのプロダクトに必須です。リソース名の最後のコンポーネントであるプロダクト ID ではなく、プロダクトの完全なリソース名を使用します。

Product.name フィールドのないプロダクトを含むイベントは、Retail API では使用できません。

イベントに含まれるプロダクトは、プロダクトのカタログに存在する必要があります。

未結合イベントの比率はできるだけ低くする必要があります。この比率が高いと、レコメンデーションや検索結果の品質に悪影響を与える可能性があります。
detail-page-view

イベントごとに 1 つのプロダクトのみを含めます。

プロダクトが存在しない場合、イベントは使用できません。複数のプロダクトが指定されている場合、イベントは不正な形式のため使用できません。

add-to-cart

イベントごとに 1 つのプロダクトのみを含めます。

複数のプロダクトが含まれている場合、イベントは不正な形式になり、使用できません。

purchase-complete

purchase_transaction.revenue を含む。

このフィールドがない場合、収益最適化モデルは使用できません。

すべての購入イベントで 1 つの purchase_transaction.currency_code のみを含めます。

このフィールドのない購入イベントでは、収益指標が正しくありません。

複数アイ入った入ったカートを複数の購入イベントに平たん化しないでください。つまり、複数のプロダクトが含まれる 1 つの購入イベントとして残す必要があります。

これにより、有効な共同購入パターンが生成されます。

ユーザー イベントタイプの例とスキーマ

このセクションでは、Recommendations AI でサポートされる各イベントタイプのデータ形式について説明します。

JavaScript Pixel とタグ マネージャーの例が用意されています。BigQuery の場合、各タイプのテーブル スキーマ全体が用意されています。

すべてのユーザー イベントタイプでは、user-id は省略可能です。カタログ アイテムの情報項目（currencyCode、originalPrice、displayPrice、stockState）は省略可能です。指定されている場合、カタログ内の値はオーバーライドされます。

次のことに注意してください。

  • experimentIds 項目は、A/B テストを実行する場合にのみ必要です。
  • attribution-token 項目は省略可能です。推奨パフォーマンスを測定するために使用されます。詳細
  • 特に Cloud Console を使用して収益指標を取得する予定がある場合は、すべてのイベントで単一の通貨が使用されていることを確認してください。Retail API では、単一のカタログに複数の通貨を使用することはできません。

ユーザー イベント オブジェクトの詳細については、ユーザー イベントをご覧ください。

カートに追加

add-to-cart ユーザー イベントの形式は、次のとおりです。

最低限必要な add-to-cart オブジェクト

次の例は、add-to-cart ユーザー イベント形式の必須項目のみを示しています。

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": "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"
 }
]
}
]

カテゴリ ページビュー

category-page-view ユーザー イベントの形式は、次のとおりです。

最低限必要な category-page-view オブジェクト

次の例は、category-page-view ユーザー イベント形式の必須項目のみを示しています。

通常、ページに関連付けられるカテゴリは 1 つのみですが、pageCategories 項目ではカテゴリ階層もサポートし、それをリストとして指定できます。

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 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": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]

詳細ページ表示

detail-page-view ユーザー イベントのデータ形式は、次のとおりです。

最低限必要な detail-page-view オブジェクト

次の例は、detail-page-view ユーザー イベント形式の必須項目のみを示しています。

ほとんどの場合、productDetails は、プロダクトをバンドルしてまとめて販売しない限り、関連付けられたプロダクトの詳細を含みます。

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": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
}
]

ホームページ表示

home-page-view ユーザー イベントの形式は、次のとおりです。

最低限必要な home-page-view オブジェクト

次の例は、home-page-view ユーザー イベント形式の必須項目のみを示しています。

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"
}
]

購入完了

purchase-complete ユーザー イベントのデータ形式は、次のとおりです。

最低限必要な purchase-complete オブジェクト

次の例は、purchase-complete ユーザー イベント形式の必須項目のみを示しています。

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": "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": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
 {
   "name": "revenue",
   "type": "FLOAT",
   "mode": "REQUIRED"
 },
 {
   "name": "currencyCode",
   "type": "STRING",
   "mode": "REQUIRED"
 }
]
}
]

search ユーザー イベントの形式は、次のとおりです。

最低限必要な search オブジェクト

次の例は、search ユーザー イベント形式の必須項目のみを示しています。

searchQuery 項目は必須です。

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query"
};

タグ マネージャー 

<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'
      }
    });
</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": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
}
]

ショッピング カート ページビュー

shopping-cart-page-view ユーザー イベントのデータ形式は、次のとおりです。

最低限必要な shopping-cart-page-view オブジェクト

次の例は、shopping-cart-page-view ユーザー イベント形式の必須項目のみを示しています。

ショッピング カートが空でない場合は productDetails オブジェクトを指定します。

JavaScript Pixel

var user_event = {
  "eventType": "shopping-cart-page-view",
  "visitorId": "visitor-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.
        '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"
}
]

カスタム属性

ユーザー イベント用にカスタム属性と機能を追加できます。こうすることで、ユーザーにとっては、レコメンデーションの精度が向上し、より明確になる可能性があります。カスタム属性を追加するには、ユーザー イベントを記録するときに attributes を使用します。

取り込まれたユーザー イベントのカスタム属性を指定する場合は、予測リクエストに関連付けるユーザー イベントにも含めることが重要です。カスタム属性の形式は、インポートされたイベントと、予測リクエストで指定されたイベントの間で一貫している必要があります。これにより、Retail API はモデルのトレーニング時や予測の提供時にこれらのカスタム属性を使用できるため、レコメンデーションの品質向上に役立ちます。

text フィールドを使用してカスタム テキスト値を指定するか、number フィールドを使用してカスタムの数値を指定します。

たとえば、ユーザー イベントを記録するリクエストの attributes セクションを以下に示します。

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

ユーザー情報について

visitorId は一意のユーザー ID を表し、ユーザー イベントを記録する際に必要です。

ユーザー イベントを記録するときに表示されるユーザー情報（UserInfo）には、両方の userId 値が含まれます。userId は省略可能で、ユーザーがサイトにログインするたびに、デバイス間で一意の永続的な識別子として使用できます。ユーザーの userId を記録すると、Recommendations AI は、モバイル デバイスやウェブブラウザなど、ユーザーが複数のデバイスでブラウジングするサービスに基づいておすすめを生成します。

タイムスタンプについて

ユーザー イベントを記録する際は、イベントが発生した正確なタイムスタンプを必ず含めるようにしてください。正確なタイムスタンプによって、Recommendations AI が正しい順序でイベントを保存できるようになります。タイムスタンプは、タグ マネージャーと JavaScript Pixel を使用して収集されたイベントに対して自動的に記録されます。イベントをインポートする際は、RFC 3339 で指定されている形式で eventTime フィールドにタイムスタンプを指定する必要があります。

次のステップ