Registrare eventi utente in tempo reale

Questa pagina descrive come registrare gli eventi utente in tempo reale. Gli eventi utente sono obbligatori per le app di contenuti multimediali. Se non utilizzi app di contenuti multimediali, l'importazione degli eventi utente non è obbligatoria. Tuttavia, la registrazione degli eventi utente è consigliata per le app di ricerca e suggerimenti personalizzati.

Per vedere un esempio di registrazione degli eventi utente, esegui il notebook "Registra eventi utente" in uno dei seguenti ambienti:

Apri in Colab | Visualizza su GitHub

Per i tipi di eventi utente che puoi registrare, consulta il eventType campo dell' userEvents oggetto. Se esegui l'inserimento degli eventi utente, puoi migliorare la qualità dei risultati. Ad esempio, gli eventi utente influiscono sul ranking dei risultati di ricerca. I risultati con percentuali di clic più elevate vengono promossi, mentre quelli con percentuali di clic inferiori vengono nascosti. Non registrare gli eventi utente per i documenti che non hai ancora importato.

Se utilizzi un'app con più datastore collegati, inserisci gli eventi utente a livello di località anziché a livello di datastore. In questo modo, un determinato evento utente può essere inviato al datastore a cui è associato. Quando registri gli eventi utente a livello di località, devi includere il campo engine negli eventi utente per associare l'evento all'app corretta. Per esempi di eventi utente che includono il campo engine, consulta quanto segue:

• Esempi e schemi di tipi di eventi utente di app personalizzate
• Esempi e schemi di tipi di eventi utente di app di contenuti multimediali

Per importare in blocco gli eventi utente storici, consulta Importare gli eventi utente storici.

Puoi registrare gli eventi utente nei seguenti modi:

• Con un pixel JavaScript.
• Con il metodo userEvents.write.

Per la rappresentazione JSON degli eventi utente, consulta userEvents nella documentazione di riferimento dell'API.

Nota: anche il widget di ricerca registra gli eventi utente. Se aggiungi il widget a una pagina web e l'utente fa clic su un risultato di ricerca, il widget registra un evento utente view-item per quel clic.

Prima di iniziare

Prima di importare gli eventi utente:

• Crea un datastore e un'app.
• Consulta la sezione Informazioni sugli eventi utente di contenuti multimediali o Informazioni sugli eventi utente per le app personalizzate per i requisiti degli eventi utente.

Registra gli eventi utente in tempo reale con un pixel JavaScript

Per registrare gli eventi utente con un pixel JavaScript:

1. Crea una chiave API per le chiamate al userEvents.collect metodo.
2. Consulta l'esempio di pixel JavaScript per un esempio di tag JavaScript che raccoglie gli eventi utente.

Crea una chiave API

È necessaria una chiave API se utilizzi un pixel JavaScript per raccogliere gli eventi utente dai browser degli utenti.

Per creare una chiave API per le chiamate al userEvents.collect metodo, completa i seguenti passaggi:

1. Nella Google Cloud console, vai alla pagina Credenziali.

   Credenziali

2. Nell'elenco dei progetti nella parte superiore della pagina della Google Cloud console, seleziona il tuo progetto (potrebbe essere già selezionato).

3. Fai clic su Crea credenziali e poi seleziona Chiave API. Non aggiungere limitazioni relative ai referrer. Alcune impostazioni per la privacy degli utenti non trasmettono l'URL del referrer.

   • Prendi nota della chiave API generata, che utilizzerai quando chiami il logging degli eventi utente.

4. Per una maggiore sicurezza, aggiungi una limitazione HTTP alla tua chiave API per limitare l'accesso al servizio Ricerca agente a https://discoveryengine.googleapis.com/*.

Nota: la chiave API è solo per l'autenticazione del userEvents.collect metodo e del servingConfigs.searchLite metodo. Altri metodi di Ricerca agente richiedono OAuth 2.0 tramite un account di servizio o un account utente.

Esempio di pixel JavaScript

Il seguente esempio registra un evento utente view-item utilizzando un pixel JavaScript.

Per la rappresentazione JSON degli eventi utente, consulta userEvents in nella documentazione di riferimento dell'API.

<script type="text/javascript">
var user_event = {
  "eventType" : "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "projects/PROJECT_ID/locations/LOCATION_ID/collections/default_collection/engines/APP_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>

Registra gli eventi utente in tempo reale con il metodo userEvents.write

REST

Puoi utilizzare il userEvents.write metodo per inviare gli eventi utente direttamente all'API dal server di backend.

Per registrare gli eventi utente, invia una richiesta POST al metodo userEvents.write e fornisci il corpo della richiesta appropriato. Per la rappresentazione JSON degli eventi utente, consulta userEvents nella documentazione di riferimento dell'API.

Se stai registrando gli eventi utente a livello di località, utilizza l'endpoint https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:write.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/userEvents:write" \
     -d '{
         "eventType": "view-item",
         "userPseudoId": "visitor0",
         "engine": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID",
         "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"
         }
        }'

C#

Per saperne di più, consulta la documentazione di riferimento dell' API C# di Ricerca agente.

Per eseguire l'autenticazione in Ricerca agente, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell' API Go di Ricerca agente.

Per eseguire l'autenticazione in Ricerca agente, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell' API di Ricerca agente Java.

Per eseguire l'autenticazione in Ricerca agente, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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

Per saperne di più, consulta la documentazione di riferimento dell' API di Ricerca agente Python.

Per eseguire l'autenticazione in Ricerca agente, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

# 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

Per saperne di più, consulta la documentazione di riferimento dell' API di Ricerca agente Ruby.

Per eseguire l'autenticazione in Ricerca agente, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

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