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 necesarios para las recomendaciones de contenido multimedia. Si no usas recomendaciones de contenido multimedia, no es necesario importar eventos de usuario. Sin embargo, se recomienda registrar los eventos del usuario para las apps de búsqueda de contenido multimedia.

Para conocer los tipos de eventos de usuario que puedes registrar, consulta el campo eventType del objeto userEvents. Si transfieres eventos de usuario, puedes mejorar la calidad de tus recomendaciones y las clasificaciones de tus 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 los documentos que aún no hayas importado.

Si usas una app de búsqueda con varios almacenes de datos adjuntos, Google recomienda que transfieras los eventos del usuario a nivel de la ubicación en lugar de hacerlo 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. Para transferir eventos de usuarios con documentos de diferentes dataStores a nivel de la ubicación en lugar de a nivel del almacén de datos, consulta userEvents.write.

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

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, sigue estos pasos:

  1. Crea una clave de API para las llamadas al método userEvents.Collect.
  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 desde los navegadores de los usuarios.

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

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

    Credenciales

  2. En el menú desplegable del proyecto en la parte superior de la página de la consola de Google Cloud, 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. Algunos parámetros de configuración de privacidad del usuario no pasan la URL de referencia.

    • 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 Vertex AI Agent Builder en https://discoveryengine.googleapis.com/*.

Ejemplo de píxel de JavaScript

En el siguiente ejemplo, se registra un evento de usuario view-item con 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",
  "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 método userEvents.write 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 del usuario, consulta userEvents en la referencia de la API.

Si tienes una app con varios almacenes de datos, Google recomienda que transfieras eventos a nivel de la ubicación. En este caso, usa el extremo 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#

Para obtener más información, consulta la documentación de referencia de la API de C# del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas 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 Go del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas 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 Java del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas 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 Python del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas 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 Ruby del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas 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