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 de 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

Sugestões gerais para registar eventos do utilizador

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 conclusão da importação do catálogo.

    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 com junção bem-sucedida são usados para a preparação. Por isso, certifique-se de que volta a juntar-se a 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, é rejeitado 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 tipo de evento é denominado "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 um formulário seguro de um identificador exclusivo 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

Formas de transmitir eventos do utilizador

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

Registe eventos de utilizador com um píxel de JavaScript

O exemplo seguinte regista um detail-page-view UserEvent através de um pixel JavaScript.

<script type="text/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);
})();

</script>

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 ID de cliente do Google Analytics faz apenas parte do nome completo do cookie _ga (por exemplo, o ID de cliente 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.

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

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;
}

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.

Verifique se:

  1. Se estiver a importar eventos de compra, que alguns modelos da Pesquisa do Vertex AI para comércio eletrónico requerem, os seus relatórios de eventos incluem códigos de moeda. Consulte os parâmetros de eventos purchase na documentação do Google Analytics.

  2. Se planeia importar eventos search, os seus relatórios de eventos incluem consultas de pesquisa.

    A importação de eventos search é suportada, mas os eventos search não são mapeados a partir do Google Analytics 4 da mesma forma que outros tipos de eventos , porque o Google Analytics 4 não suporta nativamente o tipo de evento search do Vertex AI Search for commerce. Durante a importação, os searcheventos são criados a partir do Google Analytics 4 combinando informações do view_item_list e dos parâmetros de eventos search_term.

    Consulte os parâmetros de eventos search na documentação do Google Analytics.

Registe os seus eventos do Google Analytics 4

Registe um evento do utilizador incluindo dados JSON não processados codificados por URL para o evento na sua chamada ao método userEvents.collect.

Para o parâmetro prebuilt_rule, use o valor ga4_bq.

Para facilitar a leitura, o exemplo seguinte de utilização da chamada userEvents.collect define primeiro GA4_EVENT como uma variável que contém os dados JSON não processados para um evento de exemplo. A chamada userEvents.collect no exemplo codifica então os dados do evento em URL usando a variável GA4_EVENT.

  1. Para facilitar a codificação de URLs mais tarde, pode definir o GA4_EVENT como uma variável com dados de eventos. Este exemplo mostra um evento add-to-cart.

    GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

  2. Faça uma chamada userEvents.collect que inclua os dados JSON não processados codificados por URL de um evento do utilizador:

    curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

Registe eventos de utilizadores com o Gestor de Etiquetas da Google

O Gestor de Etiquetas oferece uma forma de gerir e testar várias etiquetas sem muitas alterações de código do lado do servidor no seu site.

Algumas decisões que toma durante a configuração dependem de estar a usar o Google Analytics e o Google Analytics Ecommerce. O comércio eletrónico do Google Analytics pode ser implementado através do Google Analytics 4 ou do Comércio eletrónico otimizado. A etiqueta do Cloud Retail suporta ambas.

O Google Analytics nem o Google Analytics Ecommerce são necessários. Se não os usar, pode configurar a variável - comércio eletrónico (para usar o esquema de comércio eletrónico do GA4) ou a variável - Cloud Retail (para usar o esquema da Vertex AI Search for commerce) quando criar a etiqueta Cloud Retail e preencher manualmente o código da camada de dados do seu site após a criação da etiqueta.

O comércio eletrónico do Google Analytics é uma configuração adicional do Google Analytics que transmite títulos, IDs, preços, detalhes de transações e outros dados de comércio eletrónico estruturados de produtos para o Google Analytics. A Vertex AI Search for commerce pode usar automaticamente a camada de dados do comércio eletrónico do Google Analytics. Por isso, se já tiver essa configuração, a configuração pode ser mais fácil. Se não tiver o comércio eletrónico do Google Analytics configurado para o Google Analytics, mas quiser usá-lo, consulte mais detalhes e instruções de configuração no guia do programador do GA4.

Use este procedimento único para configurar uma etiqueta do Cloud Retail no Gestor de Etiquetas para registar eventos de utilizadores.

Crie uma variável de ID de visitante

