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

このページでは、ユーザーイベントをリアルタイムで記録する方法について説明します。メディアレコメンデーションにはユーザーイベントが必要です。メディアレコメンデーションを使用していない場合は、ユーザーイベントのインポートは必要ありません。ただし、メディア検索アプリではユーザーイベントの記録をおすすめします。

記録できるユーザーイベントのタイプについては、userEvents オブジェクトの eventType フィールドをご覧ください。ユーザーイベントを取り込むことで、レコメンデーションの品質と検索結果のランキングを改善できます。クリック率が高い結果はブーストされ、クリック率が低い結果は非表示になります。まだインポートしていないドキュメントのユーザーイベントを記録しないでください。

複数のデータストアが接続された検索アプリを使用している場合は、データストアレベルではなく、ロケーションレベルでユーザーイベントを取り込むことをおすすめします。これにより、特定のユーザーイベントを、関連付けられているデータストアに送信できます。データストアレベルではなくロケーションレベルで、異なる dataStores からのドキュメントを含むユーザーイベントを取り込むには、userEvents.write をご覧ください。

過去のユーザーイベントを一括でインポートするには、過去のユーザーイベントをインポートするをご覧ください。

ユーザーイベントは次の方法で記録できます。

JavaScript ピクセルを使用する。
userEvents.write メソッドを使用する。

ユーザーイベントの JSON 表現については、API リファレンスの userEvents をご覧ください。

始める前に

ユーザーイベントをインポートする前に:

データストアとアプリを作成します。
ユーザーイベントの要件については、ユーザーイベントについてをご覧ください。

JavaScript ピクセルでリアルタイムのユーザーイベントを記録する

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

userEvents.Collect メソッドの呼び出し用の API キーを作成する
ユーザーイベントを収集する JavaScript タグの例については、JavaScript ピクセルの例をご覧ください。

API キーを作成する

JavaScript ピクセルを使用してユーザーのブラウザからユーザーイベントを収集する場合は、API キーが必要です。

userEvents.Collect メソッド呼び出し用の API キーを作成するには、次の手順を行います。

Google Cloud コンソールで、[認証情報] ページに移動します。

[認証情報] ページに移動
Google Cloud コンソールページの上部にあるプロジェクトのプルダウンで、プロジェクトを選択します（プロジェクトがすでに選択されている可能性もあります）。
[認証情報を作成] をクリックして [API キー] を選択します。 リファラー制限を追加しないでください。一部のユーザーのプライバシー設定は、参照 URL を渡さないことがわかっています。
- 生成された API キーをメモします。このキーは、ユーザーイベントロギングを呼び出すときに使用します。
セキュリティを強化するには、API キーに HTTP 制限を追加して、https://discoveryengine.googleapis.com/* での Vertex AI Agent Builder サービスへのアクセスを制限します。

JavaScript ピクセルの例

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

ユーザーイベントの JSON 表現については、API リファレンスの userEvents をご覧ください。

<script type="text/javascript">
var user_event = {
  "eventType" : "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "userInfo": {
      "userId": "USER_ID"
  },
  "attributionToken": "ATTRIBUTION_TOKEN",
  "tagIds": "TAG_ID",
  "documents": [
      {
        "id": "DOCUMENT_ID"
      }
  ]
};

var _gre = _gre || {};
// Credentials for project.
_gre.apiKey = '[API_KEY]';
_gre.logEvent = user_event;
_gre.projectId = 'PROJECT_ID';
_gre.locationId = 'LOCATION_ID';
_gre.dataStoreId = 'DATA_STORE_ID';

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

</script>

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

REST

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

ユーザーイベントを記録するには、userEvents.write メソッドに POST リクエストを送信し、適切なリクエスト本文を指定します。ユーザーイベントの JSON 表現については、API リファレンスの userEvents をご覧ください。

複数のデータストアがあるアプリの場合は、ロケーションレベルでイベントをインポートすることをおすすめします。この場合は、エンドポイント https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:write を使用します。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'view-item',
         'userPseudoId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'tagIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'documents': [{
            'id': 'abc'
          }],
         'userInfo': {
           'userId': 'abc',
           'userAgent': 'Mozilla/5.0'
         },
         'pageInfo': {
          'uri': 'http://example',
          'referrerUri': 'http://example',
          'pageViewId': 'currentPageUri'
        }
}" \\
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:write"

C#

詳細については、Vertex AI Agent Builder C# API のリファレンスドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

using Google.Cloud.DiscoveryEngine.V1;

public sealed partial class GeneratedUserEventServiceClientSnippets
{
    /// <summary>Snippet for WriteUserEvent</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void WriteUserEventRequestObject()
    {
        // Create client
        UserEventServiceClient userEventServiceClient = UserEventServiceClient.Create();
        // Initialize request argument(s)
        WriteUserEventRequest request = new WriteUserEventRequest
        {
            ParentAsDataStoreName = DataStoreName.FromProjectLocationDataStore("[PROJECT]", "[LOCATION]", "[DATA_STORE]"),
            UserEvent = new UserEvent(),
            WriteAsync = false,
        };
        // Make the request
        UserEvent response = userEventServiceClient.WriteUserEvent(request);
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンスドキュメントをご覧ください。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewUserEventClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.WriteUserEventRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#WriteUserEventRequest.
	}
	resp, err := c.WriteUserEvent(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンスドキュメントをご覧ください。

import com.google.cloud.discoveryengine.v1.DataStoreName;
import com.google.cloud.discoveryengine.v1.UserEvent;
import com.google.cloud.discoveryengine.v1.UserEventServiceClient;
import com.google.cloud.discoveryengine.v1.WriteUserEventRequest;

public class SyncWriteUserEvent {

  public static void main(String[] args) throws Exception {
    syncWriteUserEvent();
  }

  public static void syncWriteUserEvent() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (UserEventServiceClient userEventServiceClient = UserEventServiceClient.create()) {
      WriteUserEventRequest request =
          WriteUserEventRequest.newBuilder()
              .setParent(
                  DataStoreName.ofProjectLocationDataStoreName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]")
                      .toString())
              .setUserEvent(UserEvent.newBuilder().build())
              .setWriteAsync(true)
              .build();
      UserEvent response = userEventServiceClient.writeUserEvent(request);
    }
  }
}

Python

詳細については、Vertex AI Agent Builder Python API のリファレンスドキュメントをご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_write_user_event():
    # Create a client
    client = discoveryengine_v1.UserEventServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.WriteUserEventRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.write_user_event(request=request)

    # Handle the response
    print(response)

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンスドキュメントをご覧ください。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the write_user_event call in the UserEventService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::UserEventService::Client#write_user_event.
#
def write_user_event
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::UserEventService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::WriteUserEventRequest.new

  # Call the write_user_event method.
  result = client.write_user_event request

  # The returned object is of type Google::Cloud::DiscoveryEngine::V1::UserEvent.
  p result
end