Registra eventos de usuario en tiempo real

En esta página, se describe cómo registrar eventos de usuario en tiempo real. Los eventos de usuario son obligatorios para las apps de contenido multimedia. Si no usas apps de contenido multimedia, no es necesario importar eventos de usuario. Sin embargo, se recomienda registrar eventos de usuario para las apps de búsqueda y recomendaciones personalizadas.

Para conocer los tipos de eventos de usuario que puedes registrar, consulta el eventType campo del userEvents objeto. Si ingieres eventos de usuario, puedes mejorar la calidad de tus resultados. Por ejemplo, los eventos de usuario afectan la clasificación de los resultados de la búsqueda. Los resultados con tasas de clics más altas se potencian, mientras que los resultados con tasas de clics más bajas se ocultan. No registres eventos de usuario para documentos que aún no hayas importado.

Si usas una app con varios almacenes de datos adjuntos, ingiere eventos de usuario a nivel de la ubicación en lugar de a nivel del almacén de datos. Esto permite que un evento de usuario determinado se envíe al almacén de datos con el que está asociado. Cuando registres eventos de usuario a nivel de la ubicación, debes incluir el campo engine en los eventos de usuario para asociar el evento con la app correcta. Para ver ejemplos de eventos de usuario que incluyen el campo engine, consulta lo siguiente:

Para importar eventos de usuario históricos de forma masiva, consulta Importa eventos de usuario históricos.

Puedes registrar eventos de usuario de las siguientes maneras:

Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la referencia de la API.

Antes de comenzar

Antes de importar eventos de usuario, haz lo siguiente:

Registra eventos de usuario en tiempo real con un píxel de JavaScript

Para registrar eventos de usuario con un píxel de JavaScript, haz lo siguiente:

  1. Crea una clave de API para las llamadas al userEvents.collect método.
  2. Consulta el ejemplo de píxel de JavaScript para ver un ejemplo de una etiqueta de JavaScript que recopila eventos de usuario.

Crea una clave de API

Se requiere una clave de API si usas un píxel de JavaScript para recopilar eventos de usuario de los navegadores de los usuarios.

Para crear una clave de API para las llamadas al userEvents.collect método, completa los siguientes pasos:

  1. En la Google Cloud consola de, ve a la Credenciales página.

    Credenciales

  2. En la lista de proyectos en la parte superior de la Google Cloud página de la consola de, selecciona tu proyecto (es posible que el proyecto ya esté seleccionado).

  3. Haz clic en Crear credenciales y selecciona Clave de API. No agregues ninguna restricción del referente. Algunas configuraciones de privacidad del usuario no pasan la URL del referente.

    • Toma nota de la clave de API generada, que usarás cuando llames al registro de eventos del usuario.

  4. Para obtener mayor seguridad, agrega una restricción de HTTP a tu clave de API para restringir el acceso al servicio de Agent Search en https://discoveryengine.googleapis.com/*.

Ejemplo de píxel de JavaScript

En el siguiente ejemplo, se registra un evento de usuario view-item mediante un píxel de JavaScript.

Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la referencia de la 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 eventos de usuario en tiempo real con el método userEvents.write

REST

Puedes usar el userEvents.write método para enviar eventos de usuarios directamente a la API desde tu servidor de backend.

Para registrar eventos de usuario, envía una solicitud POST al método userEvents.write y proporciona el cuerpo de la solicitud correspondiente. Para obtener la representación JSON de los eventos de usuario, consulta userEvents en la referencia de la API.

Si registras eventos de usuario a nivel de la ubicación, usa el extremo 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#

Para obtener más información, consulta la documentación de referencia de la API de Agent SearchC#.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Para obtener más información, consulta la documentación de referencia de la API de GoAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 


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

Para obtener más información, consulta la documentación de referencia de la API de JavaAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Para obtener más información, consulta la documentación de referencia de la API de PythonAgent Search.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

# 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

Para obtener más información, consulta la documentación de referencia de la API de Agent SearchRuby.

Para autenticarte en Agent Search, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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