Registre eventos do usuário em tempo real

Nesta página, descrevemos como registrar eventos do usuário em tempo real.

Para os tipos de evento do usuário que podem ser registrados, consulte o campo eventType do objeto userEvents. Ao ingerir eventos do usuário, é possível melhorar a qualidade dos resultados. Por exemplo, os eventos do usuário afetam a classificação dos resultados da pesquisa. Os resultados com taxas de cliques mais altas são impulsionados, enquanto os resultados com taxas de cliques mais baixas são ocultados. Não registre eventos de usuário para documentos que você ainda não importou.

Se você estiver usando um app com vários repositórios de dados anexados, faça a ingestão de eventos de usuário no nível do local, em vez do nível do repositório de dados. Isso permite que um determinado evento de usuário seja enviado ao repositório de dados associado. Ao registrar eventos de usuário em um local, inclua o campo engine nos eventos para associá-los ao app correto. Para ver exemplos de eventos de usuário que incluem o campo engine, consulte:

• Exemplos e esquemas de tipos de eventos de usuário de apps personalizados

Para importar eventos históricos de usuários em massa, consulte Importar eventos históricos de usuários.

É possível registrar eventos de usuário das seguintes maneiras:

• Com um pixel JavaScript.
• Com o método userEvents.write.

Para ver a representação JSON de eventos do usuário, consulte userEvents na referência da API.

Antes de começar

Antes de importar eventos de usuário:

• Criar um repositório de dados e um app.
• Consulte Sobre eventos de usuário para ver os requisitos para eventos de usuário.

Registrar eventos do usuário em tempo real com um pixel JavaScript

Para registrar eventos do usuário com um pixel JavaScript:

1. Crie uma chave de API para chamadas ao método userEvents.collect.
2. Consulte o exemplo de pixel JavaScript para ver um exemplo de tag JavaScript que coleta eventos do usuário.

Criar uma chave de API

Uma chave de API é necessária se você usa um pixel JavaScript para coletar eventos de usuário dos navegadores dos usuários.

Para criar uma chave de API para chamadas ao método userEvents.collect, siga estas etapas:

1. No console do Google Cloud , acesse a página Credenciais.

   Credenciais

2. Na lista de projetos na parte de cima da página do console do Google Cloud , selecione seu projeto (talvez ele já esteja selecionado).

3. Clique em Criar credenciais e, em seguida, selecione Chave de API. Não adicione restrições de referenciador. Algumas configurações de privacidade do usuário não transmitem o URL de referência.

   • Anote a chave de API gerada, que será usada ao chamar o log de eventos do usuário.

4. Para aumentar a segurança, adicione uma restrição de HTTP à sua chave de API para restringir o acesso ao serviço do Gemini Enterprise em https://discoveryengine.googleapis.com/*.

Observação: a chave de API serve apenas para autenticar os métodos userEvents.collect e servingConfigs.searchLite. Outros métodos do Gemini Enterprise exigem o OAuth 2.0 por uma conta de serviço ou de usuário.

Exemplo de pixel JavaScript

O exemplo a seguir registra um evento de usuário view-item usando um pixel JavaScript.

Para ver a representação JSON de eventos do usuário, consulte userEvents na referência da 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>

Registrar eventos do usuário em tempo real com o método userEvents.write

REST

Use o método userEvents.write para enviar eventos de usuário diretamente para a API do seu servidor de back-end.

Para registrar eventos do usuário, envie uma solicitação POST para o método userEvents.write e forneça o corpo da solicitação apropriado. Para ver a representação JSON de eventos de usuário, consulte userEvents na referência da API.

Se você estiver registrando eventos de usuário no nível do local, use o 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#

Antes de testar este exemplo, siga as instruções de configuração do C# no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise C#.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Antes de testar este exemplo, siga as instruções de configuração do Go no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise Go.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

//go:build examples

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

Antes de testar este exemplo, siga as instruções de configuração do Java no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise Java.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise Python.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Antes de testar este exemplo, siga as instruções de configuração do Ruby no guia de início rápido do Gemini Enterprise: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Gemini Enterprise Ruby.

Para se autenticar no Gemini Enterprise, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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