O valor visitorId destina-se ao acompanhamento de utilizadores. visitorId é normalmente um ID da sessão e é obrigatório para todos os eventos. Configure uma variável que defina os IDs das sessões como visitorId.

Se estiver a usar o Google Analytics, pode usar o ID do visitante do Google Analytics. Para configurar esta opção, use o seguinte procedimento para substituir o valor do ID do visitante da etiqueta do Cloud Retail. Isto mapeia o cookie original "_ga" para uma variável do Gestor de Etiquetas denominada "GA visitorId". Pode fazer o mesmo para qualquer cookie de ID de sessão; não tem de ser do Google Analytics.

Este procedimento pressupõe que está a usar o Google Analytics. Se não for o caso, pode usar outro cookie ou variável, ou obter o ID do visitante a partir da cloud_retailcamada de dados.

Para definir o valor visitorID para uma variável da etiqueta do Cloud Retail:

  1. No Gestor de Etiquetas, aceda ao separador Variáveis e clique em Nova para criar uma nova variável definida pelo utilizador.

  2. Atribua um nome à variável na parte superior da caixa de diálogo, como "visitorId do GA".

  3. Introduza as definições das variáveis.

    Pode usar o ID de cliente ou o ID do cookie para definir como a origem dos IDs dos visitantes. Use sempre uma origem de ID do visitante consistente quando carrega eventos de utilizadores históricos e em tempo real.

    ID do cliente

    No Google Analytics 4, esta variável é mapeada para o campo user_pseudo_id no esquema do BigQuery Export do Google Analytics 4.

    1. Defina o Tipo de variável como JavaScript personalizado.

    2. Introduza o seguinte script no campo JavaScript personalizado.

      Substitua "G-XXXXXX" pelo seu ID de acompanhamento do Google Analytics. Para encontrar o seu ID de acompanhamento, consulte O que aconteceu ao meu ID de acompanhamento?.

      function() {
 var tracker = ga.getByName('G-XXXXXX');
 return tracker.get('clientID');
}

    3. Clique em Guardar para guardar a variável.

    1. Escolha Cookie original como tipo de variável.

    2. No campo Nome do cookie, introduza _ga.

    3. Clique em Formatar valor, selecione Converter indefinido em… e introduza "" (uma string vazia).

    4. Clique em Guardar para guardar a variável.

      Isto mapeia o cookie original "_ga" para uma variável do Gestor de Etiquetas denominada "ID do visitante do GA".

Em seguida, crie uma etiqueta do Cloud Retail no Gestor de Etiquetas. Esta etiqueta vai usar a variável de ID de visitante que acabou de criar.

Crie uma etiqueta do Gestor de Etiquetas da Google

