Merekam peristiwa pengguna real-time

Halaman ini menjelaskan cara merekam peristiwa pengguna secara real time. Peristiwa pengguna diperlukan untuk rekomendasi media. Jika Anda tidak menggunakan rekomendasi media, impor peristiwa pengguna tidak diperlukan. Namun, merekam peristiwa pengguna direkomendasikan untuk aplikasi penelusuran media.

Untuk jenis peristiwa pengguna yang dapat Anda catat, lihat kolom eventType dari objek userEvents. Dengan menyerap peristiwa pengguna, Anda dapat meningkatkan kualitas rekomendasi serta peringkat hasil penelusuran. Hasil dengan rasio klik-tayang (CTR) yang lebih tinggi akan dioptimalkan, sedangkan hasil dengan rasio klik-tayang (CTR) yang lebih rendah akan disembunyikan. Jangan rekam peristiwa pengguna untuk dokumen yang belum Anda impor.

Jika Anda menggunakan aplikasi penelusuran dengan beberapa penyimpanan data yang terpasang, Google menyarankan agar Anda menyerap peristiwa pengguna di tingkat lokasi, bukan tingkat penyimpanan data. Hal ini memungkinkan peristiwa pengguna tertentu dikirim ke penyimpanan data yang terkait. Untuk menyerap peristiwa pengguna dengan dokumen dari berbagai dataStores di tingkat lokasi, bukan tingkat penyimpanan data, lihat userEvents.write.

Untuk mengimpor peristiwa pengguna historis secara massal, lihat Mengimpor peristiwa pengguna historis.

Anda dapat mencatat peristiwa pengguna dengan cara berikut:

Untuk representasi JSON peristiwa pengguna, lihat userEvents dalam referensi API.

Sebelum memulai

Sebelum mengimpor peristiwa pengguna:

Merekam peristiwa pengguna real-time dengan piksel JavaScript

Untuk merekam peristiwa pengguna dengan piksel JavaScript:

  1. Membuat kunci API untuk panggilan ke metode userEvents.Collect
  2. Lihat Contoh piksel JavaScript untuk mengetahui contoh tag JavaScript yang mengumpulkan peristiwa pengguna

Membuat kunci API

Kunci API diperlukan jika Anda menggunakan piksel JavaScript untuk mengumpulkan peristiwa pengguna dari browser pengguna.

Untuk membuat kunci API bagi panggilan ke metode userEvents.Collect, selesaikan langkah-langkah berikut:

  1. Di Konsol Google Cloud, buka halaman Kredensial.

    Kredensial

  2. Di menu drop-down project di bagian atas halaman konsol Google Cloud, pilih project Anda (project mungkin sudah dipilih).

  3. Klik Create credentials, lalu pilih API key. Jangan tambahkan batasan perujuk. Beberapa setelan privasi pengguna tidak meneruskan URL perujuk.

    • Catat kunci API yang dihasilkan, yang akan Anda gunakan saat memanggil logging peristiwa pengguna.

  4. Untuk meningkatkan keamanan, tambahkan pembatasan HTTP ke Kunci API Anda untuk membatasi akses ke layanan Vertex AI Agent Builder di https://discoveryengine.googleapis.com/*.

Contoh piksel JavaScript

Contoh berikut mencatat peristiwa pengguna view-item menggunakan piksel JavaScript.

Untuk representasi JSON peristiwa pengguna, lihat userEvents di referensi API.

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

Merekam peristiwa pengguna real-time dengan metode userEvents.write

REST

Anda dapat menggunakan metode userEvents.write untuk mengirim peristiwa pengguna langsung ke API dari server backend.

Untuk merekam peristiwa pengguna, kirim permintaan POST ke metode userEvents.write dan berikan isi permintaan yang sesuai. Untuk representasi JSON peristiwa pengguna, lihat userEvents dalam referensi API.

Jika Anda memiliki aplikasi dengan beberapa penyimpanan data, Google merekomendasikan agar Anda mengasimilasikan peristiwa di tingkat lokasi. Dalam hal ini, gunakan endpoint 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#

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API C# Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

# 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

Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Ruby Vertex AI Agent Builder.

Untuk melakukan autentikasi ke Vertex AI Agent Builder, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

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