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

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

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

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

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

• JavaScript ピクセルを使用する。

• バックエンド サーバーから API にイベントを直接送信する。

• タグ マネージャー タグを使用する。

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

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

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

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

注: 小売業向け Vertex AI Search に対してユーザーを匿名にして、ユーザーのプライバシーを保護するために、安全な形式の固有識別子を使用してください。メールアドレスや自宅住所などの個人情報（PII）をデータから削除するのは、お客様の責任です。

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

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

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

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

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

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

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

Cloud Retail タグを設定する

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

このチュートリアルでは、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 を設定する形式を示す短縮例です。「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 アナリティクスのイベント リファレンス ドキュメントをご覧ください。

以下を確認します。

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

2. 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 エンコードします。

1. 後で 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"
   }'

2. ユーザー イベントの 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 デベロッパー ガイドをご覧ください。

ユーザー イベントを記録するために、この 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 を取得します。

注: visitorID フィールドを正しく取得することが重要になります。ユーザー イベントの記録、ユーザー イベントのインポート、予測リクエストの送信において、この ID の一貫性を保つ必要があります。一貫性のない訪問者 ID を使用してもエラーは返されませんが、ユーザー イベントの履歴が不完全になり、モデルのカスタマイズの質が低下する可能性があります。

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

1. [タグ マネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。

2. ダイアログの先頭で、変数に「GA visitorId」などの名前を付けます。

3. 変数の設定を入力します。

   クライアント ID または Cookie ID を使用して、訪問者 ID のソースとして設定できます。過去のユーザー イベントとリアルタイムのユーザー イベントを取り込むときは、必ず一貫したユーザー ID ソースを使用してください。

   クライアント ID

   Google アナリティクス 4 では、この変数は Google アナリティクス 4 BigQuery エクスポート スキーマの user_pseudo_id フィールドにマッピングされます。

   1. [変数タイプ] を [カスタム JavaScript] に設定します。

   2. [カスタム JavaScript] フィールドに次のスクリプトを入力します。

      「G-XXXXXX」を Google アナリティクスのトラッキング ID に置き換えます。トラッキング ID を確認するには、トラッキング ID はどうなりますか？をご覧ください。

      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 に送信するようにタグ マネージャーでタグを設定します。

1. タグ マネージャーにログインし、サイトのコンテナを選択します。

2. [Tags] タブに移動し、[New] をクリックして新しいタグを追加します。

3. パネルの上部で、タグに「小売業向け Vertex AI Search」などの名前を付けます（プレースホルダはタイトルのない変数です）。

4. [タグの構成] をクリックし、Cloud Retail タグを選択してタグ構成パネルを開きます。

5. API キーを入力します。

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

   API キーは、Google Cloud コンソールの [API とサービス] > [認証情報] ページで入手できます。

6. 小売業向け Vertex AI Search が有効になっている Google Cloud プロジェクトのプロジェクト番号を入力します。

   プロジェクト番号は Google Cloud コンソール ダッシュボードで入手できます。

7. [ユーザー イベント データソース] フィールドには、次のいずれかを選択します。

   • データレイヤー（推奨）: 実装が次のいずれかである場合に選択します。

     • タグ マネージャーで 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 コマース オブジェクト ビルダー、タグ マネージャー コミュニティ テンプレート ギャラリーのカスタム変数テンプレートを使用して、正しい形式の変数を作成できます。コミュニティ テンプレートは Google によって管理されていません。このテンプレートを使用するには、拡張 e コマース オブジェクト ビルダーのギャラリー ページでドキュメントやその他のリソースをご覧ください。

8. [+ Overwrite a value on the UserEvent message] ボタンをクリックします。

9. フィールド セレクタでは、フィールドとして visitorId を選択し、フィールド値は、訪問者 ID 変数を作成するで作成した新しい訪問者 ID 変数を選択します。

10. [保存] をクリックします。

    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 のいずれかのタイプのタグ マネージャー変数を作成します。

1. [タグ マネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。

2. ダイアログの先頭で、変数に「search_variable」などの名前を付けます。

3. 変数の設定を入力します。

   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;
      }
      

4. [Save] をクリックして、変数を保存します。

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

1. [タグ マネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。

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

   これにより、小売業向け Vertex AI Search は、このタグから取得した検索データに基づいて、ユーザー イベントのタイプが search かどうかを判断できます。

3. [ユーザー イベント データ] セクションで、+ UserEvent メッセージの値を上書きするボタンをクリックします。

4. [フィールド セレクタ] から searchQuery を選択し、検索クエリ変数を「フィールド値」として設定します。

5. タグを保存します。

次は:

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

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

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

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

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

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

1. [タグ マネージャー] で [変数] タブに移動し、[新規] をクリックして新しいユーザー定義変数を作成します。

2. ダイアログの先頭で、変数に「search_constant」などの名前を付けます。

3. [変数タイプ] を [定数] に設定します。

4. [Value] フィールドに「search」を入力します。

5. [Save] をクリックして、変数を保存します。

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

1. [タグ マネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。

2. [ユーザー イベント データ] セクションで、+ UserEvent メッセージの値を上書きするボタンをクリックします。

3. [フィールド セレクタ] から eventType を選択し、検索クエリ変数を「フィールド値」として設定します。

4. タグを保存します。

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

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

小売業向け 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 モデルに必要なすべてのユーザー イベントに対して、この手順を繰り返します。

1. [タグ マネージャー] の [トリガー] ページで、[新規] > [トリガーの構成] をクリックします。

2. トリガーを作成するユーザー イベントに適用されるトリガー タイプを選択します。

3. トリガーを保存します。

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

1. [タグ マネージャー] の [タグ] ページで、Cloud Retail タグをクリックして編集します。

2. [Triggering] をクリックして新しいトリガーを選択し、[Add] をクリックします。

3. タグを保存します。

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

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

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

1. タグ マネージャーのタグページで、Google アナリティクスの e コマースタグ（タイプ Google アナリティクス - GA4 イベント）をクリックして編集します。

2. [詳細設定] > [タグの順序付け] で、拡張 e コマースまたは GA4 タグ名の起動した後に [タグを起動する] を選択します。

3. Cleanup タグ として Cloud Retail タグを選択します。

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

4. タグを保存します。

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

ユーザー イベントの発生元として 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フィールドの値をユーザー定義の変数で上書きする方法について説明します。

注: visitorID フィールドを正しく取得することが重要になります。ユーザー イベントの記録、ユーザー イベントのインポート、予測リクエストの送信において、この ID の一貫性を保つ必要があります。一貫性のない訪問者 ID を使用してもエラーは返されませんが、ユーザー イベントの履歴が不完全になり、モデルのカスタマイズの質が低下する可能性があります。

次の例は、タグ マネージャーを使用して 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>

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

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

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

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

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

   新しいブラウザタブでタグ マネージャー プレビュー モードが開きます。

2. サイトの情報を入力し、[Start] をクリックして Tag Assistant を起動します。

   現在のブラウザタブで Tag Assistant が起動し、サイトが新しいタブで開きます。

3. サイトで、Cloud Retail タグがトリガーされるページに移動します。

4. Tag Assistant により、[タグ呼び出し] セクションの [タグ] タブに Cloud Retail タグが表示されていることを確認します。

5. Tag Assistant で [データレイヤー] タブに移動し、cloud_retail または e コマース データレイヤーの正しい値が表示されていることを確認します。

タグエラーを確認する

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

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

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

1. Chrome ブラウザでサイトのタグ マネージャーのプレビュー モードを有効にして、Cloud Retail タグがトリガーされるページに移動します。

2. プレビュー モードを開いた状態で DevTools を開き、[ネットワーク] タブをクリックします。

3. ページを再読み込みします。

4. DevTools で、userEventを検索します。

   [ネットワーク] タブには、userEvent:collect イベントとそのステータス コードが表示されます。

   • 200 レスポンスは、タグが適切な状態であることを示します。
   • 400 エラーやイベントの赤色でのハイライト表示など、他のレスポンスは、デバッグが必要であることを示します。

5. イベント名をダブルクリックしてリクエストを実行し、詳細なエラー情報とともに完全なレスポンスを表示します。

   たとえば、400 エラーが発生し、「visitorId が必要ですが空です」というエラー メッセージが表示される場合、visitorId が正しく設定されていません。

6. userEvent が呼び出されない場合は、DevTools の [Console] タブで、データレイヤーの構文エラーを確認します。

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

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

記録したイベントを表示

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

[データ] ページに移動

次のステップ

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