Registe eventos de utilizador em tempo real

Esta página descreve como registar eventos de utilizadores em tempo real. O Vertex AI Search for commerce usa eventos do utilizador em tempo real para gerar recomendações e resultados da pesquisa. Registar o maior número possível de tipos de eventos do utilizador com informações válidas sobre o produto aumenta a qualidade dos resultados.

Os procedimentos de gravação nesta página aplicam-se às recomendações e à pesquisa. Depois de registar os dados, ambos os serviços podem usar esses eventos, pelo que não precisa de carregar os mesmos dados duas vezes se usar ambos os serviços.

Antes de começar

Antes de registar eventos do utilizador, deve ter:

  • Um Google Cloud projeto criado com a autenticação configurada.

  • Uma chave da API válida (para o píxel de JavaScript ou o Gestor de Etiquetas) ou uma conta de serviço válida com a função de editor de retalho atribuída se usar a API para escrever diretamente.

Componentes obrigatórios

Comece a gravar

Faça stream de eventos de utilizadores em direto

Embora a importação em massa e o streaming em tempo real ofereçam mecanismos eficazes para a carregamento de eventos do utilizador na Vertex AI Search for commerce, o streaming em tempo real apresenta várias vantagens subtis:

  • Escalabilidade imediata: o streaming em tempo real elimina frequentemente a necessidade de pipelines de extração, transformação e carregamento (ETL) adicionais, o que facilita a escalabilidade à medida que os volumes de eventos aumentam. Normalmente, a infraestrutura consegue lidar com o crescimento de forma orgânica sem ajustes importantes.

  • Integração com o Google Analytics (GA4): os Websites instrumentados com o GA4 podem usar o Gestor de Etiquetas da Google para capturar e transmitir eventos em tempo real para o Vertex AI Search for commerce, eliminando a necessidade de implementações de acompanhamento de eventos personalizados.

  • Chamadas diretas à API: os eventos em tempo real podem ser transmitidos diretamente a partir do front-end ou através de um servidor proxy com APIs REST, integrando todo o processo e reduzindo potenciais pontos de falha.

  • Medição de IEDs e relatórios de erros atualizados: o processamento mais rápido de eventos em tempo real traduz-se em medições de IEDs e relatórios de erros mais atuais. Isto permite uma identificação e uma resolução mais rápidas dos problemas.

  • Personalização em tempo real: ao capturar e processar eventos do utilizador em tempo real, a Vertex AI Search for commerce pode fornecer resultados de pesquisa personalizados com base no comportamento de navegação e compra recente.

Métodos de streaming de eventos de utilizadores em direto

Pode registar um evento do utilizador de várias formas:

Potenciais desvantagens do streaming em tempo real

As potenciais desvantagens da streaming em tempo real podem apresentar-se das seguintes formas:

  • Reingestão limitada: ao contrário das importações em massa, em que os dados podem ser preparados no BigQuery ou no Cloud Storage, os eventos em tempo real são difíceis de reingerir em caso de erros ou dados com formato incorreto. Isto requer mecanismos de validação robustos no ponto de carregamento para garantir a integridade dos dados.

  • Desafios com a análise personalizada: se for necessária uma análise personalizada dos dados de eventos, muitas vezes, é preciso exportar eventos para o BigQuery para processamento adicional. Isto pode tornar-se um gargalo para streams de eventos de grande volume, o que pode atrasar a análise e os relatórios.

  • Depuração retrospetiva e transferência de dados de eventos limitadas: o envio do evento diretamente sem preparação limita a capacidade de realizar qualquer análise forense retrospetiva nos eventos que já foram carregados. Outra potencial limitação é que a preparação dos modelos num ambiente inferior pode não ter eventos suficientes. Ter uma área de preparação para os dados de eventos (BigQuery ou Cloud Storage) permite-lhe também importar ou transferir os eventos noutros ambientes após transformações de dados menores.

