Esta página foi traduzida pela API Cloud Translation.

Registre eventos do usuário em tempo real

Esta página descreve como gravar eventos do usuário em tempo real. Os eventos do usuário são necessários para recomendações de mídia. Se você não usa recomendações de mídia, não é necessário importar eventos de usuário. No entanto, a gravação de eventos do usuário é recomendada para apps de pesquisa de mídia.

Para saber os tipos de evento do usuário que podem ser gravados, consulte o campo eventType do objeto userEvents. Ao processar eventos de usuário, você pode melhorar a qualidade das suas recomendações e 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 de documentos que você ainda não importou.

Se você estiver usando um app de pesquisa com vários repositórios de dados anexados, o Google recomenda que você ingira eventos de usuário no nível do local, em vez do repositório de dados. Isso permite que um determinado evento do usuário seja enviado para o repositório de dados a que ele está associado. Para importar eventos do usuário com documentos de diferentes dataStores no nível do local, em vez de no nível do repositório de dados, consulte userEvents.write.

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

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

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

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 os eventos do usuário para conferir os requisitos.

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

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

Crie uma chave de API para chamadas ao método userEvents.Collect.
Consulte Exemplo de pixel JavaScript para conferir um exemplo de uma tag JavaScript que coleta eventos do usuário.

crie uma chave de API

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

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

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

Credenciais
Na lista suspensa do projeto, na parte de cima da página do console do Google Cloud, selecione seu projeto (ele já pode estar selecionado).
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 a API de registro de eventos do usuário.
Para reforçar a segurança, adicione uma restrição HTTP à sua chave de API para restringir o acesso ao serviço Vertex AI Agent Builder 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 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>

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

REST

É possível usar o método userEvents.write 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ê tiver um app com vários armazenamentos de dados, o Google recomenda que você insira eventos no nível do local. Nesse caso, use o endpoint 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 mais informações, consulte a documentação de referência da API C# do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, 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

Para mais informações, consulte a documentação de referência da API Go do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para 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

Para mais informações, consulte a documentação de referência da API Java do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, 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

Para mais informações, consulte a documentação de referência da API Python do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, 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

Para mais informações, consulte a documentação de referência da API Ruby do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, 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

Registre eventos do usuário em tempo real

Antes de começar

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

crie uma chave de API

Exemplo de pixel JavaScript

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

REST

C#

Go

Java

Python

Ruby

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