Configure uma etiqueta no Gestor de Etiquetas para enviar informações de eventos do utilizador para o Vertex AI Search for commerce.

  1. Inicie sessão no Gestor de Etiquetas e selecione o contentor do seu site.

  2. Aceda ao separador Etiquetas e clique em Nova para adicionar uma nova etiqueta.

  3. Atribua um nome à etiqueta na parte superior do painel (o marcador de posição é Variável sem título), como "Vertex AI Search for commerce".

  4. Clique em Configuração da etiqueta e escolha a etiqueta Cloud Retail para abrir o painel de configuração da etiqueta.

  5. Introduza a chave da API.

    Use a chave que criou quando configurar o Vertex AI Search para comércio.

    As suas chaves da API estão disponíveis na página APIs e serviços > Credenciais na Google Cloud console.

  6. Introduza o número do projeto do Google Cloud projeto onde a Pesquisa do Vertex AI para comércio está ativada.

    O número do projeto está disponível no Google Cloud painel de controlo da consola.

  7. Para o campo Origem de dados de eventos do utilizador:

    • Camada de dados (recomendado): selecione se a sua implementação for uma das seguintes:

      • Tem o comércio eletrónico do Google Analytics implementado através do Gestor de Etiquetas. Reutilize a camada de dados como origem de dados de eventos em vez de preencher uma nova. Isto usa o esquema do Google Analytics 4, se estiver presente. Caso contrário, usa o Comércio eletrónico otimizado do UA. Com esta origem de dados, só pode registar eventos add-to-cart, purchase-complete, detail-page-view e search. Os eventos search são registados através de impressões de comércio eletrónico combinadas com consultas de pesquisa (consulte o artigo Crie uma variável de consulta de pesquisa).

      • Está a usar o comércio eletrónico do Google Analytics e pode preencher manualmente o código da camada de dados. Consulte o guia do programador do Gestor de Etiquetas.

    • Variável, Cloud Retail: selecione esta opção para preencher uma variável do Gestor de Etiquetas com os campos necessários para o Vertex AI Search para comércio. Pode escolher esta opção se não estiver a usar o comércio eletrónico do Google Analytics ou se o comércio eletrónico do Google Analytics não tiver os dados necessários para a pesquisa da Vertex AI para comércio. Se estiver a mudar para esta origem a partir da opção Camada de dados - Cloud Retail antiga, também deve criar uma variável da camada de dados com a chave cloud_retail e associá-la a esta opção Variável - Cloud Retail.

    • Variável, comércio eletrónico: selecione se não estiver a usar o comércio eletrónico do Google Analytics na camada de dados e não conseguir preencher manualmente o código da camada de dados, mas quiser continuar a usar o esquema de comércio eletrónico do Google Analytics. Isto também é útil se tiver o comércio eletrónico do Google Analytics implementado, mas quiser aumentar ou alterar os valores na camada de dados. Em seguida, pode reunir esses valores numa variável personalizada no formato do esquema de comércio eletrónico do Google Analytics que pode ser usada pela etiqueta do Cloud Retail.

      No campo Leia dados de comércio eletrónico da variável do utilizador apresentado, escolha uma variável. Isto permite que a Vertex AI Search for commerce leia dados de eventos do utilizador de comércio eletrónico do Google Analytics a partir de uma variável personalizada que criar.

      A variável deve corresponder ao formato documentado no guia do programador do GA4. Para criar uma variável no formato correto, pode usar o criador de objetos de comércio eletrónico melhorado, um modelo de variável personalizada da galeria de modelos da comunidade do Gestor de Etiquetas. Os modelos da comunidade não são mantidos pela Google. Para usar este modelo, consulte a página da galeria do criador de objetos do comércio eletrónico otimizado para ver documentação e outros recursos.

  8. Clique no botão + Substituir um valor na mensagem UserEvent.

  9. Para o Seletor de campos, selecione visitorId como o campo e, para o Valor do campo, selecione a nova variável de ID do visitante que criou em Crie uma variável de ID do visitante.

  10. Clique em Guardar.

    A sua etiqueta do Cloud Retail é criada.

Opções de origens de dados antigas

Anteriormente, a camada de dados – comércio eletrónico e a camada de dados – Cloud Retail estavam disponíveis como opções de origem de dados. Estas opções antigas não estão disponíveis em novas etiquetas. Se mudar uma etiqueta existente para uma nova origem de dados, pré-visualize-a com o Gestor de Etiquetas para a validar antes da implementação. Quando muda:

  • Se usou a opção Camada de dados – Comércio eletrónico, pode mudar para a opção Camada de dados. Isto usa o esquema do Google Analytics 4, se estiver presente. Caso contrário, usa o Comércio eletrónico otimizado do UA.

  • Se usou Camada de dados – Cloud Retail, mude para a opção Variável – Cloud Retail. Crie uma variável da camada de dados com a chave cloud_retail e associe-a à opção Variável – Cloud Retail.

Seguinte:

Crie uma variável de consulta de pesquisa

Se estiver a usar a pesquisa, pode criar uma variável no Gestor de Etiquetas para consultas de pesquisa e anexá-la à etiqueta do Cloud Retail. Isto permite que o Vertex AI Search para comércio receba consultas de pesquisa do Analytics.

