Registe eventos de utilizador em tempo real

Esta página descreve como registar eventos do utilizador em tempo real.

Para os tipos de eventos de utilizador que pode registar, consulte o campo eventType do objeto userEvents. Ao carregar eventos do utilizador, pode melhorar a qualidade dos resultados. Por exemplo, os eventos do utilizador afetam a classificação dos resultados da pesquisa. Os resultados com taxas de cliques mais elevadas são promovidos, enquanto os resultados com taxas de cliques mais baixas são ocultados. Não registar eventos de utilizadores para documentos que ainda não importou.

Se estiver a usar uma app com várias origens de dados anexadas, a Google recomenda que carregue eventos de utilizadores ao nível da localização em vez de ao nível da origem de dados. Isto permite que um determinado evento do utilizador seja enviado para o armazenamento de dados ao qual está associado. Para carregar eventos de utilizador com documentos de dataStores diferentes ao nível da localização em vez de ao nível do armazenamento de dados, consulte o artigo userEvents.write.

Para importar eventos de utilizadores anteriores em massa, consulte o artigo Importe eventos de utilizadores anteriores.

Pode registar eventos do utilizador das seguintes formas:

Para a representação JSON dos eventos do utilizador, consulte userEvents na referência da API.

Antes de começar

Antes de importar eventos do utilizador:

Registe eventos de utilizadores em tempo real com um píxel JavaScript

Para registar eventos do utilizador com um píxel JavaScript:

  1. Crie uma chave da API para chamadas ao método userEvents.collect.
  2. Consulte o exemplo de píxel JavaScript para ver um exemplo de uma etiqueta JavaScript que recolhe eventos do utilizador.

Crie uma chave da API

É necessária uma chave da API se usar um pixel JavaScript para recolher eventos de utilizadores dos navegadores dos utilizadores.

Para criar uma chave da API para chamadas ao método userEvents.collect, siga estes passos:

  1. Na Google Cloud consola, aceda à página Credenciais.

    Credenciais

  2. No menu pendente do projeto na parte superior da Google Cloud página da consola, selecione o seu projeto (o projeto pode já estar selecionado).

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

    • Tome nota da chave da API gerada, que vai usar quando chamar o registo de eventos do utilizador.

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

Exemplo de pixel JavaScript

O exemplo seguinte regista um evento de utilizador view-item através de um pixel de JavaScript.

Para a representação JSON dos eventos do utilizador, consulte userEvents na referência da 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>

Registe eventos de utilizadores em tempo real com o método userEvents.write

REST

Pode usar o método userEvents.write para enviar eventos do utilizador diretamente para a API a partir do seu servidor de back-end.

Para registar eventos do utilizador, envie um pedido POST para o método userEvents.write e forneça o corpo do pedido adequado. Para a representação JSON de eventos de utilizador, consulte userEvents na referência da API.

Se estiver a registar eventos de utilizador ao nível da localização, use o ponto final 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" \
     --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/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:write"

C#

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

Para se autenticar no Gemini Enterprise, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Goinstruções de configuração no início rápido do Gemini Enterprise usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API GoGemini Enterprise.

Para se autenticar no Gemini Enterprise, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Gemini Enterprise usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API JavaGemini Enterprise.

Para se autenticar no Gemini Enterprise, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Gemini Enterprise usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API PythonGemini Enterprise.

Para se autenticar no Gemini Enterprise, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Rubyinstruções de configuração no início rápido do Gemini Enterprise usando bibliotecas cliente. Para mais informações, consulte a documentação de referência da API RubyGemini Enterprise.

Para se autenticar no Gemini Enterprise, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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