これは Recommendations AI のみに関するドキュメントです。制限付き一般提供フェーズで Retail Search と統合された Retail コンソールを試すには、Cloud 営業担当者にお問い合わせください。Retail Search を使用する予定がない場合は、通知があるまで引き続き Recommendations コンソールを使用してください。

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

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

このセクションでは、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 を使用します。

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 フィールドにタイムスタンプを指定する必要があります。

次のステップ