「Retail」は「小売業向け Vertex AI Search」に名称変更されます。現在、新しいブランディングを反映するようにコンテンツの更新を進めています。

リアルタイムのユーザーイベントを記録する

このページでは、リアルタイムのユーザーイベントを記録する方法について説明します。小売業向け Vertex AI Searchl は、リアルタイムのユーザーイベントを使用してレコメンデーションと検索結果を生成します。有効な商品情報を使用してできるだけ多くの種類のユーザーイベントを記録することで、結果の品質が向上します。

このページの記録手順は、レコメンデーションと検索の両方に適用されます。データをいったん記録すると、両方のサービスでこれらのイベントを使用できるようになります。そのため、両方のサービスを使用する場合、同じデータを 2 回アップロードする必要はありません。

ユーザーイベントタイプ、すべてのタイプのサンプル JSON などのユーザーイベントの詳細については、ユーザーイベントについてをご覧ください。

以下の複数の方法で、ユーザーイベントを記録できます。

JavaScript ピクセルを使用する。
バックエンドサーバーから API にイベントを直接送信する。
タグマネージャータグを使用する。

以下のすべてのメソッドで、detail-page-view タイプのユーザーイベントを記録する例を紹介します。他のイベントタイプについては、ユーザーイベントについてをご覧ください。

過去のユーザーイベントをインポートすることもできます。モデルのトレーニングに十分なユーザーイベントデータが記録されるまでに、かなりの時間がかかる場合があります。過去のイベントからユーザーイベントデータを一括インポートすることで、初期のモデルトレーニングを高速化できます。過去のユーザーイベントをインポートするをご覧ください。

記録しているユーザーイベントが、以前に提示されたレコメンデーションや検索結果に基づいてユーザーが初めてプロダクトを操作するものである場合、アトリビューショントークンを含めることにより、パフォーマンス指標が有効になります。小売業向け Vertex AI Search を機能させるには、属性トークンを含める必要があります。アトリビューショントークンの仕組みについての情報は、アトリビューショントークンをご覧ください。

ユーザーイベントを記録するには、訪問者 ID が必要です。訪問者 ID とユーザー ID については、ユーザー情報についてをご覧ください。

ユーザーイベントの作成チュートリアル

このチュートリアルでは、userEvents.write メソッドを使用してユーザーイベントを記録する方法を説明します。

このタスクを Cloud Shell エディタで直接行う際の順を追ったガイダンスについては、[ガイドを表示] をクリックしてください。

ガイドを表示

始める前に

ユーザーイベントを記録する前に、次のことが必要です。

作成された、認証が設定された Google Cloud プロジェクト。
API を使用して直接書き込む場合は、有効な API キー（JavaScript Pixel またはタグマネージャーの場合）、または Retail 閲覧者のロールが割り当てられた有効なサービスアカウント。

詳細については、始める前にをご覧ください。

ユーザーイベントの記録に関するおすすめの方法

小売業向け Vertex AI Search では、高品質な結果を生成するために高品質なデータが必要です。データが不完全または不正確である場合、結果の品質が損なわれます。

ユーザーイベントを記録するときは、次のおすすめの方法を実施するようにしてください。

カタログのインポート前またはインポート中にユーザーイベントを記録する場合は、カタログのインポートが完了する前に記録されたイベントをすべて再結合する。

ユーザーイベントを記録する前、後、または同時に、カタログをインポートできます。カタログが大きく、ユーザーイベントが多数存在する場合、このようなタスクを同時に行うことで、時間を節約できます。カタログのインポートが完了したら、インポートが完了する前にアップロードされたイベントを再結合するために、API を使用する必要があります。

小売業向け Vertex AI Search は、ユーザーイベントの作成時に、記録されたユーザーイベントを商品カタログのメタデータと結合しようとします。トレーニングには正常に結合されたイベントのみが使用されるため、カタログが完全にインポートされる前に、記録されたイベントの再結合を確実に行ってください。イベントでカタログに存在しないアイテムを参照している場合、そのイベントは破棄されるか、正しい商品に関連付けられません。同様に、過去のユーザーイベントをインポートする場合、カタログにはユーザーイベントが参照する商品すべてを含める必要があります。カタログから以前のアイテムを削除するのではなく、古い商品を OUT_OF_STOCK としてマークできます。
カタログを最新の状態に保つ。

ユーザーイベントを記録すると、ユーザーイベントに含まれる商品は現在のカタログに関連付けられます。現在のカタログにない商品のイベントを記録する場合、モデルのトレーニングに使用できません。これは「未結合の」イベントと呼ばれます。カタログが完全にインポートされる前にイベントを記録した場合は、インポート時に記録されたイベントに再結合する必要があります。未結合のイベントがいくつかあることが想定されます。ただし、未結合イベントの割合がユーザーイベント合計の 5% 以上に達した場合は、カタログが最新であることを確認し、カタログが完全に更新される前に記録されたイベントを再結合して、未結合のイベントが作成される理由を調査してください。