Os tipos de variáveis que cria dependem da sua origem de dados de eventos do utilizador.

  • Variável – Comércio eletrónico ou a camada de dados com o esquema de comércio eletrónico do Google Analytics: crie uma variável de URL ou de elemento DOM no Gestor de Etiquetas e anexe-a à etiqueta do Cloud Retail. Além disso, ative a opção para que a sua etiqueta use impressões de comércio eletrónico do Google Analytics para criar eventos de pesquisa.
  • Variável – Cloud Retail ou uma camada de dados preenchida manualmente: crie uma variável de URL ou de elemento DOM no Gestor de Etiquetas e anexe-a à sua etiqueta do Cloud Retail. Para determinar se o tipo de um evento de utilizador é search, também tem de:
    • Crie uma variável de tipo constante para os tipos de eventos de pesquisa e anexe-a à sua etiqueta.
    • Defina o tipo de evento de pesquisa na camada de dados ou na variável do Cloud Retail.

Crie e anexe uma variável do Gestor de Etiquetas para consultas de pesquisa

Se usar a pesquisa, pode criar um URL, um elemento DOM ou uma variável JavaScript personalizada que vai ser preenchida com as consultas de pesquisa introduzidas no seu site.

Em alternativa a este procedimento, pode configurar a camada de dados para fornecer informações sobre a consulta de pesquisa. No entanto, pode optar por usar variáveis do Gestor de Etiquetas se não tiver acesso à camada de dados ou preferir não configurar a camada de dados.

Pode criar uma variável do tipo URL, uma variável do tipo elemento DOM ou uma variável de JavaScript (página) personalizada. Qual cria e como o configura, depende da implementação do seu site:

  • Uma variável de URL recebe consultas de pesquisa dos URLs de resultados da pesquisa do seu site. Use esta variável se o seu site incluir a string de consulta no URL dos respetivos resultados da pesquisa.
  • Uma variável de elemento DOM obtém as informações da consulta de pesquisa do Document Object Model (DOM) do seu site. Não precisa de editar o DOM para usar esta variável. No entanto, deve conseguir ler e compreender o DOM para configurar corretamente esta variável.
  • Uma variável de JavaScript personalizado devolve dados formatados por uma função JavaScript. Isto é útil se tiver dados existentes que quer formatar no esquema do Cloud Retail ou de comércio eletrónico.

Primeiro, crie uma variável do Gestor de Etiquetas do tipo URL, elemento DOM ou JavaScript personalizado:

  1. No Gestor de Etiquetas, aceda ao separador Variáveis e clique em Nova para criar uma nova variável definida pelo utilizador.

  2. Atribua um nome à variável na parte superior da caixa de diálogo, como "search_variable".

  3. Introduza as definições das variáveis:

    Tipo de URL

    1. Defina o Tipo de variável como URL.

    2. Defina o Tipo de componente como Consulta.

    3. Se especificar uma chave de consulta, defina-a como a chave que precede a consulta de pesquisa no seu URL.

      Por exemplo, se o URL for http://example.com/?q=shoes, a chave de consulta é q. Neste exemplo, o valor da variável seria definido como shoes.

    Tipo de elemento DOM

    1. Defina o Tipo de variável como Elemento DOM.

    2. Defina o Método de seleção e introduza o ID do elemento ou o seletor de elementos da consulta de pesquisa.

      Esta definição depende de o seu site usar um ID do elemento ou um seletor CSS para identificar a consulta de pesquisa.

    3. Se especificar um atributo, defina-o como o atributo que contém o termo de consulta de pesquisa.

      Por exemplo, se a consulta de pesquisa no seu DOM for <id="search" value="shoes">, o atributo seria value. Neste exemplo, o valor da variável seria definido como shoes.

    Tipo de JavaScript personalizado

    1. Defina o Tipo de variável como JavaScript personalizado.

    2. Substitua as variáveis no código seguinte e cole-o no painel JavaScript personalizado.

    3. No painel JavaScript personalizado, adicione código JavaScript que devolva um evento de pesquisa no esquema de retalho.

      O seguinte código de exemplo transforma os dados numa variável Ecommerce Items existente na matriz productDetails usada pelo esquema do Vertex AI Search for commerce e devolve um evento completo. Para usar este código, substitua Ecommerce Items, Search Query e Search Filter por variáveis na implementação do Gestor de Etiquetas.

      function () {

  var retail;
  var items = [];

  for (var i = 0; i < {{Ecommerce Items}}.length; i++) {
    var item = {'product':
                {
                  'id': {{Ecommerce Items}}[i].item_id
                }
               };

    items.push(item);
  }

  retail = {
    'eventType': 'search',
    'searchQuery': '{{Search Query}}',
    'filter': '{{Search Filter}}',
    'productDetails': items
  }

  return retail;
}

  4. Clique em Guardar para guardar a variável.