Compreender estas nuances pode ajudar a tomar decisões informadas sobre a estratégia de carregamento de eventos de utilizador mais adequada às suas necessidades e prioridades específicas no ecossistema do Vertex AI Search for commerce.

Práticas recomendadas para registar eventos do utilizador

O Vertex AI Search para comércio requer dados de alta qualidade para gerar resultados de alta qualidade. Se os seus dados estiverem incompletos ou incorretos, a qualidade dos resultados é afetada.

Quando regista eventos do utilizador, certifique-se de que implementa as seguintes práticas recomendadas:

  • Se registar eventos do utilizador antes ou durante a importação do catálogo, associe novamente todos os eventos registados antes da importação do catálogo estar concluída.

    Pode importar o catálogo antes, depois ou ao mesmo tempo que regista eventos do utilizador. A execução destas tarefas em paralelo pode poupar tempo se o catálogo for grande e existirem muitos eventos de utilizador. Assim que a importação do catálogo estiver concluída, tem de usar a API para voltar a juntar eventos que foram carregados antes da conclusão da importação.

    A Vertex AI Search for commerce tenta juntar eventos de utilizador registados com metadados do catálogo de produtos quando o evento de utilizador é criado. Apenas os eventos associados com êxito são usados para a preparação. Por isso, certifique-se de que volta a associar todos os eventos registados antes de o catálogo ser completamente importado. Se um evento fizer referência a um artigo que não existe no catálogo, é ignorado ou não é associado aos produtos corretos. Da mesma forma, se importar eventos de utilizadores do passado, o catálogo tem de incluir todos os produtos a que fazem referência. Pode marcar os produtos mais antigos como OUT_OF_STOCK em vez de os remover do catálogo.

  • Mantenha o seu catálogo atualizado.

    Quando regista eventos do utilizador, o produto incluído no evento do utilizador está associado ao seu catálogo atual. Se registar um evento para um produto que não está no catálogo atual, não pode ser usado para preparar os seus modelos. Este é denominado evento "não associado". Se registou eventos antes de o catálogo ter sido completamente importado, tem de voltar a associar os eventos que foram registados durante a importação. É esperado ter alguns eventos não associados. No entanto, se a percentagem de eventos não associados atingir 5% ou mais do total de eventos de utilizadores, certifique-se de que o catálogo está atualizado, volte a associar os eventos que foram registados antes de o catálogo ser totalmente atualizado e investigue o motivo pelo qual os eventos não associados estão a ser criados.

    Pode ver os eventos não associados através da filtragem de eventos. Saiba mais.

  • Forneça o máximo de informações possível com os seus eventos de utilizador.

    Cada tipo de evento do utilizador tem informações diferentes que são necessárias e aceites. Para mais informações, consulte o artigo Acerca dos eventos do utilizador.

  • Configure alertas do Cloud Monitoring para saber se os seus processos de gravação de eventos do utilizador sofrem interrupções.

  • Para uma importação de eventos de utilizadores em massa, limite o tamanho dos dados que está a importar.

    Uma importação em massa de eventos de utilizadores pode demorar até 24 horas a ser concluída.

    O tamanho de cada ficheiro tem de ser igual ou inferior a 2 GB. Pode incluir, no máximo, 100 ficheiros numa única solicitação de importação. Uma abordagem consiste em importar apenas os eventos de utilizador de um dia de cada vez.

  • Após uma importação em massa, reveja os relatórios de erros para garantir que os dados foram importados corretamente.

  • Quando importar dados de eventos do utilizador, inclua uma data/hora precisa para cada evento do utilizador e evite importar eventos do utilizador sequenciais com datas/horas idênticas.

    Indique a data/hora no campo eventTime no formato especificado pela RFC 3339.

  • Se importou eventos de utilizador incorretos, fale com o seu contacto do Vertex AI Search for commerce sobre como corrigir o problema.

  • Sempre que possível, mantenha os dados de eventos de utilizadores contínuos.

    As lacunas nos dados de eventos do utilizador podem reduzir a qualidade do modelo.

  • Use uma forma segura de um identificador único para manter os utilizadores anónimos para a Vertex AI Search for commerce e proteger a privacidade dos seus utilizadores. É responsável por ocultar IIP (informações de identificação pessoal), como endereços de email ou de casa, dos seus dados.