未結合イベントを確認するには、イベントのフィルタリングを使用します。詳細
ユーザーイベントについて、できるだけ多くの情報を提供してください。

ユーザーイベントの種類ごとに、必要で受け入れられる情報が異なります。詳細については、ユーザーイベントについてをご覧ください。
ユーザーイベントの記録プロセスが停止した場合に把握できるように、Cloud Monitoring アラートを設定します。
ユーザーイベントの一括インポートでは、インポートするデータのサイズを制限する。

ユーザーイベントの一括インポートは最長で 24 時間かかることがあります。

各ファイルのサイズは 2 GB 以下である必要があります。1 回のインポートリクエストで最大 100 個のファイルを含めることができます。1 つの方法は、一度に 1 日分のユーザーイベントのみをインポートすることです。
一括インポートが完了したら、エラーレポートを確認して、データが正しくインポートされていることを確認する。
ユーザーイベントデータをインポートする場合は、ユーザーイベントごとに正確なタイムスタンプを含め、同一のタイムスタンプを含む連続のユーザーイベントをインポートしないようにする。

RFC 3339 で指定された形式で、eventTime フィールドにタイムスタンプを指定します。
誤ったユーザーイベントをインポートした場合は、問題をどのように修正するかについて、小売業向け Vertex AI Search の担当者にお問い合わせください。
可能であれば、ユーザーイベントのデータを継続的に保持する。

ユーザーイベントデータのずれによって、モデルの品質が低下する可能性があります。
小売業向け Vertex AI Search に対してユーザーを匿名にして、ユーザーのプライバシーを保護するために、安全な形式の一意の ID を使用してください。メールアドレスや自宅住所などの個人情報（PII）をデータから削除するのは、お客様の責任です。

JavaScript ピクセルでユーザーイベントを記録する

次の例では、JavaScript ピクセルを使用して detail-page-view UserEvent を記録しています。

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

Google アナリティクス 360 を使用してユーザーイベントをインポートした場合は、visitorID を Google アナリティクスクライアント ID に設定します。なお、Google アナリティクスクライアント ID は、完全な _ga Cookie 名の一部にすぎません（たとえば、クライアント ID 123456789.123456789 は _ga Cookie GA1.3.123456789.123456789 の一部です）。

クライアント ID の取得について詳しくは、Google アナリティクスのドキュメントをご覧ください。

次の例は、ユーザーイベントでクライアント ID を設定する形式を示す短縮例です。「G-XXXXXX」を Google アナリティクスのトラッキング ID に置き換えます。

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

`userEvents.write` メソッドを使用してユーザーイベントを記録する

userEvents.write メソッドを使用して、バックエンドサーバーから API にユーザーイベントを直接送信できます。

ユーザーイベントを記録するには、userEvents.write メソッドに POST リクエストを送信し、適切なリクエスト本文を指定します。

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Google アナリティクス 4 でユーザーイベントを記録する

Google アナリティクス 4 のユーザーイベントデータを、小売業向け Vertex AI Search に記録できます。

データソースを確認する

インポートするユーザーイベントデータの形式が正しいことを確認します。

小売業向け Vertex AI Search が使用する Google アナリティクス 4 フィールドと、それらがマッピングされる小売業向け Vertex AI Search のフィールドの表については、Google アナリティクス 4 のユーザーイベントフィールドをご覧ください。

すべての Google アナリティクスイベントパラメータについては、Google アナリティクスイベントのリファレンスドキュメントをご覧ください。

以下を確認します。

一部の小売業向け Vertex AI Search モデルで必要となる購入イベントをインポートする場合、イベントレポートに通貨コードが含まれます。Google アナリティクスドキュメントの purchase イベントパラメータをご覧ください。
search イベントをインポートする場合、イベントレポートに検索クエリが含まれます。

search イベントのインポートはサポートされますが、search イベントは他のイベントタイプと同様に Google アナリティクス 4 からマッピングされません。これは、小売向け Vertex AI Search の search イベントタイプが Google アナリティクス 4 でネイティブにサポートされていないためです。インポートの際、view_item_list イベントパラメータと search_term パラメータからの情報を組み合わせることにより、Google アナリティクス 4 から search イベントが構築されます。

Google アナリティクスドキュメントの search イベントパラメータをご覧ください。

Google アナリティクス 4 のイベントを記録する

ユーザーイベントを記録するには、userEvents.collect メソッドの呼び出しに、イベントの URL エンコードされた生の JSON データを含めます。

prebuilt_rule パラメータには、値 ga4_bq を使用します。

読みやすくするために、次の userEvents.collect 呼び出しの使用例では、まず、サンプルイベントの未加工の JSON データを含む変数として GA4_EVENT を設定します。この例の userEvents.collect 呼び出しは、GA4_EVENT 変数を使用してイベントデータを URL エンコードします。

後で URL を簡単にエンコードするために、イベントデータを含む変数として GA4_EVENT を設定できます。この例では、add-to-cart イベントを示します。

GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