Em seguida, anexe a variável à etiqueta do Cloud Retail:

  1. Na página Gestor de Etiquetas, Etiquetas, clique na etiqueta de retalho do Google Cloud para a editar.

  2. Se a origem de dados de eventos do utilizador da sua etiqueta for Variável – Comércio eletrónico ou usar a camada de dados com o esquema de comércio eletrónico do Google Analytics, selecione a caixa de verificação Usar impressões de comércio eletrónico otimizado para criar eventos de pesquisa.

    Isto permite que o Vertex AI Search para comércio determine se o tipo de um evento do utilizador é search com base nos dados de pesquisa que recebe desta etiqueta.

  3. Na secção Dados de eventos do utilizador, clique no botão + Substituir um valor na mensagem UserEvent.

  4. Selecione searchQuery no seletor de campos e defina a variável de consulta de pesquisa como o valor do campo.

  5. Guarde a etiqueta.

Seguinte:

Crie e anexe uma variável constante

Pode usar este procedimento se tiver escolhido Variável – Cloud Retail ou uma camada de dados preenchida manualmente como a origem do evento do utilizador para a etiqueta do Cloud Retail.

A criação de uma variável de tipo constante para eventos de pesquisa e a sua definição como uma substituição de eventos de utilizador na etiqueta do Cloud Retail permite que a Vertex AI Search for commerce determine se o tipo de um evento de utilizador é search.

Em alternativa a este procedimento, pode especificar o tipo de evento do utilizador search usando a camada de dados ou a variável do Cloud Retail que serve como origem do evento da etiqueta. Caso contrário, siga estes passos para definir o tipo de evento.

Primeiro, crie uma variável do tipo constante:

  1. No Gestor de Etiquetas, aceda ao separador Variáveis e clique em Nova para criar uma nova variável definida pelo utilizador.

  2. Atribua um nome à variável na parte superior da caixa de diálogo, como "search_constant".

  3. Defina o Tipo de variável como Constante.

  4. Introduza search no campo Valor

  5. Clique em Guardar para guardar a variável.

Em seguida, anexe a variável à etiqueta do Cloud Retail:

  1. Na página Gestor de Etiquetas, Etiquetas, clique na etiqueta de retalho do Google Cloud para a editar.

  2. Na secção Dados de eventos do utilizador, clique no botão + Substituir um valor na mensagem UserEvent.

  3. Selecione eventType no seletor de campos e defina a variável de consulta de pesquisa como o valor do campo.

  4. Guarde a etiqueta.

Em seguida, crie acionadores de eventos para a sua etiqueta.

Crie acionadores de eventos para a etiqueta do Gestor de Etiquetas

Crie acionadores para todos os tipos de eventos dos utilizadores que os modelos de pesquisa da Vertex AI para comércio vão usar.

As etiquetas do Gestor de Etiquetas têm de ter acionadores que controlam quando a etiqueta deve ser "acionada" no site. Os acionadores ouvem quando ocorrem eventos (como um utilizador ver a página inicial ou adicionar um artigo ao carrinho) e pedem à sua etiqueta para enviar essas informações de eventos do utilizador para a Vertex AI Search for commerce.

O Gestor de Etiquetas fornece alguns acionadores padrão. Por exemplo, o evento Window Loaded é um acionador para eventos detail-page-view. Para ver detalhes sobre cada tipo, consulte Tipos de acionadores na documentação do Gestor de Etiquetas.

Normalmente, define a etiqueta para ser acionada quando um utilizador vê qualquer página que tenha os eventos necessários para a Vertex AI Search for commerce (como a página inicial, as páginas de detalhes do produto, as páginas do carrinho ou a página de pagamento concluído). Nestes casos, a etiqueta deve ser acionada após o carregamento da página, para que os cookies estejam disponíveis e todas as variáveis da camada de dados sejam preenchidas. Para o fazer, defina os acionadores para serem acionados em Janela carregada ou DOM preparado.

