Esta página foi traduzida pela API Cloud Translation.

Registe eventos de utilizador em tempo real

Esta página descreve como registar eventos do utilizador em tempo real. Os eventos de utilizador são necessários para apps de multimédia. Se não usar apps de multimédia, não é necessário importar eventos do utilizador. No entanto, o registo de eventos do utilizador é recomendado para apps de pesquisa e recomendações personalizadas.

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 diferentes dataStores 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:

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

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:

Crie um repositório de dados e uma app.
Reveja o artigo Acerca dos eventos de utilizadores de multimédia ou Acerca dos eventos de utilizadores para ver os requisitos dos eventos de utilizadores.

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

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

Crie uma chave da API para chamadas ao método userEvents.collect.
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:

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

Credenciais
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).
Clique em Criar credenciais e, de seguida, selecione Chave de API. Não adicione restrições de referenciadores. 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.
Para aumentar a segurança, adicione uma restrição HTTP à sua chave da API para restringir o acesso ao serviço de aplicações de IA 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 ver a representação JSON dos 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#

Para mais informações, consulte a documentação de referência da API C# de aplicações de IA.

Para se autenticar em aplicações de IA, 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

Para mais informações, consulte a documentação de referência da API Go de aplicações de IA.


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 de aplicações de IA.

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 de aplicações de IA.

# 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 de aplicações de IA.

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