Registre eventos do usuário em tempo real

Esta página descreve como registrar eventos do usuário em tempo real.

Para conferir os tipos de eventos do usuário que podem ser registrados, consulte o campo eventType do userEvents objeto. Ao ingerir eventos do usuário, você pode 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 promovidos, enquanto os resultados com taxas de cliques mais baixas são ocultados. Não registre eventos do usuário para documentos que ainda não foram importados.

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

Para importar eventos históricos do usuário em massa, consulte Importar eventos históricos do usuário.

Você pode registrar eventos do usuário das seguintes maneiras:

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

Antes de começar

Antes de importar eventos do usuário:

  • Crie um repositório de dados e um app.
  • Consulte Sobre eventos do usuário para conferir os requisitos de eventos do 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 userEvents.collect método.
  2. Consulte o exemplo de pixel JavaScript para conferir um exemplo de tag JavaScript que coleta eventos do usuário.

Criar uma chave de API

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

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

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

    Credenciais

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

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

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

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

Exemplo de pixel JavaScript

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

Para a representação JSON de eventos do usuário, consulte userEvents em a 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

É possível usar o userEvents.write método para enviar eventos do usuário diretamente para a API do 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 a representação JSON de eventos do usuário, consulte userEvents na referência da API.

Se você estiver registrando eventos do 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 do Gemini Enterprise.C#

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser 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 do Gemini Enterprise.Go

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

Antes de testar este exemplo, siga as instruções de configuração 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 Java do Gemini Enterprise.

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser 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 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 Python do Gemini Enterprise.

Para autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser 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 autenticar no Gemini Enterprise, configure o Application Default Credentials. Se quiser 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