Pode ter de acionar a etiqueta quando uma ação é realizada em vez de no carregamento da página (por exemplo, se um utilizador adicionar um artigo a um carrinho não forçar a atualização da página). Nestes casos, pode configurar essa ação de clique no seu site para enviar atualizações em simultâneo para a camada de dados e associar o acionador a essa ação.

Por exemplo, se criou um acionador para eventos add-to-cart, pode escolher o tipo de acionador Clique - Apenas links e defini-lo para ser acionado no ID do clique (neste exemplo, addtocart). Em seguida, configuraria o link addtocart no seu site para também atualizar a camada de dados com novos valores quando for clicado:

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

Para alguns eventos de utilizador, tem de criar um acionador personalizado. Geralmente, cria um acionador personalizado no Gestor de Etiquetas com o nome do evento do utilizador. Se não conseguir modificar o código do frontend, pode criar um acionador personalizado através de macros de JavaScript. Para mais informações sobre acionadores personalizados, consulte o artigo Acionador de eventos personalizados.

Use os procedimentos seguintes para criar acionadores no Gestor de Etiquetas:

Crie novos acionadores para a etiqueta do Gestor de Etiquetas

Se não usar o comércio eletrónico do Google Analytics, crie novos acionadores de eventos para quaisquer eventos de utilizador de que os seus modelos do Vertex AI Search for commerce precisem. Em seguida, associe os novos acionadores à etiqueta do Cloud Retail que criou no Gestor de Etiquetas.

Antes de iniciar os passos seguintes, certifique-se de que criou uma etiqueta do Cloud Retail no Gestor de Etiquetas. Consulte o artigo Crie uma etiqueta do Gestor de Etiquetas.

Primeiro, crie os acionadores. Repita este procedimento para todos os eventos do utilizador que os modelos do Vertex AI Search for commerce requerem:

  1. Na página Gestor de Etiquetas, Acionadores, clique em Novo > Configuração do acionador.

  2. Escolha o tipo de acionador que se aplica ao evento do utilizador para o qual está a criar um acionador.

  3. Guarde o acionador.

Em seguida, associe os novos acionadores à etiqueta Cloud Retail. Este é um procedimento único:

  1. Na página Gestor de Etiquetas, Etiquetas, clique na etiqueta de retalho do Google Cloud para a editar.

  2. Clique em Acionadores, selecione os novos acionadores e clique em Adicionar.

  3. Guarde a etiqueta.

Em seguida, pré-visualize a etiqueta e configure a monitorização de erros de registo de eventos e outros problemas para garantir que os dados continuam a ser recebidos com êxito.

Se estiver a usar a cloud_retailcamada de dados como origem de eventos do utilizador, certifique-se de que também configura a camada de dados.

Reutilize acionadores de comércio eletrónico do Google Analytics

Se implementou o comércio eletrónico do Google Analytics através do Gestor de Etiquetas, reutilize os acionadores de eventos do comércio eletrónico do Google Analytics para a pesquisa da Vertex AI para comércio.

Com esta origem de dados, só pode registar eventos add-to-cart, purchase-complete, detail-page-view e search. Os eventos search são registados através de impressões de comércio eletrónico combinadas com consultas de pesquisa (consulte o artigo Crie uma variável de consulta de pesquisa).

A tabela seguinte mostra como os eventos de comércio eletrónico e de comércio eletrónico melhorado do Google Analytics são mapeados para eventos de comércio da Vertex AI Search.

Google Analytics 4 Comércio eletrónico otimizado Vertex AI Search para comércio
add_to_cart add add-to-cart
purchase purchase purchase-complete
view_item detail detail-page-view
view_item_list ou view_search_results impressions search (se combinado com o campo searchQuery)

