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 usar recomendações de mídia, não é necessário importar eventos do 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 ingerir eventos do usuário, você melhora o a qualidade de suas recomendações, bem como a classificação de seus resultados de 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 em documentos que você ainda não foram importadas.

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 de no nível do repositório de dados. Isso permite que um determinado evento de usuário seja enviado ao repositório de dados ao qual 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 de usuários das seguintes maneiras:

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

Para a representação JSON para eventos de 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.

Registrar 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.
Veja um exemplo de pixel JavaScript para 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 nos navegadores deles.

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

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

Acessar a página Credenciais
No menu suspenso do projeto na parte de cima da página do console do Google Cloud, selecione seu projeto (o projeto pode já estar selecionado).
Clique em Criar credenciais e, em seguida, selecione Chave de API. Não adicione restrições de referenciadores. Algumas configurações de privacidade do usuário costumam não transmitir 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 um Restrição HTTP à sua chave de API para restringir o acesso ao serviço do Vertex AI Agent Builder às 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>

Registrar 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 aplicativo com vários repositórios de dados, o Google recomenda ingerir eventos no 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 API Vertex AI Agent Builder C# documentação de referência.

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 API Vertex AI Agent Builder Go documentação de referência.

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 API Vertex AI Agent Builder Ruby documentação de referência.

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

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

Criar uma chave de API

Exemplo de pixel JavaScript

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

REST

C#

Go

Java

Python

Ruby

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