ユーザーイベントの URL エンコードされた未加工の JSON データが含まれる userEvents.collect 呼び出しを実行します。

curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

Google タグマネージャーでのユーザーイベントを記録する

タグマネージャーでは、サイトへのサーバーサイドでのコード変更なしに、複数のタグを管理してテストできます。

設定中に行う決定は、Google アナリティクスと Google アナリティクス e コマースのどちらを使用しているかによって異なります。Google アナリティクス e コマースは、Google アナリティクス 4 または拡張 e コマースを使用して実装できます。Cloud Retail タグは両方をサポートしています。

Google アナリティクスと e コマースは必須ではありません。まだ使用していない場合は、Cloud Retail タグの作成時に Variable - Ecommerce を構成するか、タグを作成した後にサイトのデータレイヤーコードを手動で入力できます。

Google アナリティクス e コマースは、Google アナリティクスの追加構成であり、商品名、ID、価格、トランザクションの詳細、その他の構造化 e コマースデータを Google アナリティクスに渡します。小売業向け Vertex AI Search は、Google アナリティクス e コマースのデータレイヤーを自動的に使用できるため、すでに設定している場合は構成が容易になります。Google アナリティクスで e コマースを構成していないものの、Google アナリティクスを使用する場合は、GA4 デベロッパーガイドまたは拡張 e コマースデベロッパーガイドをご覧ください。

ユーザーイベントを記録するために、この 1 回限りの手順を使用して、タグマネージャーで Cloud Retail タグを設定します。

訪問者 ID 変数を作成する

値 visitorId は、ユーザーをトラッキングするためのものです。 visitorId は通常、セッション ID であり、すべてのイベントに必要です。セッション ID を visitorId として設定する変数を設定します。

Google アナリティクスを使用している場合は、Google アナリティクスの訪問者 ID を使用できます。これを構成するには、次の手順を使用して Cloud Retail タグの訪問者 ID 値をオーバーライドします。これにより、ファーストパーティの Cookie「_ga」が「GA visitorId」というタグマネージャーの変数にマッピングされます。どのセッション ID Cookie でも同じことができます。Google アナリティクスで行う必要はありません。

この手順は、Google アナリティクスを使用していることを前提としています。そうでない場合は、別の Cookie または変数を使用するか、cloud_retail データレイヤーからビジター ID を取得します。

Cloud Retail タグの変数に visitorID 値を設定するには:

[タグマネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。
ダイアログの先頭で、変数に「GA visitorId」などの名前を付けます。
変数の設定を入力します。

クライアント ID または Cookie ID を使用して、訪問者 ID のソースとして設定できます。過去のユーザーイベントとリアルタイムのユーザーイベントを取り込むときは、必ず一貫したユーザー ID ソースを使用してください。
クライアント ID
Google アナリティクス 360 BigQuery では、この変数はユニバーサルアナリティクス BigQuery エクスポートスキーマの clientID フィールドにマッピングされます。Google アナリティクス 4 では、この変数は Google アナリティクス 4 BigQuery エクスポートスキーマの user_pseudo_id フィールドにマッピングされます。
1. [変数タイプ] を [カスタム JavaScript] に設定します。
2. [カスタム JavaScript] フィールドに次のスクリプトを入力します。
  
  「G-XXXXXX」を Google アナリティクスのトラッキング ID に置き換えます。トラッキング ID を確認するには、トラッキング ID はどうなりますか？をご覧ください。クライアント ID の取得について詳しくは、Google アナリティクスのドキュメントをご覧ください。
  function() { var tracker = ga.getByName('G-XXXXXX'); return tracker.get('clientID'); }
3. [Save] をクリックして、変数を保存します。
Cookie ID
1. 変数のタイプとして [1st Party Cookie] を選択します。
2. [Cookie 名] フィールドに「_ga」と入力します。
3. [値のフォーマット] をクリックして、[未定義を変換] を選択し、「""」（空の文字列）を入力します。
4. [Save] をクリックして、変数を保存します。
  
  これにより、ファーストパーティの Cookie「_ga」が「GA visitorId」というタグマネージャーの変数にマッピングされます。

次に、タグマネージャーで Cloud Retail タグを作成します。このタグでは、作成した訪問者 ID 変数を使用します。

Google タグマネージャータグを作成する

ユーザーイベント情報を小売業向け Vertex AI Search に送信するようにタグマネージャーでタグを設定します。

タグマネージャーにログインし、サイトのコンテナを選択します。
[Tags] タブに移動し、[New] をクリックして新しいタグを追加します。
パネルの上部で、タグに「小売業向け Vertex AI Search」などの名前を付けます（プレースホルダはタイトルのない変数です）。
[タグの構成] をクリックし、Cloud Retail タグを選択してタグ構成パネルを開きます。
API キーを入力します。

小売業向け Vertex AI Search の設定時に作成したキーを使用します。

API キーは、Google Cloud コンソールの [API とサービス] > [認証情報] ページで入手できます。
小売業向け Vertex AI Search が有効になっている Google Cloud プロジェクトのプロジェクト番号を入力します。

プロジェクト番号は Google Cloud コンソールダッシュボードで入手できます。
[ユーザーイベントデータソース] フィールドには、次のいずれかを選択します。
- データレイヤー（推奨）: 実装が次のいずれかである場合に選択します。
  - タグマネージャーで Google アナリティクス e コマースを実装している。新しく入力する代わりに、データレイヤーをイベントデータソースとして再利用します。存在する場合、Google アナリティクス 4 スキーマが使用されます。それ以外の場合は、UA 拡張 e コマースが使用されます。このデータソースで記録できるのは、add-to-cart、purchase-complete、detail-page-view、search のイベントのみです。search イベントは、検索クエリと e コマースのインプレッション数を組み合わせて記録されます（検索クエリ変数を作成するをご覧ください）。
  - Google アナリティクスの e コマースを使用しており、データレイヤーのコードを手動で入力できます。詳しくは、タグマネージャーのデベロッパーガイドをご覧ください。
- 変数 - Cloud Retail: 小売業向け Vertex AI Search の必須フィールドを使用してタグマネージャー変数を入力するために選択します。Google アナリティクス e コマースを使用していない場合や、Google アナリティクス e コマースに小売業向け Vertex AI Search に必要なデータがない場合に、このオプションを選択できます。従来のデータレイヤー - クラウド Retail オプションからこのソースに切り替える場合は、キー cloud_retail を使用してデータレイヤー変数を作成し、この変数 - クラウド Retail オプションに関連づけます。
- 変数 - e コマース: データレイヤーで Google アナリティクス e コマースを使用していない場合で、データレイヤーコードを手動で入力できない場合に選択します。
  
  表示される [ユーザー変数から e コマースデータを読み取る] フィールドで、変数を選択します。これにより、作成したカスタム変数から小売業向け Vertex AI Search が Google アナリティクス e コマースのユーザーイベントデータを読み取ることができます。
  
  変数は、GA4 デベロッパーガイドまたは拡張 e コマースデベロッパーガイドに記載されている形式と一致している必要があります。拡張 e コマースオブジェクトビルダー、タグマネージャーコミュニティテンプレートギャラリーのカスタム変数テンプレートを使用して、正しい形式の変数を作成できます。コミュニティテンプレートは Google によって管理されていません。このテンプレートを使用するには、拡張 e コマースオブジェクトビルダーのギャラリーページでドキュメントやその他のリソースをご覧ください。
[+ Overwrite a value on the UserEvent message] ボタンをクリックします。
フィールドセレクタでは、フィールドとして visitorId を選択し、フィールド値は、訪問者 ID 変数を作成するで作成した新しい訪問者 ID 変数を選択します。
[保存] をクリックします。

Cloud Retail タグが作成されます。

従来のデータソースオプション

これまでは、データレイヤー - e コマースとデータレイヤー - Cloud Retail をデータソースオプションとして使用可能でした。これらの従来のオプションは、新しいタグでは使用できません。既存のタグを新しいデータソースに切り替える場合は、タグマネージャーでプレビューして、デプロイ前に確認します。切り替える場合:

データレイヤー - e コマースを使用した場合は、データレイヤーに切り替えることができます。存在する場合、Google アナリティクス 4 スキーマが使用されます。それ以外の場合は、UA 拡張 e コマースが使用されます。
[データレイヤー - Cloud Retail] を使用した場合は、オプション [変数 - Cloud Retail] に切り替えます。キー cloud_retail を使用してデータレイヤー変数を作成し、[変数 - Cloud Retail] オプションに関連付けます。

次は:

検索を使用している場合は、検索クエリ変数を作成して、新しいタグにアタッチします。
タグのイベントトリガーを作成します。

検索クエリ変数を作成する

検索を使用している場合は、タグマネージャーで検索クエリの変数を作成し、Cloud Retail タグにアタッチできます。これにより、小売業向け Vertex AI Search はアナリティクスから検索クエリを取得できるようになります。

作成する変数のタイプは、ユーザーイベントのデータソースによって異なります。

変数 - e コマース、または Google アナリティクス e コマーススキーマを含むデータレイヤー: タグマネージャーで URL または DOM 要素変数を作成して、Cloud Retail タグに追加します。また、Google アナリティクス e コマースインプレッションを使用して検索イベントを作成できるようタグのオプションを有効にします。
変数 - Cloud Retail、または手動で入力されたデータレイヤー: タグマネージャーで URL または DOM 要素変数を作成して、Cloud Retail タグに追加します。ユーザーイベントのタイプが search かどうかを判断するには、次のいずれかも行う必要があります。
- 検索イベントタイプ用の定数型変数を作成し、タグに追加します。
- データレイヤーまたは Cloud Retail の変数で検索イベントのタイプを設定します。

検索クエリ用のタグマネージャー変数を作成してアタッチする

検索を使用する場合は、サイトに入力された検索クエリで値が入力される URL、DOM 要素、カスタム JavaScript 変数を作成できます。

この手順の代わりに、データレイヤーを構成して検索クエリ検索クエリ情報を提供することもできます。ただし、データレイヤーにアクセスできない場合や、データレイヤーを構成したくない場合は、タグマネージャー変数を使用できます。

URL 型の変数、DOM 要素型の変数、カスタム JavaScript（ページ）変数を作成できます。作成する内容と構成方法は、サイトの実装によって異なります。

URL 変数は、サイトの検索結果 URL から検索クエリを取得します。この変数は、サイトの検索結果の URL にクエリ文字列が含まれている場合に使用します。
DOM 要素の変数は、サイトのドキュメントオブジェクトモデル（DOM）から検索クエリ情報を取得します。この変数を使用するために DOM を編集する必要はありません。ただし、この変数を正しく設定するには、DOM を読んで理解できる必要があります。
カスタム JavaScript 変数は、JavaScript 関数によってフォーマットされたデータを返します。これは、既存のデータを Cloud Retail または e コマーススキーマでフォーマットしたい場合に便利です。

まず、URL、DOM 要素、カスタム JavaScript 型のタグマネージャー変数を作成します。

[タグマネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。
ダイアログの先頭で、変数に「search_variable」などの名前を付けます。
変数の設定を入力します。
URL type
1. [変数タイプ] を [URL] に設定します。
2. [コンポーネントタイプ] を [クエリ] に設定します。
3. クエリキーを指定する場合は、URL で検索クエリの前にあるキーに設定します。
  
  たとえば、URL が http://example.com/?q=shoes の場合、クエリキーは q です。この例では、変数の値は shoes に設定されます。
DOM 要素のタイプ
1. [変数タイプ] を [DOM 要素] に設定します。
2. [選択方法] を設定し、検索クエリの要素 ID または要素セレクタを入力します。
  
  この設定は、サイトが検索クエリを識別するために要素 ID と CSS セレクタのどちらを使用するかによって異なります。
3. 属性を指定する場合は、検索クエリのキーワードを含む属性に設定します。
  
  たとえば、DOM の検索クエリが <id="search" value="shoes"> の場合、属性は value になります。この例では、変数の値は shoes に設定されます。
カスタム JavaScript タイプ
1. [変数タイプ] を [カスタム JavaScript] に設定します。
2. 次のコードの変数を置き換え、カスタム JavaScript ペインに貼り付けます。
3. [カスタム JavaScript] ペインで、検索イベントを返す JavaScript コードを [Retail スキーマ] に追加します。
  
  次のサンプルコードは、既存の Ecommerce Items 変数のデータを小売業向け Vertex AI Search スキーマで使用される productDetails 配列に変換し、完全なイベントを返します。このコードを使用するには、タグマネージャーの実装で Ecommerce Items、Search Query、Search Filter を変数に置き換えます。
  function () { var retail; var items = []; for (var i = 0; i < {{Ecommerce Items}}.length; i++) { var item = {'product': { 'id': {{Ecommerce Items}}[i].item_id } }; items.push(item); } retail = { 'eventType': 'search', 'searchQuery': '{{Search Query}}', 'filter': '{{Search Filter}}', 'productDetails': items } return retail; }
[Save] をクリックして、変数を保存します。

次に、この変数を Cloud Retail タグに追加します。

[タグマネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。
タグのユーザーイベントデータソースが変数 - e コマースである場合、または Google アナリティクス e コマーススキーマでデータレイヤーを使用している場合は、[拡張 e コマースインプレッションを使用して検索イベントを作成する] チェックボックスをオンにします。

これにより、小売業向け Vertex AI Search は、このタグから取得した検索データに基づいて、ユーザーイベントのタイプが search かどうかを判断できます。
[ユーザーイベントデータ] セクションで、+ UserEvent メッセージの値を上書きするボタンをクリックします。
[フィールドセレクタ] から searchQuery を選択し、検索クエリ変数を「フィールド値」として設定します。
タグを保存します。

次は:

Cloud Retail タグのユーザーイベントソースとして Cloud Retail 変数または手動で入力したデータレイヤの使用を選択した場合は、定数変数を作成して接続するをご覧ください。
タグのイベントトリガーを作成します。

定数変数を作成して接続する

この手順は、Cloud Retail タグのユーザーイベントの発生元として [変数 - Cloud Retail] または手動で入力したデータレイヤーを選択した場合に使用できます。

検索イベント用に定数型変数を作成し、Cloud Retail タグのユーザーイベントオーバーライドとして設定すると、小売業向け Vertex AI Search はユーザーイベントの型が search かどうかを判断できます。

この手順の代わりに、タグのイベントソースとして使用しているデータレイヤーまたは Cloud Retail 変数を使用して search ユーザーイベントタイプを指定することもできます。それ以外の場合は、次の手順を使用してイベントタイプを設定します。

まず、定数型変数を作成します。

[タグマネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。
ダイアログの先頭で、変数に「search_constant」などの名前を付けます。
[変数タイプ] を [定数] に設定します。
[Value] フィールドに「search」を入力します。
[Save] をクリックして、変数を保存します。

次に、この変数を Cloud Retail タグに追加します。

[タグマネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。
[ユーザーイベントデータ] セクションで、+ UserEvent メッセージの値を上書きするボタンをクリックします。
[フィールドセレクタ] から eventType を選択し、検索クエリ変数を「フィールド値」として設定します。
タグを保存します。

次に、タグのイベントトリガーを作成します。

タグマネージャータグのイベントトリガーを作成する

小売業向け Vertex AI Search モデルが使用するすべてのユーザーイベントタイプのトリガーを作成します。

タグマネージャータグには、サイト上でタグを呼び出すタイミングを制御するトリガーが必要です。トリガーは、イベント（ユーザーがホームページを表示する、カートに商品を追加するなど）が発生したときをリッスンし、そのユーザーイベント情報を小売業向け Vertex AI Search に送信するようにタグに指示します。

タグマネージャーには標準のトリガーがいくつか用意されています。たとえば、Window Loaded は、detail-page-view イベントのトリガーです。各タイプの詳細については、タグマネージャーのドキュメントのトリガーのタイプをご覧ください。

通常は、小売業向け Vertex AI Serach に必要なイベント（ホームページ、商品の詳細ページ、カートページ、決済手続き完了ページなど）を含むページをユーザーが閲覧するとトリガーされるタグを設定します。この場合、ページの読み込み後にタグが呼び出されるため、Cookie が有効になり、すべてのデータレイヤー変数が入力されます。これを行うには、Window Loaded または DOM Ready で呼び出すトリガーを設定します。

ページの読み込みではなくアクションが実行された場合に（たとえば、ユーザーがカートに商品を追加しても、ページが強制的に再読み込みされない場合）、タグの呼び出しが必要になる場合があります。このような場合、サイトでのクリックアクションと同時に更新がデータレイヤーに push されるよう構成し、トリガーをそのアクションに関連付けることができます。

たとえば、add-to-cart イベント用のトリガーを作成した場合、トリガータイプとして [クリック - リンクのみ] を選択して、クリック ID でトリガーを呼び出すように設定します（この例では addtocart）。次に、データレイヤーがクリック時に新しい値で更新されるようサイトに addtocart リンクを構成します。

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

ユーザーイベントによっては、カスタムトリガーを作成する必要があります。通常は、ユーザーイベント名を使用して、タグマネージャーでカスタムトリガーを作成します。フロントエンドコードを変更できない場合は、JavaScript マクロを使用して、カスタムトリガーを作成できます。カスタムトリガーの詳細については、カスタムイベントトリガーをご覧ください。

次の手順に従って、タグマネージャーでトリガーを作成します。

トリガーを設定していない場合: タグマネージャータグでの新しいトリガーを作成します。
Google アナリティクス e コマーストリガーをすでに設定している場合: 新しいトリガーを作成する代わりに、Google アナリティクス e コマース用に設定したトリガーを再利用できます。Google アナリティクスの e コマーストリガーを再利用するをご覧ください。

タグマネージャータグの新しいトリガーを作成する

Google アナリティクスの e コマースを使用しない場合は、小売業向け Vertex AI Search モデルに必要なユーザーイベントごとに新しいイベントトリガーを作成します。次に、新しいトリガーを、タグマネージャーに作成した Cloud Retail タグに関連付けます。

次の手順を開始する前に、タグマネージャーで Cloud Retail タグが作成されていることを確認します。タグマネージャータグを作成するをご覧ください。

まず、トリガーを作成します。小売業向け Vertex AI Search モデルに必要なすべてのユーザーイベントに対して、この手順を繰り返します。

[タグマネージャー] の [トリガー] ページで、[新規] > [トリガーの構成] をクリックします。
トリガーを作成するユーザーイベントに適用されるトリガータイプを選択します。
トリガーを保存します。

次に、新しいトリガーを Cloud Retail タグに関連付けます。これは 1 回限りの手順です。

[タグマネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。
[Triggering] をクリックして新しいトリガーを選択し、[Add] をクリックします。
タグを保存します。

次に、タグをプレビューし、その他の問題とイベント記録のエラーのモニタリングを設定し、データが正常に受信されるようにします。

ユーザーイベントの発生元として cloud_retail データレイヤーを使用する場合は、データレイヤーを設定することも必要です。

Google アナリティクス e コマーストリガーを再利用する

タグマネージャーを使用して Google アナリティクスの e コマースを実装している場合は、小売業向け Vertex AI Search 用の Google アナリティクス e コマースのイベントトリガーを再利用します。

このデータソースで記録できるのは、add-to-cart、purchase-complete、detail-page-view、search のイベントのみです。search イベントは、検索クエリと e コマースのインプレッション数を組み合わせて記録されます（検索クエリ変数を作成するをご覧ください）。

次の表は、Google アナリティクス e コマースイベントと拡張 e コマースイベントを小売業向け Vertex AI Search イベントにマッピングする方法を示しています。

Google アナリティクス 4	拡張 e コマース	Vertex AI Search for Retail
`add_to_cart`	`add`	`add-to-cart`
`purchase`	`purchase`	`purchase-complete`
`view_item`	`detail`	`detail-page-view`
`view_item_list` または `view_search_results`	`impressions`	`search`（フィールド `searchQuery` と組み合わせた場合）

この手順を開始する前に、最初に次のことを行います。

タグタイプが Google アナリティクス - ユニバーサルアナリティクスまたは Google アナリティクス - GA4 イベントのタグマネージャーでタグを設定し、拡張 e コマースまたは GA4 を有効にします。タグマネージャーのドキュメント、GA4 デベロッパーガイド、拡張 e コマースのデベロッパーガイドをご覧ください。
タグマネージャーで拡張 e コマースまたは GA4 タグを構成して、小売業向け Vertex AI Search 用に記録するユーザーイベントをトリガーします。
ユーザーイベントのデータソースとして「データレイヤー」または「変数 - e コマース」を使用して、タグマネージャーで Cloud Retail タグを作成します（タグマネージャータグを作成するをご覧ください）。

Google アナリティクス e コマーストリガーを再利用するには:

アプリケーションのタグマネージャー、タグページ上で、Google アナリティクスの e コマースタグをクリックして、（タグタイプ Google アナリティクス - ユニバーサルアナリティクスまたはGoogle アナリティクス - GA4 イベント）編集します。
[詳細設定] > [タグの順序付け] で、拡張 e コマースまたは GA4 タグ名の起動した後に [タグを起動する] を選択します。
Cleanup タグ として Cloud Retail タグを選択します。

拡張 e コマースまたは GA4 タグ名が失敗した場合や一時停止している場合は、[Cloud Retail タグ名を呼び出さない] を選択します。
タグを保存します。

次に、タグをプレビューし、その他の問題とイベント記録のエラーのモニタリングを設定し、データが正常に受信されるようにします。

ユーザーイベントの発生元として cloud_retail データレイヤーを使用する場合は、データレイヤーを設定することも必要です。

タグマネージャーで `cloud_retail` データレイヤーを使用する

ユーザーイベントの発生元として cloud_retail データレイヤーを使用するために、タグマネージャーで Cloud Retail タグを作成した場合は、タグマネージャーのデベロッパーガイドで説明されているとおり、ソース HTML で dataLayer 変数を設定します。

データレイヤーの概要

ほとんどのタグマネージャータグでは、ユーザーやページに応じて変化するデータ（ユーザー ID や商品 ID など）が必要です。Cloud Retail タグの場合、タグマネージャーで使用できるように、そのデータをデータレイヤーを介して構造化された形で公開する必要があります。

データレイヤーは、通常はサーバーサイドコードを使用するか、HTML またはテンプレートを使用してフロントエンドでページに追加する JavaScript オブジェクトです。ページがデータレイヤーで構成されている場合は、次のようなコードが含まれます。

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

このコードは、dataLayer オブジェクトを作成し、配列要素として cloud_retail 構造を割り当てます。

`cloud_retail` データレイヤーの必須フィールド

ユーザーイベントについてには、cloud_retail データレイヤーに渡す必要があるすべてのイベントタイプと必須フィールドが一覧表示されます。

サーバー側のコードまたはテンプレートに、イベントの送信元となる各ページの正しいスクリプトタグを含める必要があります。各ページで dataLayer オブジェクトを正しく設定したら、Cloud Retail タグをテストできます。

visitorId のような一部のフィールドは UserEvent メッセージでは必須ですが、データレイヤーへの入力時に利用できない場合もあります。たとえば、visitorId はユーザーの Cookie や、A/B テストフレームワークの experimentIds から得られる場合があります。ここでは、変数を使用してタグマネージャータグのフィールドを上書きします。

次のフィールドを上書きできます。

visitorId
userInfo.userId
attributionToken
experimentIds

タグマネージャーの UserEvent フィールドを上書きする方法については、タグマネージャーでの visitorID フィールドの設定をご覧ください。このページでは、visitorIdフィールドの値をユーザー定義の変数で上書きする方法について説明します。

次の例は、タグマネージャーを使用して detail-page-view UserEvent 用のページに含める必要があるデータレイヤーを示しています。

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      'attributionToken': 'attribution-token',
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

タグマネージャータグをプレビューする

タグマネージャーのプレビューモードでは、新しいタグを実際のサイトに公開する前にテストできます。

プレビューモードの詳細については、タグマネージャーのドキュメントでプレビューモードをご覧ください。

次の手順に沿って、タグが正しく呼び出されていることを確認します。

タグマネージャーの概要ページで、[Preview] をクリックします。

新しいブラウザタブでタグマネージャープレビューモードが開きます。
サイトの情報を入力し、[Start] をクリックして Tag Assistant を起動します。

現在のブラウザタブで Tag Assistant が起動し、サイトが新しいタブで開きます。
サイトで、Cloud Retail タグがトリガーされるページに移動します。
Tag Assistant により、[タグ呼び出し] セクションの [タグ] タブに Cloud Retail タグが表示されていることを確認します。
Tag Assistant で [データレイヤー] タブに移動し、cloud_retail または e コマースデータレイヤーの正しい値が表示されていることを確認します。

タグエラーを確認する

タグのプレビューで一部のフィールドが正しくない場合や欠落している場合、呼び出しがまったく行われていない場合を除きタグは通常、エラーも返します。

Search for Retail コンソールの [モニタリング] ページでエラーを確認できます。このページでは、通常はリクエスト結果にのみ表示される構文エラーを除くほとんどのエラーを記録します。

次の手順により、Chrome DevTools を使用して、構文エラーを含め、生成されたエラーをチェックできます。

Chrome ブラウザでサイトのタグマネージャーのプレビューモードを有効にして、Cloud Retail タグがトリガーされるページに移動します。
プレビューモードを開いた状態で DevTools を開き、[ネットワーク] タブをクリックします。
ページを再読み込みします。
DevTools で、userEventを検索します。

[ネットワーク] タブには、userEvent:collect イベントとそのステータスコードが表示されます。
- 200 レスポンスは、タグが適切な状態であることを示します。
- 400 エラーやイベントの赤色でのハイライト表示など、他のレスポンスは、デバッグが必要であることを示します。
イベント名をダブルクリックしてリクエストを実行し、詳細なエラー情報とともに完全なレスポンスを表示します。

たとえば、400 エラーが発生し、「visitorId が必要ですが空です」というエラーメッセージが表示される場合、visitorId が正しく設定されていません。
userEvent が呼び出されない場合は、DevTools の [Console] タブで、データレイヤーの構文エラーを確認します。

サーバーサイドタグ設定でユーザーイベントを記録する

サーバーサイドタグ設定を使用すると、多数のダウンストリームクライアントで単一のサーバー側コンテナをデプロイできます。これにより、クライアント側に信頼できる単一の情報源が作成され、多数のサーバー側コンシューマーが使用できるようになります。このアーキテクチャでは、ウェブからサーバーに負荷が移されるため、ウェブサイトのパフォーマンスを最大化したいユーザーに適しています。

サーバーサイドタグ設定のもう 1 つのメリットは、1 つのサーバー側のタグで、多数のアップストリームクライアント（ウェブとモバイルの両方など）もサポートできることです。詳しくは、サーバーサイドタグを設定するをご確認ください。

小売業向け Vertex AI Search には、独自のネイティブサーバーサイドタグが用意されています。

Cloud Retail サーバーサイドタグには、Cloud Retail ウェブタグと同様のパラメータが必要であり、これらのパラメータを受け入れます。次に例を示します。

プロジェクト番号
API キー（認証用）
visitorId や searchQuery などのキーフィールドのオーバーライド

Cloud Retail タグのサーバーバージョンとウェブバージョンの主な違いは、データソースを定義できない点です。サーバータグのデータソースは、GA4 スキーマの Google タグから送信されるデータストリームです。

Cloud Retail タグを設定する

インポート状態をモニタリングする

高品質な結果を得るには、ユーザーイベントを正常に記録することが重要です。イベント記録のエラー率をモニタリングし、必要に応じて対処する必要があります。詳細については、データアップロードの問題のアラートの設定をご覧ください。

記録したイベントを表示

Search for Retail コンソールの [データ] ページの [イベント] タブでイベント統合指標を表示します。このページには、去年に書き込みまたはインポートされたすべてのイベントが表示されます。データの取り込みが成功した後、指標が表示されるまでには、最長で 24 時間かかることがあります。

[データ] ページに移動

次のステップ

ユーザーイベントの詳細について確認する。
カタログのインポートが完了する前にイベントが記録された場合は、イベントを再結合する。
ユーザーイベントのインポートと管理の詳細について確認する。
予測の取得を開始する。
データアップロードプロセスをモニタリングしてトラブルシューティングする。
タグマネージャーの詳細について確認する。

リアルタイムのユーザー イベントを記録する

ユーザー イベントの作成チュートリアル

始める前に

ユーザー イベントの記録に関するおすすめの方法

JavaScript ピクセルでユーザー イベントを記録する

userEvents.write メソッドを使用してユーザー イベントを記録する

curl

Java

Google アナリティクス 4 でユーザー イベントを記録する

データソースを確認する

Google アナリティクス 4 のイベントを記録する

Google タグ マネージャーでのユーザー イベントを記録する

訪問者 ID 変数を作成する

クライアント ID

Cookie ID

Google タグ マネージャー タグを作成する

従来のデータソース オプション

検索クエリ変数を作成する

検索クエリ用のタグ マネージャー変数を作成してアタッチする

URL type

DOM 要素のタイプ

カスタム JavaScript タイプ