Antes de iniciar estes passos, certifique-se de que:

  • Configurou uma etiqueta no Gestor de Etiquetas do tipo Google Analytics – Evento do GA4 e ativou o comércio eletrónico melhorado ou o GA4 na mesma. Consulte a documentação do Gestor de Etiquetas e o guia do programador do GA4 para ver detalhes.
  • Configurou a etiqueta do comércio eletrónico otimizado ou do GA4 no Gestor de Etiquetas para acionar os eventos do utilizador que planeia registar para a Vertex AI Search for commerce.
  • Criou uma etiqueta do Cloud Retail no Gestor de Etiquetas com "Camada de dados" ou "Variável – Comércio eletrónico" como origem de dados de eventos de utilizador (consulte o artigo Crie uma etiqueta do Gestor de Etiquetas).

Para reutilizar acionadores de comércio eletrónico do Google Analytics:

  1. Na página Etiquetas do Gestor de Etiquetas, clique na etiqueta de comércio eletrónico do Google Analytics (tipo Google Analytics – Evento do GA4) para a editar.

  2. Em Definições avançadas > Sequência de etiquetas, selecione Acionar uma etiqueta depois do acionamento de <nome da etiqueta do GA4 ou do comércio eletrónico melhorado>.

  3. Selecione a etiqueta do Cloud Retail como a etiqueta de limpeza.

    Selecione Não acionar <nome da etiqueta do Cloud Retail> se <nome da etiqueta do Comércio eletrónico otimizado ou do GA4> falhar ou estiver em pausa.

  4. Guarde a etiqueta.

Em seguida, pré-visualize a etiqueta e configure a monitorização de erros de registo de eventos e outros problemas para garantir que os dados continuam a ser recebidos com êxito.

Se estiver a usar a cloud_retailcamada de dados como origem de eventos do utilizador, certifique-se de que também configura a camada de dados.

Use a camada de dados cloud_retail com o Gestor de Etiquetas

Se criou a etiqueta do Cloud Retail no Gestor de Etiquetas para usar a cloud_retail camada de dados como a origem do evento do utilizador, configure a dataLayer variável no HTML de origem, conforme descrito no guia do programador do Gestor de Etiquetas.

Acerca da camada de dados

A maioria das etiquetas do Gestor de Etiquetas requer dados que mudam consoante o utilizador ou a página (como IDs dos utilizadores ou IDs dos produtos). Para a etiqueta Cloud Retail, esses dados têm de ser expostos de forma estruturada através de uma camada de dados para que o Gestor de Etiquetas os possa usar.

A camada de dados é um objeto JavaScript que é normalmente adicionado a uma página através de código do lado do servidor ou, no frontend, através de HTML ou um modelo. Se uma página estiver configurada com a camada de dados, vai conter algum código semelhante ao seguinte:

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

Este código cria um objeto dataLayer e atribui-lhe a estrutura cloud_retail como um elemento de matriz.

Campos obrigatórios na cloud_retail camada de dados

O artigo Acerca dos eventos do utilizador lista todos os campos obrigatórios e exemplos para os tipos de eventos que devem ser transmitidos para a camada de dados cloud_retail.

O código ou os modelos do lado do servidor devem ter as etiquetas de script corretas em cada página a partir da qual quer enviar eventos. Depois de o objeto dataLayer ser preenchido corretamente em cada página, deve conseguir testar a etiqueta do Cloud Retail.

Alguns campos, como visitorId, são necessários para a mensagem UserEvent, mas podem não estar disponíveis quando preenche a camada de dados. Por exemplo, o valor visitorId pode ser derivado do cookie do utilizador ou o valor experimentIds do framework de testes A/B. Neste caso, use uma variável para substituir o campo na etiqueta do Gestor de Etiquetas.

Pode substituir os seguintes campos:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Para saber como substituir um campo UserEvent no Gestor de Etiquetas, consulte o artigo Definir o campo visitorID no Gestor de Etiquetas, que explica como substituir o valor do campo visitorId por uma variável definida pelo utilizador.

O exemplo seguinte mostra a camada de dados que tem de ser incluída na sua página para um detail-page-view UserEvent através do Gestor de Etiquetas:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Pré-visualize a etiqueta do Gestor de Etiquetas

O modo de pré-visualização do Gestor de Etiquetas permite-lhe testar novas etiquetas antes de as publicar no seu site publicado.

Para ver mais detalhes sobre o modo de pré-visualização, consulte a documentação do Gestor de Etiquetas para o modo de pré-visualização.