Tutorial sobre como escrever eventos do utilizador

Este tutorial mostra como registar eventos do utilizador através do método userEvents.write.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Registe eventos de utilizador com um píxel de JavaScript

Para páginas Web padrão (aplicações com várias páginas ou MPAs), o exemplo seguinte regista um detail-page-view UserEvent através de um pixel JavaScript.

  var user_event = {
    "eventType" : "detail-page-view",
    "visitorId": "visitor-id",
    "userInfo": {
        "userId": "user-id"
    },
    "experimentIds": "experiment-id",
    "productDetails": [
        {
          "product": {"id": "123"}
        }
    ]
  };
  var _gre = _gre || [];
  // Credentials for project.
  _gre.push(['apiKey', 'api-key']);
  _gre.push(['logEvent', user_event]);
  _gre.push(['projectId', 'project-id']);
  _gre.push(['locationId', 'global']);
  _gre.push(['catalogId', 'default_catalog']);
  (function() {
    var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
    gre.src = 'https://www.gstatic.com/retail/v2_event.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
  })();

Se importou eventos de utilizadores com o Google Analytics 360, defina visitorID como o ID do cliente do Google Analytics. Tenha em atenção que o Client-ID do Google Analytics faz apenas parte do nome completo do cookie _ga (por exemplo, o Client-ID 123456789.123456789 faz parte do cookie _ga GA1.3.123456789.123456789).

Segue-se um exemplo abreviado que mostra o formato para definir o ID do cliente num evento de utilizador. Substitua "G-XXXXXX" pelo seu ID de acompanhamento do Google Analytics.

    var tracker = ga.getByName('G-XXXXXX');
    var user_event = {
          "visitorId": tracker.get('clientId')
    };

Registe eventos do utilizador com o método userEvents.write

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 faculte o corpo do pedido adequado.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Envie eventos do utilizador em tempo real para recomendações a partir de aplicações Android ou iOS

Não existem bibliotecas de cliente Swift ou Kotlin específicas fornecidas nas origens para ligação direta a partir de apps para dispositivos móveis. No entanto, são recomendadas duas abordagens arquitetónicas principais para enviar eventos de utilizadores em tempo real para recomendações:

  1. Proxy de back-end (recomendado): configure um ponto final intermediário (como uma Google Cloud função ou o seu próprio servidor de back-end) para receber eventos da sua app para dispositivos móveis. Em seguida, escreva-os na API Retail através do método userEvents.write. Este procedimento mantém as credenciais da API fora do dispositivo móvel.

  2. Etiquetagem do lado do servidor (Gestor de Etiquetas da Google): use o Google Analytics 4 (GA4) na sua app para dispositivos móveis para transmitir eventos para um contentor do Gestor de Etiquetas da Google do lado do servidor, que os encaminha para a Retail API.

Se escolher o método de proxy de back-end, a sua app para dispositivos móveis envia dados para o seu servidor. O seu servidor usaria o seguinte código para enviar o evento para o Vertex AI Search for commerce.

Registe eventos do utilizador com o Google Analytics 4

Pode registar dados de eventos do utilizador do Google Analytics 4 no Vertex AI Search for commerce.

Verifique a sua origem de dados

Certifique-se de que os dados de eventos do utilizador que quer importar estão formatados corretamente.

Para ver uma tabela dos campos do Google Analytics 4 que a Vertex AI Search for commerce usa e a que campos da Vertex AI Search for commerce são mapeados, consulte os campos de eventos do utilizador do Google Analytics 4.

Para todos os parâmetros de eventos do Google Analytics, consulte a documentação de referência de eventos do Google Analytics.