Use o procedimento seguinte para confirmar se a etiqueta está a ser acionada corretamente.

  1. Na página Vista geral do Gestor de Etiquetas, clique em Pré-visualizar.

    O modo de pré-visualização do Gestor de Etiquetas abre num novo separador do navegador.

  2. Introduza as informações do seu site e clique em Iniciar para iniciar o Assistente de Etiquetas.

    No separador do navegador atual, o Assistente de Etiquetas é iniciado e o seu site é aberto num novo separador.

  3. No seu site, visite qualquer página onde a etiqueta de retalho do Google Cloud deve ser acionada.

  4. Confirme que o Assistente de Etiquetas lista a etiqueta do Cloud Retail no separador Etiquetas na secção Etiquetas acionadas.

  5. No Assistente de Etiquetas, aceda ao separador Camada de dados e verifique se os valores corretos da camada de dados cloud_retail ou de comércio eletrónico são apresentados.

Verifique se existem erros de etiquetas

Se alguns campos estiverem incorretos ou em falta quando pré-visualiza a etiqueta, esta também devolve normalmente um erro, a menos que não esteja a ser acionada.

Pode verificar a página Monitorização na consola de pesquisa de comércio para ver se existem erros. Esta página regista a maioria dos erros, exceto os erros de sintaxe, que normalmente só aparecem nos resultados dos pedidos.

Pode usar os passos seguintes para usar as Chrome DevTools para verificar se existem erros gerados, incluindo erros de sintaxe.

  1. Ative o modo de pré-visualização no Gestor de Etiquetas para o seu site num navegador Chrome e visite qualquer página onde a etiqueta do Cloud Retail deve ser acionada.

  2. Com o modo de pré-visualização aberto, abra as DevTools e clique no separador Rede.

  3. Atualize a página.

  4. Nas DevTools, pesquise userEvent.

    O separador Rede apresenta o evento userEvent:collect e o respetivo código de estado.

    • Uma resposta 200 indica que a etiqueta está em bom estado.
    • Outras respostas, como um erro 400 e o realce do evento a vermelho, indicam que é necessária a depuração.

  5. Clique duas vezes no nome do evento para executar o pedido e mostrar uma resposta completa com mais informações sobre o erro.

    Por exemplo, pode ver um erro 400 com a mensagem "'visitorId' é obrigatório e não pode estar vazio", o que indica que visitorId não foi definido corretamente.

  6. Se não for acionado nenhum userEvent, verifique se existem erros de sintaxe no separador Consola das DevTools.

Registe eventos de utilizadores com a etiquetagem do lado do servidor

A etiquetagem do lado do servidor permite-lhe implementar um único contentor do lado do servidor com muitos clientes a jusante. Isto cria uma única fonte de verdade do lado do cliente, com muitos consumidores do lado do servidor. Esta arquitetura transfere a carga da Web para o servidor, o que a torna desejável para os utilizadores que querem maximizar o desempenho dos respetivos Websites.

Outra vantagem da etiquetagem do lado do servidor é que uma única etiqueta do lado do servidor também pode suportar muitos clientes a montante, por exemplo, a Web e dispositivos móveis. Saiba como configurar a etiquetagem do lado do servidor.

O Vertex AI Search para comércio fornece a sua própria etiqueta do lado do servidor antiga.

A etiqueta do lado do servidor do Cloud Retail requer e aceita parâmetros semelhantes aos da etiqueta da Web do Cloud Retail, como:

  • Número do projeto
  • Chave da API (para autenticação)
  • Substituições de campos principais, como visitorId e searchQuery

A principal diferença entre a versão de servidor e a versão Web da etiqueta Cloud Retail é que não pode definir a origem de dados. A origem de dados das etiquetas de servidor é uma stream de dados enviada a partir da etiqueta Google no esquema do GA4.

Configure a etiqueta do Cloud Retail

Veja os eventos gravados

Veja as métricas de integração de eventos no separador Eventos na consola de pesquisa para comércio página Dados. Esta página mostra todos os eventos escritos ou importados no último ano. As métricas podem demorar até 24 horas a aparecer após a ingestão de dados bem-sucedida.

Aceda à página Dados

O que se segue?